photon_local: Local photon instance
In photon: High-Performance Geocoding using 'photon'
photon_local R Documentation
Local photon instance
Description
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
OpenSearch index. It can start, stop, and query the status of the
photon instance. It is also the basis for geocoding requests as it is used
to retrieve the URL for geocoding.
Value
A list containing four elements:
status: Shows "Ok" when photon is running without problems.
import_date: Time stamp when the database was built.
version: Photon version currently running.
git_commit: Git commit string of the photon version currently running.
Search indices
Search indices can be self-provided by importing an existing
Nominatim database or they can be downloaded from the
Photon download server.
If you want to download pre-built search indices, simply provide a
region string during initialization or use the
$download_data method. Pre-built search indices do not come with
support for structured geocoding.
If you want to build from Nominatim, do not
provide a region string and use the $import() method. 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.7.0, OpenSearch jar files are the
standard and ElasticSearch is deprecated.
Super class
photon::photon -> photon_local
Public fields
pathPath to the directory where the photon instance is stored.
procprocess object that handles the
external process running photon.
Methods
Public 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,
region = NULL,
opensearch = TRUE,
mount = TRUE,
overwrite = FALSE,
quiet = FALSE,
country = NULL
)
Arguments
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: 1.0.0).
regionCharacter string that identifies a region or country. An
extract for this region will be downloaded. If "planet", downloads
a global extract (see note). Run list_regions() to get an overview
of available regions. You can specify countries using any code that can
be translated by countrycode.
opensearchDeprecated for photon versions >= 1.0.0 and superseded
for photon versions >= 0.7.0. If TRUE,
attempts to download the OpenSearch version of photon. OpenSearch-based
photon supports structured geocoding. If FALSE, falls back to
ElasticSearch. Since photon 0.7.0, OpenSearch is the default and since
1.0.0, ElasticSearch is not supported anymore.
mountIf TRUE, mounts the object to the session so that
functions like geocode automatically detect the new
instance. If FALSE, initializies the instance but doesn't mount
it to the session. Defaults to TRUE.
overwriteIf TRUE, overwrites existing jar files and
search indices when initializing a new instance. Defaults to
FALSE.
quietIf TRUE, suppresses all informative messages.
countryDeprecated since photon 1.0.0. Use region instead.
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 region and creation date of the 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 help()
Print the default arguments to the R console. This can be helpful to
get a list of additional photon arguments for $start() or
$import().
Usage
photon_local$help(cmd = "start")
Arguments
cmdA command for which to display the help page. Must be one
of "start", "import", "update", "update-init",
or "dump-nominatim-db". Defaults to "start".
Returns
Nothing, but prints to the console.
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
askIf 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 = "",
json = FALSE,
languages = c("en", "fr", "de", "it"),
countries = NULL,
full_geometries = FALSE,
extra_tags = NULL,
timeout = 60,
java_opts = NULL,
photon_opts = NULL,
structured = NULL,
update = NULL,
enable_update_api = NULL
)
Arguments
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 "".
jsonIf TRUE and a JSON dump is present in the photon
directory, imports from a JSON dump. Otherwise, tries to import from
Nominatim.
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.
full_geometriesAdd the full geometry for each place if
available. Considerably increases the size of the photon database.
extra_tagsCharacter vector specifying extra OSM tags to import
from the Nominatim database. These tags are used to augment geocoding
results. Defaults to NULL.
timeoutTime in seconds before the java process aborts. Defaults
to 60 seconds.
java_optsCharacter vector of further flags passed on to the
java command.
photon_optsCharacter vector of further flags passed on to the
photon jar in the java command. See cmd_options for a
helper function.
structuredDeprecated since v1.0.0. Structured geocoding is
enabled by default now. For earlier versions, use photon_opts.
updateDeprecated since v1.0.0. Updates are done using a distinct
command now. For earlier versions, use photon_opts.
enable_update_apiDeprecated since v1.0.0. For earlier versions,
use photon_opts.
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,
countries = NULL,
threads = 1,
query_timeout = NULL,
max_results = NULL,
max_reverse_results = NULL,
java_opts = NULL,
photon_opts = NULL
)
Arguments
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.
countriesCharacter vector of countries to import. By default,
all countries in the database are imported.
threadsNumber of threads in parallel. Defaults to 1.
query_timeoutTime in seconds after which to cancel queries
to Photon. Defaults to 7 seconds.
max_resultsMaximum number of results returned to
geocode and structured. Defaults to
50.
max_reverse_resultsMaximum number of results returned to
reverse. Defaults to 50.
java_optsCharacter vector of further flags passed on to the
java command.
photon_optsCharacter vector of further flags passed on to the
photon jar in the java command. See cmd_options for a
helper function.
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 may sometimes hang instead of
emitting an error. In this case, please open a bug report.
Method stop()
Kills the running photon process.
Usage
photon_local$stop()
Method status()
Returns information from a live server about the photon version used
and the date of data import.
Usage
photon_local$status()
Method download_data()
Downloads a search index using download_database.
Usage
photon_local$download_data(region, json = FALSE)
Arguments
regionCharacter string that identifies a region or country. An
extract for this region will be downloaded. If "planet", downloads
a global extract (see note). Run list_regions() to get an overview
of available regions. You can specify countries using any code that can
be translated by countrycode.
jsonExtracts come in two forms: JSON dumps and pre-build databases.
Pre-built databases are more convenient but less flexible and are not available
for all regions. If you wish or need to build your own database, set
json = TRUE and use the $import() method.
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
deepWhether 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, region = "Andorra")
# start a new instance with an older photon version
photon <- new_photon(path = dir, photon_version = "0.4.1", opensearch = FALSE)
}
## Not run:
# 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$import(photon_options = cmd_options(port = 29146, password = "pgpass"))
## End(Not run)
photon$purge(ask = FALSE)
photon documentation built on April 10, 2026, 5:07 p.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
| photon_local | R Documentation |
Local photon instance
Description
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 OpenSearch index. It can start, stop, and query the status of the photon instance. It is also the basis for geocoding requests as it is used to retrieve the URL for geocoding.
Value
A list containing four elements:
status: Shows "Ok" when photon is running without problems.
import_date: Time stamp when the database was built.
version: Photon version currently running.
git_commit: Git commit string of the photon version currently running.
Search indices
Search indices can be self-provided by importing an existing
Nominatim database or they can be downloaded from the
Photon download server.
If you want to download pre-built search indices, simply provide a
region string during initialization or use the
$download_data method. Pre-built search indices do not come with
support for structured geocoding.
If you want to build from Nominatim, do not
provide a region string and use the $import() method. 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.7.0, OpenSearch jar files are the standard and ElasticSearch is deprecated.
Super class
photon::photon -> photon_local
Public fields
pathPath to the directory where the photon instance is stored.
procprocessobject that handles the external process running photon.
Methods
Public 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, region = NULL, opensearch = TRUE, mount = TRUE, overwrite = FALSE, quiet = FALSE, country = NULL )
Arguments
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
jaris given. IfNULL, uses the latest known version (Currently: 1.0.0).regionCharacter string that identifies a region or country. An extract for this region will be downloaded. If
"planet", downloads a global extract (see note). Runlist_regions()to get an overview of available regions. You can specify countries using any code that can be translated bycountrycode.opensearchDeprecated for photon versions >= 1.0.0 and superseded for photon versions >= 0.7.0. If
TRUE, attempts to download the OpenSearch version of photon. OpenSearch-based photon supports structured geocoding. IfFALSE, falls back to ElasticSearch. Since photon 0.7.0, OpenSearch is the default and since 1.0.0, ElasticSearch is not supported anymore.mountIf
TRUE, mounts the object to the session so that functions likegeocodeautomatically detect the new instance. IfFALSE, initializies the instance but doesn't mount it to the session. Defaults toTRUE.overwriteIf
TRUE, overwrites existing jar files and search indices when initializing a new instance. Defaults toFALSE.quietIf
TRUE, suppresses all informative messages.countryDeprecated since photon 1.0.0. Use
regioninstead.
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 region and creation date of the 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 help()
Print the default arguments to the R console. This can be helpful to
get a list of additional photon arguments for $start() or
$import().
Usage
photon_local$help(cmd = "start")
Arguments
cmdA command for which to display the help page. Must be one of
"start","import","update","update-init", or"dump-nominatim-db". Defaults to"start".
Returns
Nothing, but prints to the console.
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
askIf
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 = "",
json = FALSE,
languages = c("en", "fr", "de", "it"),
countries = NULL,
full_geometries = FALSE,
extra_tags = NULL,
timeout = 60,
java_opts = NULL,
photon_opts = NULL,
structured = NULL,
update = NULL,
enable_update_api = NULL
)Arguments
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
"".jsonIf
TRUEand a JSON dump is present in the photon directory, imports from a JSON dump. Otherwise, tries to import from Nominatim.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.
full_geometriesAdd the full geometry for each place if available. Considerably increases the size of the photon database.
extra_tagsCharacter vector specifying extra OSM tags to import from the Nominatim database. These tags are used to augment geocoding results. Defaults to
NULL.timeoutTime in seconds before the java process aborts. Defaults to 60 seconds.
java_optsCharacter vector of further flags passed on to the
javacommand.photon_optsCharacter vector of further flags passed on to the photon jar in the java command. See
cmd_optionsfor a helper function.structuredDeprecated since v1.0.0. Structured geocoding is enabled by default now. For earlier versions, use
photon_opts.updateDeprecated since v1.0.0. Updates are done using a distinct command now. For earlier versions, use
photon_opts.enable_update_apiDeprecated since v1.0.0. For earlier versions, use
photon_opts.
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, countries = NULL, threads = 1, query_timeout = NULL, max_results = NULL, max_reverse_results = NULL, java_opts = NULL, photon_opts = NULL )
Arguments
hostCharacter string of the host name that the geocoder should be opened on.
portPort that the geocoder should listen to.
sslIf
TRUE, useshttps, otherwisehttp. Defaults toFALSE.timeoutTime in seconds before the java process aborts. Defaults to 60 seconds.
countriesCharacter vector of countries to import. By default, all countries in the database are imported.
threadsNumber of threads in parallel. Defaults to 1.
query_timeoutTime in seconds after which to cancel queries to Photon. Defaults to 7 seconds.
max_resultsMaximum number of results returned to
geocodeandstructured. Defaults to 50.max_reverse_resultsMaximum number of results returned to
reverse. Defaults to 50.java_optsCharacter vector of further flags passed on to the
javacommand.photon_optsCharacter vector of further flags passed on to the photon jar in the java command. See
cmd_optionsfor a helper function.
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 may sometimes hang instead of emitting an error. In this case, please open a bug report.
Method stop()
Kills the running photon process.
Usage
photon_local$stop()
Method status()
Returns information from a live server about the photon version used and the date of data import.
Usage
photon_local$status()
Method download_data()
Downloads a search index using download_database.
Usage
photon_local$download_data(region, json = FALSE)
Arguments
regionCharacter string that identifies a region or country. An extract for this region will be downloaded. If
"planet", downloads a global extract (see note). Runlist_regions()to get an overview of available regions. You can specify countries using any code that can be translated bycountrycode.jsonExtracts come in two forms: JSON dumps and pre-build databases. Pre-built databases are more convenient but less flexible and are not available for all regions. If you wish or need to build your own database, set
json = TRUEand use the$import()method.
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
deepWhether 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, region = "Andorra")
# start a new instance with an older photon version
photon <- new_photon(path = dir, photon_version = "0.4.1", opensearch = FALSE)
}
## Not run:
# 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$import(photon_options = cmd_options(port = 29146, password = "pgpass"))
## End(Not run)
photon$purge(ask = FALSE)
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.