an open source geocoder for openstreetmap data
Java Python CSS HTML JavaScript Shell Other
Latest commit 09fb190 Oct 18, 2016 @christophlingg christophlingg committed on GitHub Merge pull request #238 from lonvia/housenumber-interpolation
Housenumber interpolation


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

Photon was started by komoot and provides search-as-you-type and multilingual support. It's used in production with thousands of requests per minute at Find our public API and demo on

We are a young project, feel free to test and participate!


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


photon requires java, at least version 6.

get photon


download search index (31G gb compressed, 56.3 gb uncompressed, worldwide coverage, languages: English, German, French and Italian). The search index is updated weekly and thankfully provided by graphhopper with the support of lonvia.

Make sure you have bzip2 or pbzip2 installed and execute one of these two commands in your shell. This will download, uncompress and extract the huge database in one step:

wget -O - | bzip2 -cd | tar x
# you can significantly speed up extracting using pbzip2 (recommended):
wget -O - | pbzip2 -cd | tar x

start photon

java -jar photon-0.2.7.jar

Check the URL http://localhost:2322/api?q=berlin to see if photon is running without problems. You may want to use our leaflet plugin to see the results on a map.

discover more of photon's feature with its usage java -jar photon-0.2.7.jar -h.

Customized Search Data

If you need search data in other languages or restricted to a country you will need to create your search data by your own. Once you have your nominatim database ready, you can import the data to photon:

java -jar photon-0.2.7.jar -nominatim-import -host localhost -port 5432 -database nominatim -user nominatim -password ... -languages es,fr

The import of worldwide data set will take some hours/days, ssd disk are recommended to accelerate nominatim queries.

Updating from Nominatim

In order to update from nominatim, you must start photon with the nominatim database credentials on the command line:

java -jar photon-0.2.7.jar -host localhost -port 5432 -database nominatim -user nominatim -password ...

A nominatim setup is also a requirement to have continuous updates. To keep in sync with the latest OSM changes run:

export NOMINATIM_DIR=/home/nominatim/...

If you have updated nominatim with another method, photon can be updated by making a HTTP GET request to /nominatim-update, e.g. with this command:

curl http://localhost:2322/nominatim-update

Search API

Start Photon

java -jar photon-0.2.7.jar



Search with Location Bias


Reverse geocode a coordinate


Adapt Number of Results


Adjust Language


Filter results by tags and values

Note: not all tags on link in the title are supported. Please see nominatim source for an accurate list. If one or many query parameters named osm_tag are present, photon will attempt to filter results by those tags. In general, here is the expected format (syntax) for the value of osm_tag request parameters.

  1. Include places with tag: osm_tag=key:value
  2. Exclude places with tag: osm_tag=!key:value
  3. Include places with tag key: osm_tag=key
  4. Include places with tag value: osm_tag=:value
  5. Exclude places with tag key: osm_tag=!key
  6. Exclude places with tag value: osm_tag=:!value

For example, to search for all places named berlin with tag of tourism=museum, one should construct url as follows:


Or, just by they key


Results as GeoJSON

  "features": [
      "properties": {
        "name": "Berlin",
        "state": "Berlin",
        "country": "Germany",
        "osm_key": "place",
        "osm_value": "city",
        "osm_type": "N",
        "osm_id": 240109189
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [
      "properties": {
        "name": "Berlin Olympic Stadium",
        "street": "Olympischer Platz",
        "housenumber": "3",
        "postcode": "14053",
        "state": "Berlin",
        "country": "Germany",
        "osm_key": "leisure",
        "osm_value": "stadium",
        "osm_type": "W",
        "osm_id": 38862723,
        "extent": [
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [

Related Projects

  • Photon's search configuration was developed with a specific test framework. It is written in Python and hosted separately.
  • R packge to access photon's public API with R


Let us know what you think about photon! Create a github ticket or drop us an email in


Photon software is open source and licensed under Apache License, Version 2.0