Skip to contents

Initialize a photon instance

Source: R/new_photon.R
new_photon.Rd

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

path

Path to a directory where the photon executable and data should be stored. Defaults to a directory "photon" in the current working directory. If NULL, a remote instance is set up based on the url parameter.

url

URL of a photon server to connect to. If NULL and path is also NULL, connects to the public API under https://photon.komoot.io/.

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 is currently only experimental. Defaults to FALSE. See vignette("nominatim-import", package = "photon") for details.

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.

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")
}
#> ℹ 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. [676ms]
#> 
#> ℹ Fetching search index for Monaco, created on latest
#> ✔ Successfully downloaded search index. [1.3s]
#> 
#> • Version: 0.6.0
#> • Coverage: Monaco
#> • Time: latest