photon
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 www.komoot.de. Find our public API and demo on photon.komoot.de.
We are a young project, feel free to test and participate!
Features
- 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
Installation
photon requires java, at least version 6.
get photon
wget http://photon.komoot.de/data/photon-0.2.7.jar
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.
wget -O - http://download1.graphhopper.com/public/photon-db-latest.tar.bz2 |
bzip2 -cd | tar x
# you can significantly speed up extracting using pbzip2:
wget -O - http://download1.graphhopper.com/public/photon-db-latest.tar.bz2 |
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/...
./continuously_update_from_nominatim.sh
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
http://localhost:2322/api?q=berlin
Search with Location Bias
http://localhost:2322/api?q=berlin&lon=10&lat=52
Reverse geocode a coordinate
http://localhost:2322/reverse?lon=10&lat=52
Adapt Number of Results
http://localhost:2322/api?q=berlin&limit=2
Adjust Language
http://localhost:2322/api?q=berlin&lang=it
tags and values
Filter results byNote: 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.
- Include places with tag:
osm_tag=key:value
- Exclude places with tag:
osm_tag=!key:value
- Include places with tag key:
osm_tag=key
- Include places with tag value:
osm_tag=:value
- Exclude places with tag key:
osm_tag=!key
- 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:
http://localhost:2322/api?q=berlin&osm_tag=toursim:museum
Or, just by they key
http://localhost:2322/api?q=berlin&osm_tag=tourism
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": [
13.3888599,
52.5170365
]
}
},
{
"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": [
13.23727,
52.5157151,
13.241757,
52.5135972
]
},
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [
13.239514674078611,
52.51467945
]
}
}]
}
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
Contact
Let us know what you think about photon! Create a github ticket or drop us an email in https://lists.openstreetmap.org/listinfo/photon
Licence
Photon software is open source and licensed under Apache License, Version 2.0