photon

About photon

photon is an open source geocoder built for OpenStreetMap data. It is based on OpenSearch - an efficient, powerful and highly scalable search platform.

photon was started by komoot who also provide the public demo server at photon.komoot.io.

Features

• high performance
• highly scalability
• search-as-you-type
• multilingual search
• location bias
• typo tolerance
• filter by osm tag and value
• filter by bounding box
• reverse geocode a coordinate to an address
• OSM data import (built upon Nominatim) inclusive continuous updates
• import and export dumps in concatenated JSON format

Demo server

You can try out photon via the demo server at https://photon.komoot.io. You are welcome to use the API for your project as long as the number of requests stay in a reasonable limit. Extensive usage will be throttled or completely banned. We do not give guarantees for availability and reserve the right to implement changes without notice.

If you have a larger number of requests to make, please consider setting up your own private instance. It is as simple as downloading two files and starting the server. See instructions below.

Installation

Requirements

photon requires Java, version 21+.

If you want to run against an external database instead of using the embedded server, OpenSearch 3.x is needed.

A planet-wide database requires about 95GB disk space (as of 2026, grows by about 10% a year). Using SSDs for storage is strongly recommended, NVME would even be better. At least 64GB RAM are recommended for smooth operations, more, if the server takes significant load. Running photon with less RAM is possible but consider increasing the available heap (using java -Xmx8G -jar ... for example). Be careful to make sure that there remains enough free RAM that the system doesn’t start swapping.

If you want to import data from Nominatim, there are additional requirements for Nominatim.

Setting photon up with the release binaries and extracts

This is the easiest way to set up a self-hosted photon instance. Pre-built jar files can be downloaded from the Github release page.

GraphHopper kindly provides weekly updated dumps of the photon database at https://download1.graphhopper.com/public. The dumps are available for the world-wide dataset and for selected country datasets. The dumps contain names in English, German, French and local language. There is no support for full geometry output. If you need this feature, you need to import your own database from a JSON dump.

Follow the instruction on the webpage to find the right dump suitable for your version.

Make sure you have bzip2 or pbzip2 installed. Do not use WinRAR for unpacking, it is known to have issues with the files. Execute one of these two commands in your shell to download, uncompress and extract the huge database in one step:

wget -O - https://download1.graphhopper.com/public/photon-db-planet-1.0-latest.tar.bz2 | bzip2 -cd | tar x
# you can significantly speed up extracting using pbzip2 (recommended):
wget -O - https://download1.graphhopper.com/public/photon-db-planet-1.0-latest.tar.bz2 | pbzip2 -cd | tar x

Don’t forget to adapt the directory to match your photon version.

Updating photon with a new version of the database dump

When you want to update your local database with a newer version of the database dump, then you need to swap out the databases atomically:

• download and unpack the new version
• swap the directories to put the new directory in place of the old one
• restart photon and make sure everything works as expected
• delete the old database

This unfortunately means you need twice the space of the database for updates.

[!CAUTION] Never unpack the database in place of the old one. This will lead to corrupted data.

Usage

Change to the directory where the photon_data database directory is located (aka the parent directory of photon_data). Then start photon with the following command:

java -jar photon-*.jar serve

The webserver is then available at http://localhost:2322.

For a full documentation of the usage, including on how to import and update a database, see the Usage documentation.

Photon API

A full description of the Photon API and results can be found in the API documentation.

Building photon from scratch

photon uses gradle for building. To build the package from source make sure you have a JDK installed. Then run:

./gradlew build

This will build and test photon. The final jar can be found in the target directory.

Contributing

Code contributions and bug reports are welcome.

PRs that include AI-generated content, may that be in code, in the PR description or in documentation need to

1. clearly mark the AI-generated sections as such, for example, by mentioning all use of AI in the PR description, and
2. include proof that you have run the generated code on an actual installation of photon. Adding and executing tests will not be sufficient. You need to show that the code actually solves the problem the PR claims to solve.

For questions please either use Github discussions or join the OpenStreetMap forum.

License

photon is open source and licensed under Apache License, Version 2.0

Related Projects

• photon’s search configuration was developed with a specific test framework. It is written in Python and hosted separately.
• There is a leaflet-plugin for displaying a search box with a photon server in the backend.