This vignette is an introduction to the {photon}
package, an interface to the photon geocoder developed by komoot. Photon is open-source, based
on OpenStreetMap data, and
powered by the ElasticSearch search
engine. It is – according to komoot – fast, scalable, multilingual,
typo-tolerant, and up-to-date. Photon can do unstructured geocoding,
reverse geocoding, and (under special circumstances) structured
geocoding. Komoot offers a public photon API (https://photon.komoot.io/) but you can also set up a
photon instance on a local machine.
{photon} supports both online and offline geocoding.
Online geocoding through komoots public API is intriguing because it is
convenient and offers up-to-date global coverage. It is appropriately
easy to use online geocoding in {photon}. First, it is
necessary to tell R that you want to use the public API. This can be
done using the workhorse function new_photon(). To set up
online geocoding, simply call it without parameters:
The created photon object is attached to the session and
does not have to be stored manually. Now you can geocode.
cities1 <- geocode(c("Sanaa", "Caracas"), osm_tag = ":city")
cities1
#> Simple feature collection with 2 features and 12 fields
#> Geometry type: POINT
#> Dimension: XY
#> Bounding box: xmin: -66.9146 ymin: 10.50609 xmax: 44.20588 ymax: 15.35386
#> Geodetic CRS: WGS 84
#> # A tibble: 2 × 13
#> idx osm_type osm_id osm_key osm_value type countrycode name country state county extent geometry
#> <int> <chr> <int> <chr> <chr> <chr> <chr> <chr> <chr> <chr> <chr> <list> <POINT [°]>
#> 1 1 N 258013552 place city distr… YE Sana… Yemen Aman… At Ta… <lgl> (44.20588 15.35386)
#> 2 2 R 11219583 place city city VE Cara… Venezu… Capi… Munic… <dbl> (-66.9146 10.50609)Similarly, you can also reverse geocode. {photon} fully
supports sf objects so that all geocoding functions return
sf dataframes and reverse() accepts
sf and sfc objects as input.
cities2 <- reverse(cities1, osm_tag = ":city")
cities2
#> Simple feature collection with 2 features and 12 fields
#> Geometry type: POINT
#> Dimension: XY
#> Bounding box: xmin: -66.9146 ymin: 10.50609 xmax: 44.20588 ymax: 15.35386
#> Geodetic CRS: WGS 84
#> # A tibble: 2 × 13
#> idx osm_type osm_id osm_key osm_value type countrycode name country state county extent geometry
#> <int> <chr> <int> <chr> <chr> <chr> <chr> <chr> <chr> <chr> <chr> <list> <POINT [°]>
#>1 1 N 258013552 place city distr… YE Sana… Yemen Aman… At Ta… <lgl> (44.20588 15.35386)
#>2 2 R 11219583 place city city VE Cara… Venezu… Capi… Munic… <dbl> (-66.9146 10.50609) More recently, the photon geocoder started to support structured
geocoding. Structured geocoding works just like geocode(),
but you provide place data in a dataframe instead of a character string.
This allows you to be much more specific in what you want to geocode.
While you’d have to fiddle with location biases to geocode Moscow, MN,
structured geocoding can be a little more precise.
place <- data.frame(
city = "Moscow",
state = "Minnesota",
countrycode = "USA"
)
structured(place)
#> Simple feature collection with 1 feature and 12 fields
#> Geometry type: POINT
#> Dimension: XY
#> Bounding box: xmin: -93.09825 ymin: 43.70718 xmax: -93.09825 ymax: 43.70718
#> Geodetic CRS: WGS 84
#> # A tibble: 1 × 13
#> idx osm_type osm_id osm_key osm_value type countrycode name county state
#> <int> <chr> <int> <chr> <chr> <chr> <chr> <chr> <chr> <chr>
#> 1 1 R 19843371 place village city US Mosc… Freeb… Minn…
#> # ℹ 3 more variables: country <chr>, extent <list>, geometry <POINT [°]>Online geocoding is nice and it is most likely what you need for basic tasks. But what if online geocoding is not enough? What if you need to geocode a dataset of 200,000 places? What if you need to geocode sensitive information from survey respondents? And what about structured geocoding?
The photon backend is freely available on the photon GitHub repository.
With it, you can set up a local instance of photon. Offline geocoding is
nice because it is extremely fast, versatile and it doesn’t send your
potentially sensitive data around the internet. In a lot of cases,
offline geocoding is absolutely imperative, yet usually, setting up an
offline geocoder can be quite cumbersome. {photon} takes
over this task!
To run photon, you need the Java Development Kit (JDK) version 11 or
higher. To do that, you can use the {rJavaEnv}
package by Egor Kotov. It allows you to easily set up a JDK environment
for a local project.
# pak::pkg_install("rJavaEnv")
library(rJavaEnv)
# Consent to downloading Java
rje_consent()
#> Consent for using rJavaEnv has already been provided.
# Install and use Corretto JDK 24
use_java(24)
# Check if installation was successful
java_check_version_cmd()
#> JAVA_HOME: /root/.cache/R/rJavaEnv/installed/linux/x64/24
#> Java path: /root/.cache/R/rJavaEnv/installed/linux/x64/24/bin/java
#> Java version: "openjdk version \"24.0.1\" 2025-04-15 OpenJDK Runtime Environment Corretto-24.0.1.9.1 (build
#> 24.0.1+9-FR) OpenJDK 64-Bit Server VM Corretto-24.0.1.9.1 (build 24.0.1+9-FR, mixed mode, sharing)"
#> [1] "24"Setting up local photon also works through new_photon().
This time, we pass a path where the necessary files should be stored and
a country for which a search index should be downloaded. While global
coverage is also possible, the global search index is extremely large
(around 80 GB). By default, new_photon() downloads a search
index tagged with latest but it is also possible to query a
search index created at a specific date.
path <- file.path(tempdir(), "photon")
photon <- new_photon(path, region = "Andorra")
#> ℹ openjdk version "24.0.1" 2025-04-15
#> ℹ OpenJDK Runtime Environment Corretto-24.0.1.9.1 (build 24.0.1+9-FR)
#> ℹ OpenJDK 64-Bit Server VM Corretto-24.0.1.9.1 (build 24.0.1+9-FR, mixed mode, sharing)
#> ✔ Successfully downloaded OpenSearch photon 1.0.0. [17.9s]
#> ✔ Successfully downloaded search index. [854ms]
#> • Version: 1.0.0
#> • Coverage: Andorra
#> • Time: 2026-02-27The resulting object is an R6 class with a few methods to control the
instance. To start photon, run $start(). This starts an
external java process which can be accessed using the $proc
attribute.
#> photon$start()
#> Cluster Name: photon
#> Base Path: /tmp/RtmpLQIqmy/photon/./photon_data
#> Num Of Node: 1
#> Node Name: Node 1
#> HTTP Port: 9201
#> Data Directory: /tmp/RtmpLQIqmy/photon/./photon_data/node_1/data
#> Log Directory: /tmp/RtmpLQIqmy/photon/./photon_data/node_1/logs
#> [2026-02-27T14:29:54,384][INFO ][o.o.n.Node ] version[3.4.0], pid[19752], build[unknown/unknown/unknown], OS[Windows 11/10.0/amd64], JVM[Oracle Corporation/Java HotSpot(TM) 64-Bit Server VM/22/22+36-2370]
#> [2026-02-27T14:29:54,385][INFO ][o.o.n.Node ] JVM home [/root/.cache/R/rJavaEnv/installed/linux/x64/24]
#> [2026-02-27T14:29:54,389][INFO ][o.o.n.Node ] JVM arguments []
#> [2026-02-27T14:29:54,395][INFO ][o.o.p.PluginsService ] no modules loaded
#> [2026-02-27T14:29:54,396][INFO ][o.o.p.PluginsService ] loaded plugin [org.opensearch.analysis.common.CommonAnalysisModulePlugin]
#> [2026-02-27T14:29:54,397][INFO ][o.o.p.PluginsService ] loaded plugin [org.opensearch.geo.GeoModulePlugin]
#> [2026-02-27T14:29:54,397][INFO ][o.o.p.PluginsService ] loaded plugin [org.opensearch.transport.Netty4ModulePlugin]
#> [2026-02-27T14:29:54,438][INFO ][o.o.e.NodeEnvironment ] using [1] data paths, mounts [[/ (/dev/sdd)]], net usable_space [103.5gb], net total_space [783.6gb], types [NTFS]
#> [2026-02-27T14:29:54,443][INFO ][o.o.e.NodeEnvironment ] heap size [3.9gb], compressed ordinary object pointers [true]
#> [2026-02-27T14:29:54,536][WARN ][o.a.l.i.v.VectorizationProvider] Java vector incubator module is not readable. For optimal vector performance, pass '--add-modules jdk.incubator.vector' to enable Vector API.
#> [2026-02-27T14:29:54,624][INFO ][o.o.n.Node ] node name [Node 1], node ID [FYcghCrFQyi8ZcOrpZkWmA], cluster name [photon], roles [data, cluster_manager]
#> [2026-02-27T14:29:54,664][INFO ][o.o.e.ExtensionsManager ] ExtensionsManager initialized
#> [2026-02-27T14:29:54,911][INFO ][o.o.i.MergeSchedulerConfig] Updating autoThrottle for index _na_ from [false] to [true]
#> [2026-02-27T14:29:54,911][INFO ][o.o.i.MergeSchedulerConfig] Updating maxThreadCount from [0] to [4] and maxMergeCount from [0] to [9] for index _na_.
#> [2026-02-27T14:29:54,911][INFO ][o.o.i.MergeSchedulerConfig] Initialized index _na_ with maxMergeCount=9, maxThreadCount=4, autoThrottleEnabled=true
#> [2026-02-27T14:29:55,087][INFO ][o.o.i.MergeSchedulerConfig] Updating autoThrottle for index _na_ from [false] to [true]
#> [2026-02-27T14:29:55,087][INFO ][o.o.i.MergeSchedulerConfig] Updating maxThreadCount from [0] to [4] and maxMergeCount from [0] to [9] for index _na_.
#> [2026-02-27T14:29:55,087][INFO ][o.o.i.MergeSchedulerConfig] Initialized index _na_ with maxMergeCount=9, maxThreadCount=4, autoThrottleEnabled=true
#> [2026-02-27T14:29:56,578][INFO ][o.o.t.NettyAllocator ] creating NettyAllocator with the following configs: [name=opensearch_configured, chunk_size=512kb, suggested_max_allocation_size=512kb, factors={opensearch.unsafe.use_netty_default_chunk_and_page_size=false, g1gc_enabled=true, g1gc_region_size=2mb}]
#> ✔ Photon is now running. [6.2s]
photon$proc
#> PROCESS 'java', running, pid 1896.To check if the service is up and running, you can use
$is_ready().
To compare offline and online geocoding, let’s benchmark them by geocoding the Samoan capital Apia:
# offline geocoding
bench::mark(with_photon(photon, geocode("Monte Carlo")), iterations = 25)$median
#> [1] 30.2ms# online geocoding
photon_pub <- new_photon(mount = FALSE)
bench::mark(with_photon(photon_pub, geocode("Monte Carlo")), iterations = 25)$median
#> [1] 334msThat is a speed increase by a factor of over 10 (and possibly more on faster machines)!
To properly stop photon after you used it, you can run
$stop(). You do not actually need to run it
manually, because it is (implicitly) executed on two occasions: 1. on
garbage collection and 2. when the R session ends and external processes
are killed.
Finally, to clean up photon, i.e. stop the instance and delete the
photon directory, run $purge().