About photon

photon is an open source geocoder built for
OpenStreetMap data. It is based on
elasticsearch/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.

WARNING: 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.