photon

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

Photon was developed 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.

The project consistes of three parts:

Solr configuration
Converter that creates a solr xml file from a Nominatim database (Java)
Testing environment for developing (Java)

How to use

Import data

Photon needs a dataset (addresses, streets, cities, ...). Solr provides numerous input formats, including xml. Currently you cannot convert an OpenStreetMap planet file to use it with photon. Instead you can use the NominatorImporter included in this project to dump a nominatim database to a xml file. Refer to Nominatim's Installation Guide how to setup and fill a postgis database. It takes up to 10 days and sufficient RAM to import the entire world, you might prefer taking a smaller region.

Once you have a nominatim database you can run the NominatorImporter to create the solr index

mvn compile exec:java -Dexec.mainClass=de.komoot.photon.importer.NominatimImporter -Dexec.args="...args..."

command line arguments

-h postgis database host, e.g. localhost
-d database name, usually Nominatim
-u username of database user
-P password of database user
-p database port, optional default value is 5432
-f path of xml output file, e.g. /Users/christoph/berlin.sorl.xml.gz
-l languages to import, e.g. de en es

A complete example:

mvn compile exec:java -Dexec.mainClass=de.komoot.photon.importer.NominatimImporter -Dexec.args="-h localhost -d nominatim_island -u christoph -P christoph -f /Users/christoph/iceland.solr.xml.gz -l en de es" > /home/christoph/island_import.log

This will take some time (Europe ~ 12 hours).

If you just want to check out photon you can use our example dump of Iceland too: src/main/solrindex/iceland.solr.xml.gz (© OpenStreetMap contributors).

Setup Solr

You need to install Apache Solr (tested with version 4.4). Using Mac OS X and homebrew you can type:

brew install solr

Start solr and pass the configuration directory that is part of the project src/main/solrconfig/

solr /Users/christoph/komoot/solr4/src/main/solrconfig/

On other systems you might want to start solr that way:

java -Dsolr.solr.home=/Users/christoph/komoot/solr4/src/main/solrconfig/ -jar start.jar

Check Solr's admin interface on http://localhost:8983/solr/

You can already query for places but no search results will be found as we have not imported any data yet. To do so we need to type:

curl "http://localhost:8983/solr/collection1/update?commit=true" -F stream.file=/Users/christoph/iceland.solr.xml
curl "http://localhost:8983/solr/collection1/update" -F stream.body=' <optimize />'

Don't forget to unzip the xml file first.

Now solr is up and running and filled with data. You can start searching for places:

http://localhost:8983/solr/collection1/select?q=reykjavik

How to contribute

Join us in improving photon and feel free to contact us!

For developing we used a test-based approch, the test environment and testcases are located in src/main/java/de/komoot/search/tests/. Every test consists of a xml file (test data) and csv file (test definition).

Licence

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

yohanboniface / photon