Local photon instance

This R6 class is used to initialize and manage local photon instances. It can download and setup the Java, the photon executable, and the necessary ElasticSearch search index. It can start, stop, and query the status of the photon instance. It is also the basis for geocoding requests at it is used to retrieve the URL for geocoding.

ElasticSearch / OpenSearch

The standard version of photon uses ElasticSearch indices to geocode. These search indices can be self-provided by importing an existing Nominatim database or they can be downloaded from the Photon download server. Use nominatim = TRUE to indicate that no ElasticSearch indices should be downloaded. See vignette("nominatim-import", package = "photon") for details on how to import from Nominatim.

To enable structured geocoding, the photon geocoder needs to be built to support OpenSearch. Since photon 0.6.0, OpenSearch jar files are included in the photon releases. OpenSearch indices can also be downloaded, but do not support structured geocoding as of yet. To enable structured geocoding, indices have to be imported from an existing Nominatim database.

Super class

photon::photon -> photon_local

Public fields

path: Path to the directory where the photon instance is stored.
proc: process object that handles the external process running photon.

Methods

Method `new()`

Initialize a local photon instance. If necessary, downloads the photon executable, the search index, and Java.

Usage

photon_local$new(
  path,
  photon_version = NULL,
  country = NULL,
  date = "latest",
  exact = FALSE,
  section = NULL,
  opensearch = FALSE,
  overwrite = FALSE,
  quiet = FALSE
)

Arguments

path: Path to a directory where the photon executable and data should be stored. Defaults to a directory "photon" in the current working directory.
photon_version: Version of photon to be used. A list of all releases can be found here: https://github.com/komoot/photon/releases/. Ignored if jar is given. If NULL, uses the latest known version.
country: Character string that can be identified by countryname as a country. An extract for this country will be downloaded. If NULL, downloads a global search index.
date: Character string or date-time object used to specify the creation date of the search index. If "latest", will download the file tagged with "latest". If a character string, the value should be parseable by as.POSIXct. If exact = FALSE, the input value is compared to all available dates and the closest date will be selected. Otherwise, a file will be selected that exactly matches the input to date.
exact: If TRUE, exactly matches the date. Otherwise, selects the date with lowest difference to the date parameter.
section: Subdirectory of the download server from which to select a search index. If "experimental", selects a dump made for the master version of photon. If "archived", selects a dump made for an older version of photon. If NULL (or any arbitrary string), selects a dump made for the current release. Defaults to NULL.
opensearch: If TRUE, looks for an OpenSearch version of photon in the specified path. Opensearch-based photon supports structured geocoding queries but has to be built manually using gradle. Hence, it cannot be downloaded directly. If no OpenSearch executable is found in the search path, then this parameter is set to FALSE. Defaults to FALSE.
overwrite: If TRUE, overwrites existing jar files and search indices when initializing a new instance. Defaults to FALSE.
quiet: If TRUE, suppresses all informative messages.

Method `mount()`

Attach the object to the session. If mounted, all geocoding functions send their requests to the URL of this instance. Manually mounting is useful if you want to switch between multiple photon instances.

Usage

photon_local$mount()

Method `info()`

Retrieve metadata about the java and photon version used as well as the country and creation date of the Eleasticsearch search index.

Usage

photon_local$info()

Returns

A list containing the java version, the photon version, and if applicable, the spatial and temporal coverage of the search index.

Method `purge()`

Kill the photon process and remove the directory. Useful to get rid of an instance entirely.

Usage

photon_local$purge(ask = TRUE)

Arguments

ask: If TRUE, asks for confirmation before purging the instance.

Returns

NULL, invisibly.

Method `import()`

Import a Postgres Nominatim database to photon. Runs the photon jar file using the additional parameter -nominatim-import. Requires a running Nominatim database that can be connected to.

Usage

photon_local$import(
  host = "127.0.0.1",
  port = 5432,
  database = "nominatim",
  user = "nominatim",
  password = "",
  structured = FALSE,
  update = FALSE,
  enable_update_api = FALSE,
  languages = c("en", "fr", "de", "it"),
  countries = NULL,
  extra_tags = NULL,
  json = FALSE,
  timeout = 60,
  java_opts = NULL,
  photon_opts = NULL
)

Arguments

host: Postgres host of the database. Defaults to "127.0.0.1".
port: Postgres port of the database. Defaults to 5432.
database: Postgres database name. Defaults to "nominatim".
user: Postgres database user. Defaults to "nominatim".
password: Postgres database password. Defaults to "".
structured: If TRUE, enables structured query support when importing the database. This allows the usage of structured. Structured queries are only supported in the OpenSearch version of photon. See section "OpenSearch" above. Defaults to FALSE.
update: If TRUE, fetches updates from the Nominatim database, updating the search index without offering an API. If FALSE, imports the database an deletes the previous index. Defaults to FALSE.
enable_update_api: If TRUE, enables an additional endpoint /nominatim-update, which allows updates from Nominatim databases.
languages: Character vector specifying the languages to import from the Nominatim databases. Defaults to English, French, German, and Italian.
countries: Character vector specifying the country codes to import from the Nominatim database. Defaults to all country codes.
extra_tags: Character vector specifying extra OSM tags to import from the Nominatim database. These tags are used to augment geocoding results. Defaults to NULL.
json: If TRUE, dumps the imported Nominatim database to a JSON file and returns the path to the output file. Defaults to FALSE.
timeout: Time in seconds before the java process aborts. Defaults to 60 seconds.
java_opts: List of further flags passed on to the java command.
photon_opts: List of further flags passed on to the photon jar in the java command. See cmd_options for a helper function to import external Nominatim databases.

Method `start()`

Start a local instance of the Photon geocoder. Runs the jar executable located in the instance directory.

Usage

photon_local$start(
  host = "0.0.0.0",
  port = "2322",
  ssl = FALSE,
  timeout = 60,
  java_opts = NULL,
  photon_opts = NULL
)

Arguments

host: Character string of the host name that the geocoder should be opened on.
port: Port that the geocoder should listen to.
ssl: If TRUE, uses https, otherwise http. Defaults to FALSE.
timeout: Time in seconds before the java process aborts. Defaults to 60 seconds.
java_opts: List of further flags passed on to the java command.
photon_opts: List of further flags passed on to the photon jar in the java command. See cmd_options for a helper function to import external Nominatim databases.

Details

While there is a certain way to determine if a photon instance is ready, there is no clear way as of yet to determine if a photon setup has failed. Due to this, a failing setup is mostly indicated by the setup hanging after emitting a warning. In this case, the setup has to be interrupted manually.

Method `stop()`

Kills the running photon process.

Usage

photon_local$stop()

Method `download_data()`

Downloads a search index using download_searchindex.

Usage

photon_local$download_data(
  country = NULL,
  date = "latest",
  exact = FALSE,
  section = NULL
)

Arguments

country: Character string that can be identified by countryname as a country. An extract for this country will be downloaded. If NULL, downloads a global search index.
date: Character string or date-time object used to specify the creation date of the search index. If "latest", will download the file tagged with "latest". If a character string, the value should be parseable by as.POSIXct. If exact = FALSE, the input value is compared to all available dates and the closest date will be selected. Otherwise, a file will be selected that exactly matches the input to date.
exact: If TRUE, exactly matches the date. Otherwise, selects the date with lowest difference to the date parameter.
section: Subdirectory of the download server from which to select a search index. If "experimental", selects a dump made for the master version of photon. If "archived", selects a dump made for an older version of photon. If NULL (or any arbitrary string), selects a dump made for the current release. Defaults to NULL.

Method `remove_data()`

Removes the data currently used in the photon directory. This only affects the unpacked photon_data directory, not archived files.

Usage

photon_local$remove_data()

Method `is_running()`

Checks whether the photon instance is running and ready. The difference to $is_ready() is that $is_running() checks specifically if the running photon instance is managed by a process from its own photon object. In other words, $is_running() returns TRUE if both $proc$is_alive() and $is_ready() return TRUE. This method is useful if you want to ensure that the photon object can control its photon server (mostly internal use).

Usage

photon_local$is_running()

Returns

A logical of length 1.

Method `is_ready()`

Checks whether the photon instance is ready to take requests. This is the case if the photon server returns a HTTP 400 when sending a queryless request. This method is useful if you want to check whether you can send requests.

Usage

photon_local$is_ready()

Returns

A logical of length 1.

Method `get_url()`

Constructs the URL that geocoding requests should be sent to.

Usage

photon_local$get_url()

Returns

A URL to send requests to.

Method `get_logs()`

Retrieve the logs of previous photon runs.

Usage

photon_local$get_logs()

Returns

Returns a dataframe containing the run ID (rid, the highest number is the most recent run), a timestamp (ts), the thread, the log type (INFO, WARN, or ERROR), the class trace and the error message.

Method `clone()`

The objects of this class are cloneable with this method.

Usage

photon_local$clone(deep = FALSE)

Arguments

deep: Whether to make a deep clone.

Examples

if (has_java("11")) {
dir <- file.path(tempdir(), "photon")

# start a new instance using a Monaco extract
photon <- new_photon(path = dir, country = "Monaco")

# start a new instance with an older photon version
photon <- new_photon(path = dir, photon_version = "0.4.1")}
#> ℹ openjdk version "11.0.25" 2024-10-15
#> ℹ OpenJDK Runtime Environment Temurin-11.0.25+9 (build 11.0.25+9)
#> ℹ OpenJDK 64-Bit Server VM Temurin-11.0.25+9 (build 11.0.25+9, mixed mode)
#> ℹ Fetching photon 0.6.0.
#> ✔ Successfully downloaded photon 0.6.0. [475ms]
#> 
#> ℹ Fetching search index for Monaco, created on latest
#> ✔ Successfully downloaded search index. [899ms]
#> 
#> • Version: 0.6.0
#> • Coverage: Monaco
#> • Time: latest
#> ℹ openjdk version "11.0.25" 2024-10-15
#> ℹ OpenJDK Runtime Environment Temurin-11.0.25+9 (build 11.0.25+9)
#> ℹ OpenJDK 64-Bit Server VM Temurin-11.0.25+9 (build 11.0.25+9, mixed mode)
#> ℹ Fetching photon 0.4.1.
#> ✔ Successfully downloaded photon 0.4.1. [446ms]
#> 
#> ℹ A search index already exists at the given path. Download will be skipped
#> • Version: 0.4.1
#> • Coverage: Monaco
#> • Time: latest

if (FALSE) { # \dontrun{
# import a nominatim database using OpenSearch photon
# this example requires the OpenSearch version of photon and a running
# Nominatim server.
photon <- new_photon(path = dir, opensearch = TRUE)
photon$start(photon_options = cmd_options(port = 29146, password = "pgpass"))} # }

ElasticSearch / OpenSearch

Super class

Public fields

Methods

Public methods

Method new()

Usage

Arguments

Method mount()

Usage

Method info()

Usage

Returns

Method purge()

Usage

Arguments

Returns

Method import()

Usage

Arguments

Method start()

Usage

Arguments

Details

Method stop()

Usage

Method download_data()

Usage

Arguments

Method remove_data()

Usage

Method is_running()

Usage

Returns

Method is_ready()

Usage

Returns

Method get_url()

Usage

Returns

Method get_logs()

Usage

Returns

Method clone()

Usage

Arguments

Examples

Method `new()`

Method `mount()`

Method `info()`

Method `purge()`

Method `import()`

Method `start()`

Method `stop()`

Method `download_data()`

Method `remove_data()`

Method `is_running()`

Method `is_ready()`

Method `get_url()`

Method `get_logs()`

Method `clone()`