Type:	Package
Title:	High-Performance Geocoding using 'photon'
Version:	0.3.5
Description:	Features unstructured, structured and reverse geocoding using the 'photon' geocoding API https://photon.komoot.io/. Facilitates the setup of local 'photon' instances to enable offline geocoding.
License:	Apache License (≥ 2)
URL:	https://github.com/jslth/photon/, https://jslth.github.io/photon/
BugReports:	https://github.com/jslth/photon/issues
Encoding:	UTF-8
RoxygenNote:	7.3.2
Imports:	utils, cli, countrycode, httr2, R6, sf, processx
Suggests:	testthat (≥ 3.0.0), tibble, knitr, rmarkdown, webfakes, ps
Config/testthat/edition:	3
VignetteBuilder:	knitr
NeedsCompilation:	no
Packaged:	2025-02-23 11:57:49 UTC; PC
Author:	Jonas Lieth [aut, cre, cph]
Maintainer:	Jonas Lieth <jonas.lieth@gesis.org>
Repository:	CRAN
Date/Publication:	2025-02-24 13:00:02 UTC

photon: High-Performance Geocoding using 'photon'

Description

Features unstructured, structured and reverse geocoding using the 'photon' geocoding API https://photon.komoot.io/. Facilitates the setup of local 'photon' instances to enable offline geocoding.

Terms of use

From https://photon.komoot.io on using the public API:

"You can use the API for your project, but please be fair - extensive usage will be throttled. We do not guarantee for the availability and usage might be subject of change in the future."

Note that these terms only apply to the public API (new_photon()), and not to local instances (e.g. new_photon(path = "."))! For the public API, the package sets a default of 1 request per second (see below).

Global options

A number of global options can be set that change the behavior of package functions. These include:

photon_throttle

Rate limit used to throttle requests. By default, no throttle is set for non-komoot instances. For komoot's public API, this option defaults to 1 request per second. See req_throttle.

photon_max_tries

Number of retries a failing request should do before ultimately aborting. Defaults to 3. See req_retry.

photon_debug

Whether to echo the command of external processes and GET requests sent to photon. Defaults to FALSE.

photon_movers

Whether moving verbosity is allowed. If FALSE, disables progress bars and spinners globally. Overwritten by local parameters. Defaults to TRUE. This option is useful for non-interactive sessions like RMarkdown.

photon_setup_warn

Whether to convert warnings in the photon logs to R warnings. Many warnings in the log are somewhat useless, but some can be important. Defaults to TRUE.

Author(s)

Maintainer: Jonas Lieth jonas.lieth@gesis.org (ORCID) [copyright holder]

See Also

Useful links:

• https://github.com/jslth/photon/

• https://jslth.github.io/photon/

• Report bugs at https://github.com/jslth/photon/issues

Format command line options

Description

Helper function to format options for command line calls. The function accepts key-value pairs where the parameter name is the name of the option and the parameter value is the value of the option. Arguments are formatted according to the following rules:

• If a value is TRUE, add parameter name as flag.

• If a value is FALSE, do not add parameter name as flag.

• If a value has length(x) > 1, collapse it as a CSV.

• If a parameter name is missing, take the value as the flag name.

• If a parameter name is given, replace underscores with hyphens.

Usage

cmd_options(..., use_double_hyphens = FALSE)

Arguments

Value

A character vector of formatted command line options that can be used as input to system2 or run.

Examples

# converts R parameters to CMD options
# parameters for the ping command
cmd_options(n = 1, w = 5, "127.0.0.1")

# sometimes, it is necessary to use double hyphens
# options for the docker ps command
cmd_options("ps", all = TRUE, format = "json", use_double_hyphens = TRUE)

# particularly useful together with photon
# the following options can be used for the `photon_opts` argument
# of photon$start()
cmd_options(cors_any = TRUE, data_dir = "path/to/dir")

Download photon

Description

Download the photon executable from GitHub.

Usage

download_photon(
  path = ".",
  version = NULL,
  opensearch = FALSE,
  only_url = FALSE,
  quiet = FALSE
)

Arguments

Value

If only_url = FALSE, returns a character string giving the path to the downloaded file. Otherwise, returns the URL to be downloaded.

Examples

download_photon(tempdir(), version = "0.4.1")

Download search index

Description

Finds and downloads the Elasticsearch index database necessary to set up Photon locally.

Usage

download_searchindex(
  path = ".",
  country = "Monaco",
  date = "latest",
  exact = FALSE,
  section = NULL,
  only_url = FALSE,
  quiet = FALSE
)

Arguments

Value

If only_url = FALSE, returns the local path to the downloaded file. Otherwise, returns the URL to the remote file.

Note

Depending on the country, search index databases tend to be very large. The global search index is about 75 GB of size (10/2024). Keep that in mind when running this function.

Examples

# download the latest extract of Monaco
download_searchindex(path = tempdir())

# download the latest extract of American Samoa
download_searchindex(path = tempdir(), country = "Samoa")

# download an extract from a month ago
download_searchindex(
  path = tempdir(),
  country = "Monaco",
  date = Sys.time() - 2629800
 )

# if possible, download an extract from today
try(download_searchindex(
  path = tempdir(),
  country = "Monaco",
  date = Sys.Date(),
  exact = TRUE
))

# get the latest global coverage
# NOTE: the file to be downloaded is several tens of gigabytes of size!
## Not run: 
download_searchindex(path = tempdir(), country = "planet")
## End(Not run)

Unstructured geocoding

Description

Geocode arbitrary text strings. Unstructured geocoding is more flexible but generally less accurate than structured geocoding.

Usage

geocode(
  texts,
  limit = 1,
  lang = "en",
  bbox = NULL,
  osm_tag = NULL,
  layer = NULL,
  locbias = NULL,
  locbias_scale = NULL,
  zoom = NULL,
  latinize = TRUE,
  progress = interactive()
)

Arguments

Details

Filtering by OpenStreetMap tags follows a distinct syntax explained on https://github.com/komoot/photon. In particular:

• Include places with tag: key:value

• Exclude places with tag: !key:value

• Include places with tag key: key

• Include places with tag value: :value

• Exclude places with tag key: !key

• Exclude places with tag value: :!value

Value

An sf dataframe or tibble containing the following columns:

• idx: Internal ID specifying the index of the texts parameter.

• osm_type: Type of OSM element, one of N (node), W (way), R (relation), or P (polygon).

• osm_id: OpenStreetMap ID of the matched element.

• country: Country of the matched place.

• city: City of the matched place.

• osm_key: OpenStreetMap key.

• countrycode: ISO2 country code.

• housenumber: House number, if applicable.

• postcode: Post code, if applicable.

• locality: Locality, if applicable.

• street: Street, if applicable.

• district: District name, if applicable.

• osm_value: OpenStreetMap tag value.

• name: Place name.

• type: Layer type as described for the layer parameter.

• extent: Boundary box of the match.

Examples

# an instance must be mounted first
photon <- new_photon()

# geocode a city
geocode("Berlin")

# return more results
geocode("Berlin", limit = 10)

# return the results in german
geocode("Berlin", limit = 10, lang = "de")

# limit to cities
geocode("Berlin", layer = "city")

# limit to European cities
geocode("Berlin", bbox = c(xmin = -71.18, ymin = 44.46, xmax = 13.39, ymax = 52.52))

# search for museums in berlin
geocode("Berlin", osm_tag = "tourism:museum")

# search for touristic attractions in berlin
geocode("Berlin", osm_tag = "tourism")

# search for anything but tourism
geocode("Berlin", osm_tag = "!tourism")

# use location biases to match Berlin, IL instead of Berlin, DE
geocode("Berlin", locbias = c(-100, 40), locbias_scale = 0.1, zoom = 7, osm_tag = "place")

# latinization can help normalize search terms
geocode("Luatuanu\u2019u", latinize = FALSE) # fails
geocode("Luatuanu\u2019u", latinize = TRUE)  # works

Photon utilities

Description

Utilities to manage photon instances. These functions operate on mounted photon instances which can be initialized using new_photon.

• get_instance() retrieves the active photon instance.

• get_photon_url() retrieves the photon URL to send requests.

Usage

get_instance()

get_photon_url()

Value

get_instance returns a R6 object of class photon. get_photon_url() returns a URL string.

Examples

# make a new photon instance
new_photon()

# retrieve it from the cache
get_instance()

# get the server url
get_photon_url()

Is Java installed?

Description

Utility function to check if Java is installed and if it has the right version.

Usage

has_java(version = NULL)

Arguments

Value

A logical vector of length 1.

Examples

has_java() # Is Java installed?
has_java("11") # Is Java > 11 installed?

Latinization

Description

Helper tool to transliterate various encodings to latin. Attempts to convert a character vector from its current encoding to "latin1" and - if it fails - defaults back to the original term. This can be useful for geocode and structured when attempting to geocode terms containing symbols that photon does not support.

Usage

latinize(x, encoding = "latin1")

Arguments

Value

The transliterated vector of the same length as x. NAs are avoided.

Examples

# converts fancy apostrophes to normal ones
latinize("Luatuanu\u2019u")

# does nothing
latinize("Berlin")

# also does nothing, although it would fail with `iconv`
latinize("\u0391\u03b8\u03ae\u03bd\u03b1")

Initialize a photon instance

Description

Initialize a photon instance by creating a new photon object. This object is stored in the R session and can be used to perform geocoding requests.

Instances can either be local or remote. Remote instances require nothing more than a URL that geocoding requests are sent to. Local instances require the setup of the photon executable, a search index, and Java. See photon_local for details.

Usage

new_photon(
  path = NULL,
  url = NULL,
  photon_version = NULL,
  country = NULL,
  date = "latest",
  exact = FALSE,
  section = NULL,
  opensearch = FALSE,
  overwrite = FALSE,
  quiet = FALSE
)

Arguments

Value

An R6 object of class photon.

Examples

# connect to public API
photon <- new_photon()

# connect to arbitrary server
photon <- new_photon(url = "photonserver.org")

if (has_java("11")) {
# set up a local instance in the current working directory
photon <- new_photon("photon", country = "Monaco")
}

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 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

Methods

Public methods

• photon_local$new()

• photon_local$mount()

• photon_local$info()

• photon_local$purge()

• photon_local$import()

• photon_local$start()

• photon_local$stop()

• photon_local$download_data()

• photon_local$remove_data()

• photon_local$is_running()

• photon_local$is_ready()

• photon_local$get_url()

• photon_local$get_logs()

• photon_local$clone()

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

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

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

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

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

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

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")}

## 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$start(photon_options = cmd_options(port = 29146, password = "pgpass"))
## End(Not run)

Purge Java processes

Description

Kill all or selected running Java processes. This function is useful to stop Photon instances when not being able to kill the process objects. Be aware that you can also kill Java processes other than the photon application using this function!

Usage

purge_java(pids = NULL, ask = TRUE)

Arguments

Details

A list of running Java tasks is retrieved using ps (on Linux and MacOS) or tasklist (on Windows). Tasks are killed using pkill (on Linux and MacOS) or Taskkill (on Windows).

Value

An integer vector of the pkill / Taskkill status codes or NULL if not running Java processes are found.

Examples

# NOTE: These examples should only be run interactively or when you are
# sure that no other java processes are running simultaneously!
## Not run: 
purge_java() # does nothing if no java processes are running

# start a new photon instance
dir <- file.path(tempdir(), "photon")
photon <- new_photon(dir, country = "Samoa")
photon$start()

# kill photon using a sledgehammer
purge_java()

photon$start()

# kill photon using a scalpel
library(ps)
p <- ps_handle(photon$proc$get_pid())
pids <- sapply(ps_children(p), ps::ps_pid)
purge_java(pids)
## End(Not run)

Objects exported from other packages

Description

These objects are imported from other packages. Follow the links below to see their documentation.

processx

process, run

Reverse geocoding

Description

Reverse geocode a set of points to retrieve their corresponding place names. To geocode a place name or an address, see unstructured or structured geocoding.

Usage

reverse(
  .data,
  radius = NULL,
  limit = 1,
  lang = "en",
  osm_tag = NULL,
  layer = NULL,
  locbias = NULL,
  locbias_scale = NULL,
  zoom = NULL,
  distance_sort = TRUE,
  progress = interactive()
)

Arguments

Details

Filtering by OpenStreetMap tags follows a distinct syntax explained on https://github.com/komoot/photon. In particular:

• Include places with tag: key:value

• Exclude places with tag: !key:value

• Include places with tag key: key

• Include places with tag value: :value

• Exclude places with tag key: !key

• Exclude places with tag value: :!value

Value

An sf dataframe or tibble containing the following columns:

• idx: Internal ID specifying the index of the texts parameter.

• osm_type: Type of OSM element, one of N (node), W (way), R (relation), or P (polygon).

• osm_id: OpenStreetMap ID of the matched element.

• country: Country of the matched place.

• city: City of the matched place.

• osm_key: OpenStreetMap key.

• countrycode: ISO2 country code.

• housenumber: House number, if applicable.

• postcode: Post code, if applicable.

• locality: Locality, if applicable.

• street: Street, if applicable.

• district: District name, if applicable.

• osm_value: OpenStreetMap tag value.

• name: Place name.

• type: Layer type as described for the layer parameter.

• extent: Boundary box of the match.

Examples

# an instance must be mounted first
photon <- new_photon()

# works with sf objects
sf_data <- sf::st_sfc(sf::st_point(c(8, 52)), sf::st_point(c(7, 52)))
reverse(sf_data)

# ... but also with simple dataframes
df_data <- data.frame(lon = c(8, 7), lat = c(52, 52))
reverse(df_data)

# limit search radius to 10m
reverse(df_data, radius = 10)

Structured geocoding

Description

Geocode a set of place information such as street, house number, or post code. Structured geocoding is generally more accurate but requires more information than unstructured geocoding.

Note that structured geocoding must be specifically enabled when building a Nominatim database. It is generally not available on komoot's public API and on pre-built search indices through download_searchindex. See vignette("nominatim-import", package = "photon") for details. You can use the helper function has_structured_support() to check if the current API supports structured geocoding.

Usage

structured(
  .data,
  limit = 1,
  lang = "en",
  bbox = NULL,
  osm_tag = NULL,
  layer = NULL,
  locbias = NULL,
  locbias_scale = NULL,
  zoom = NULL,
  progress = interactive()
)

has_structured_support()

Arguments

Details

Filtering by OpenStreetMap tags follows a distinct syntax explained on https://github.com/komoot/photon. In particular:

• Include places with tag: key:value

• Exclude places with tag: !key:value

• Include places with tag key: key

• Include places with tag value: :value

• Exclude places with tag key: !key

• Exclude places with tag value: :!value

Value

An sf dataframe or tibble containing the following columns:

• idx: Internal ID specifying the index of the texts parameter.

• osm_type: Type of OSM element, one of N (node), W (way), R (relation), or P (polygon).

• osm_id: OpenStreetMap ID of the matched element.

• country: Country of the matched place.

• city: City of the matched place.

• osm_key: OpenStreetMap key.

• countrycode: ISO2 country code.

• housenumber: House number, if applicable.

• postcode: Post code, if applicable.

• locality: Locality, if applicable.

• street: Street, if applicable.

• district: District name, if applicable.

• osm_value: OpenStreetMap tag value.

• name: Place name.

• type: Layer type as described for the layer parameter.

• extent: Boundary box of the match.

Examples

## Not run: 
# structured() requires an OpenSearch instance with structured support
# the following code will not work off the shelf
# refer to vignette("nominatim-import") for details
dir <- file.path(tempdir(), "photon")
photon <- new_photon(dir, opensearch = TRUE)
photon$import(password = "psql_password", structured = TRUE)
photon$start()

# check if structured() is supported
has_structured_support()

# structured() works on dataframes containing structurized data
place_data <- data.frame(
  housenumber = c(NA, "77C", NA),
  street = c("Falealilli Cross Island Road", "Main Beach Road", "Le Mafa Pass Road"),
  state = c("Tuamasaga", "Tuamasaga", "Atua")
)
structured(place_data, limit = 1)

# countries must be specified as iso2 country codes
structured(data.frame(countrycode = "ws"))

# traditional parameters from geocode() can also be used but are much more niche
structured(data.frame(city = "Apia"), layer = "house") # matches nothing

# structured geocoding can discern small differences in places
safune <- data.frame(
  city = c("Safune", "Safune"),
  state = c("Gaga'ifomauga", "Tuamasaga")
)
structured(safune, limit = 1)

## End(Not run)