Go to file
Sarah Hoffmann a7d7e10ea9 prepare release 0.4.3 2023-07-28 18:00:59 +02:00
.github actions: update Nominatim dependencies and switch to Ubuntu 22 2023-05-25 12:24:44 +02:00
docs add documentation for synonym feature 2021-06-16 11:31:05 +02:00
es rename object_type to type in response to avoid BC break 2022-04-27 14:41:48 +02:00
src Refactor Osm Tag filters 2023-07-28 13:55:26 +02:00
website fix typo 2023-07-14 12:15:31 +02:00
.gitignore convert website to simple static html 2020-10-05 09:30:47 +02:00
.gitmodules Add Leaflet.Photon submodule 2014-02-19 21:06:09 +01:00
LICENSE Create LICENSE 2022-08-05 15:16:59 +02:00
README.md Merge pull request #742 from ybert/reverse-with-osm-tag 2023-07-27 16:14:06 +02:00
continuously_update_from_nominatim.sh adapt update script for nominatim CLI tool 2021-08-11 16:31:46 +02:00
pom.xml prepare release 0.4.3 2023-07-28 18:00:59 +02:00



Continuous Integration

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. Find our public API and demo on photon.komoot.io. Until October 2020 the API was available under photon.komoot.de. Please update your apps accordingly.


All code contributions and bug reports are welcome!

For questions please send an email to our mailing list.

Feel free to test and participate!


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


  • 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


photon requires java, at least version 8.

Download the search index (53G gb compressed, worldwide coverage, languages: English, German, French and local name). 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 - https://download1.graphhopper.com/public/photon-db-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-latest.tar.bz2 | pbzip2 -cd | tar x

Now get the latest version of photon from the releases and start it:

java -jar photon-*.jar

Use the -data-dir option to point to the parent directory of photon_data if that directory is not in the default location ./photon_data. Before you can send requests to photon, ElasticSearch needs to load some data into memory so be patient for a few seconds.

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.

To enable CORS (cross-site requests), use -cors-any to allow any origin or -cors-origin with a specific origin as the argument. By default, CORS support is disabled.

Discover more of photon's feature with its usage java -jar photon-*.jar -h.


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

mvn package

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.

If you haven't already set a password for your nominatim database user, do it now (change user name and password as you like, below):

su postgres
ALTER USER nominatim WITH ENCRYPTED PASSWORD 'mysecretpassword';

Import the data to photon:

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

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

Updating from OSM via Nominatim

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

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

A nominatim setup is also a requirement to have continuous updates. To keep nominatim in sync with the latest OSM changes and to update photon with nominatim afterwards 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


Search with Location Bias


There are two optional parameters to influence the location bias. 'zoom' describes the radius around the center to focus on. This is a number that should correspond roughly to the map zoom parameter of a corresponding map. The default is zoom=16.

The location_bias_scale describes how much the prominence of a result should still be taken into account. Sensible values go from 0.0 (ignore prominence almost completely) to 1.0 (prominence has approximately the same influence). The default is 0.2.


Reverse geocode a coordinate


Adapt Number of Results


Adjust Language


Filter results by bounding box

Expected format is minLon,minLat,maxLon,maxLat.


Filter results by tags and values

Note: the filter only works on principal OSM tags and not all OSM tag/value combinations can be searched. The actual list depends on the import style used for the Nominatim database (e.g. settings/import-full.style). All tag/value combinations with a property 'main' are included in the photon database. 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


You can also use this feature for reverse geocoding. Want to see the 5 pharmacies closest to a location ?


Filter results by layer

List of available layers:

  • house
  • street
  • locality
  • district
  • city
  • county
  • state
  • country

Example above will return both cities and localities.

Results as GeoJSON

  "features": [
      "properties": {
        "name": "Berlin",
        "state": "Berlin",
        "country": "Germany",
        "countrycode": "DE",
        "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",
        "countrycode": "DE",
        "osm_key": "leisure",
        "osm_value": "stadium",
        "osm_type": "W",
        "osm_id": 38862723,
        "extent": [
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [