---
title: "Introduction to {photon}"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Introduction to {photon}}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

```{r setup, include=FALSE}
library(photon)
options(photon_movers = FALSE)
```

This vignette is an introduction to the `{photon}` package, an interface to the [photon](https://photon.komoot.io/) geocoder developed by [komoot](https://www.komoot.com/). Photon is open-source, based on [OpenStreetMap](https://www.openstreetmap.org/) data, and powered by the [ElasticSearch](https://www.elastic.co/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:

```{r public_api, eval=FALSE}
new_photon()
#> <photon>
#>   Type   : remote
#>   Server : https://photon.komoot.io/
```

The created `photon` object is attached to the session and does not have to be stored manually. Now you can geocode.

```{r geocode, eval=FALSE}
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.

```{r reverse, eval=FALSE}
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) 
```

```{r compare, eval=FALSE}
all.equal(cities1, cities2)
#> [1] TRUE
```

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.

```{r}
place <- data.frame(
  city = "Moscow",
  state = "Minnesota",
  countrycode = "USA"
)
structured(place)
```



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?


# Offline geocoding

The photon backend is freely available on the [photon GitHub repository](https://github.com/komoot/photon). 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}`](https://cran.r-project.org/package=rJavaEnv) package by Egor Kotov. It allows you to easily set up a JDK environment for a local project.

```{r java, eval=FALSE}
# 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.

```{r local_photon, eval=FALSE}
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-27
```

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

```{r start, eval=FALSE}
#> 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()`.

```{r is_ready, eval=FALSE}
photon$is_ready()
#> [1] TRUE
```

To compare offline and online geocoding, let's benchmark them by geocoding the Samoan capital Apia:

```{r benchmark1, eval=FALSE}
# offline geocoding
bench::mark(with_photon(photon, geocode("Monte Carlo")), iterations = 25)$median
#> [1] 30.2ms
```

```{r benchmark2, eval=FALSE}
# online geocoding
photon_pub <- new_photon(mount = FALSE)
bench::mark(with_photon(photon_pub, geocode("Monte Carlo")), iterations = 25)$median
#> [1] 334ms
```

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

```{r stop, eval=FALSE}
photon$stop()
```

Finally, to clean up photon, i.e. stop the instance and delete the photon directory, run `$purge()`.

```{r purge, eval=FALSE}
photon$purge()
#> ℹ Purging an instance kills the photon process and removes the photon directory.
#> Continue? (y/N/Cancel) y
```

