Photon
 | ||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Author: | komoot/photon/graphs/contributors GitHub | |||||||||||||||||||
| License: | Apache License 2.0 (free of charge) | |||||||||||||||||||
| Status: | Active | |||||||||||||||||||
| Version: | 1.3.0 releases (2026-08-07) | |||||||||||||||||||
| Language: | multiple languages
| |||||||||||||||||||
| Website: | https://photon.komoot.io | |||||||||||||||||||
| Source code: | https://github.com/komoot/photon | |||||||||||||||||||
| Programming language: | Java | |||||||||||||||||||
|
An open source geocoder for openstreetmap data | ||||||||||||||||||||
| ||||||||||||||||||||
Photon is an open source geocoder built for OpenStreetMap data, with search-as-you-type as its main use. It is built on OpenSearch; earlier versions used Apache Solr and then Elasticsearch. Photon was started by komoot, which also runs the public instance at https://photon.komoot.io.
Photon imports its data from a Nominatim database, or from a JSON dump exported from one.
Features
- Search-as-you-type (autocomplete), with typo tolerance
- Free-text and structured (address-field) search
- Reverse geocoding
- Results in multiple languages, selected per request
- Location bias towards a given point
- Filters by bounding box, country, OSM tag and value, layer, and custom categories
- Continuous updates from a Nominatim database
- Results as GeoJSON
Public instance
The instance at https://photon.komoot.io can be used for projects that keep the number of requests reasonable. Heavy use is throttled or blocked, and komoot gives no availability guarantee. Projects with larger needs should run their own instance.
API
The API is documented in docs/api-v1.md. A server provides these endpoints:
| Endpoint | Purpose |
|---|---|
/api |
Forward search by name and address, e.g. /api?q=berlin
|
/structured |
Search by address fields (countrycode, state, county, city, postcode, district, street, housenumber)
|
/reverse |
Reverse geocoding, e.g. /reverse?lon=10&lat=52
|
/status |
Health check |
/update, /metrics |
Optional: triggering updates, and Prometheus metrics |
Common parameters include limit, lang (or the browser's Accept-Language header), lat/lon with zoom and location_bias_scale for location bias, bbox, osm_tag, layer, and include/exclude for categories.
Running your own instance
Photon requires Java 21 or later. It runs with an embedded search server, or against an external OpenSearch 3.x cluster.
The quickest setup uses a pre-built database: GraphHopper publishes weekly dumps of the Photon database, for the whole world and for selected countries, with names in English, German, French and the local language. Download the release jar and a matching dump, then start the server with java -jar photon-*.jar serve; it listens on port 2322. As of 2026 a planet database needs about 95 GB of disk, and at least 64 GB of RAM is recommended.
To choose the languages, the area or the objects imported, build the database yourself from a Nominatim database or a JSON dump. A reverse-only database is smaller and faster to import. Updates can only come from a Nominatim database. See the usage documentation for import, filtering and update options.
Client libraries
- leaflet.photon – search box for Leaflet
- Leaflet Control Geocoder – supports Photon among other geocoders
- geopy (Python) – includes a Photon geocoder
Other services and software using the Photon API
- GraphHopper Directions API offers Photon as one of its geocoding providers.
- overpass.ch Geocoding API provides a Photon-compatible API.
How to contribute
Code contributions and bug reports are welcome on GitHub. Pull requests that contain AI-generated content must say so and show that the code was run on a real Photon installation; see the README. Questions can go to GitHub Discussions or the OpenStreetMap community forum.
The search configuration was tuned with osm-geocoding-tester.
Photon is licensed under the Apache License, Version 2.0.