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.
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.
photon::photon -> photon_local
pathPath to the directory where the photon instance is stored.
procprocess object that handles the
external process running photon.
new()Initialize a local photon instance. If necessary, downloads the photon executable, the search index, and Java.
photon_local$new(
path,
photon_version = NULL,
country = NULL,
date = "latest",
exact = FALSE,
section = NULL,
opensearch = FALSE,
overwrite = FALSE,
quiet = FALSE
)pathPath to a directory where the photon executable and data should be stored.
photon_versionVersion 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 (Currently: 0.6.2).
countryCharacter string that can be identified by
countryname as a country. An extract for this
country will be downloaded. If "planet", downloads a global search
index.
dateCharacter 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.
exactIf TRUE, exactly matches the date. Otherwise,
selects the date with lowest difference to the date parameter.
sectionSubdirectory 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.
opensearchIf 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.
overwriteIf TRUE, overwrites existing jar files and
search indices when initializing a new instance. Defaults to
FALSE.
quietIf TRUE, suppresses all informative messages.
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.
photon_local$mount()
info()Retrieve metadata about the java and photon version used as well as the country and creation date of the Eleasticsearch search index.
photon_local$info()A list containing the java version, the photon version, and if applicable, the spatial and temporal coverage of the search index.
purge()Kill the photon process and remove the directory. Useful to get rid of an instance entirely.
photon_local$purge(ask = TRUE)askIf TRUE, asks for confirmation before purging the
instance.
NULL, invisibly.
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.
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
)hostPostgres host of the database. Defaults to "127.0.0.1".
portPostgres port of the database. Defaults to 5432.
databasePostgres database name. Defaults to "nominatim".
userPostgres database user. Defaults to "nominatim".
passwordPostgres database password. Defaults to "".
structuredIf 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.
updateIf 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_apiIf TRUE, enables an additional
endpoint /nominatim-update, which allows updates from
Nominatim databases.
languagesCharacter vector specifying the languages to import from the Nominatim databases. Defaults to English, French, German, and Italian.
countriesCharacter vector specifying the country codes to import from the Nominatim database. Defaults to all country codes.
extra_tagsCharacter vector specifying extra OSM tags to import
from the Nominatim database. These tags are used to augment geocoding
results. Defaults to NULL.
jsonIf TRUE, dumps the imported Nominatim database to
a JSON file and returns the path to the output file. Defaults to
FALSE.
timeoutTime in seconds before the java process aborts. Defaults to 60 seconds.
java_optsList of further flags passed on to the java
command.
photon_optsList 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.
start()Start a local instance of the Photon geocoder. Runs the jar executable located in the instance directory.
photon_local$start(
host = "0.0.0.0",
port = "2322",
ssl = FALSE,
timeout = 60,
java_opts = NULL,
photon_opts = NULL
)hostCharacter string of the host name that the geocoder should be opened on.
portPort that the geocoder should listen to.
sslIf TRUE, uses https, otherwise http.
Defaults to FALSE.
timeoutTime in seconds before the java process aborts. Defaults to 60 seconds.
java_optsList of further flags passed on to the java
command.
photon_optsList 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.
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.
download_data()Downloads a search index using download_searchindex.
photon_local$download_data(
country = NULL,
date = "latest",
exact = FALSE,
section = NULL
)countryCharacter 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.
dateCharacter 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.
exactIf TRUE, exactly matches the date. Otherwise,
selects the date with lowest difference to the date parameter.
sectionSubdirectory 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.
remove_data()Removes the data currently used in the photon directory. This only
affects the unpacked photon_data directory, not archived files.
photon_local$remove_data()
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).
photon_local$is_running()A logical of length 1.
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.
photon_local$is_ready()A logical of length 1.
get_url()Constructs the URL that geocoding requests should be sent to.
photon_local$get_url()A URL to send requests to.
get_logs()Retrieve the logs of previous photon runs.
photon_local$get_logs()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.
clone()The objects of this class are cloneable with this method.
photon_local$clone(deep = FALSE)deepWhether to make a deep clone.
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")}
if (FALSE) {
# 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"))}
Run the code above in your browser using DataLab