photon Geocoder

You can test the photon API without hosting it yourself via the public demo server at https://photon.komoot.io.

Note: Extensive usage will be throttled or banned. For high-volume requests, you should set up your own private instance.

A Nominatim Dump File is an export and interchange format for geocoding databases. The file format uses concatenated JSON (JSON Lines), where each top-level object must declare a type and a content payload.

Object Structure:

{
    "type": "<STRING>",
    "content": { <OBJECT> }
}

There are three primary types of objects:

1. NominatimDumpFile: The mandatory header object.
2. CountryInfo: Optional objects containing country-specific metadata.
3. Place: Objects representing individual geocoding entries.

Note for Photon users: Photon only accepts two-letter ISO-3166-1 alpha-2 country codes in CountryInfo objects.

Updates can only be performed from a Nominatim database.

1. Prepare the database

Run the update-init command once to set up required tables and triggers in Nominatim. You must provide the -import-user parameter, which specifies the user that will perform future updates.

2. Run updates

Offline Method: Use the update command from the command line. Ensure Nominatim updates are not running during this process. Important: You must repeat any filters (like -country-codes) used during the initial import.

Online Method (via API):

1. Start the server with the -enable-update-api switch.
2. Trigger an update via curl http://localhost:2322/nominatim-update.
3. Check status via curl http://localhost:2322/nominatim-update/status. Returns "BUSY" if running, or "OK" if ready.

To add categories to a place during the data import process, include a categories field in your JSON object. This field must contain an array of category name strings.

Note: Category names that do not conform to the required syntax (group.value) are silently dropped.

If you are using the Nominatim database exporter, it automatically creates a category using the reserved osm group. It maps the main OSM tag key and value to the category. If the OSM key/value does not conform to the syntax, the exporter defaults to osm.place.yes.

To configure the website, copy the provided example configuration file into the photon/ directory and then modify config.js with your specific settings.

cp config.js.example photon/config.js

Photon supports custom query-time synonyms and classification terms via a JSON configuration file. This file is applied at runtime using the -synonym-file command line parameter. Note that providing a synonym list during the import process has no effect; changes require restarting the Photon server with the new file.

To disable the feature, simply restart the server without the -synonym-file parameter.

Photon uses Gradle for its build process. To build the package from source, ensure you have a JDK installed and run the following command in the repository root:

./gradlew build

The website consists of static files that can be opened directly in a browser or served via any webserver. If you have Python3 installed, you can use the provided Makefile to start a local server.

After running the command, access the site at http://localhost:5001/.

make serve

The import command creates a new database from a Nominatim PostgreSQL database or a JSON dump file. Warning: This deletes any existing database.

Importing from Nominatim

Connect to a PostgreSQL server. Use these parameters to configure the connection:

• -host, -port, -user, -password, -database

Note: The PostgreSQL user needs read access to query tables and permission to create an index on placex(country_code) if it doesn't exist. You may need to create this index manually: psql -d nominatim -c 'CREATE INDEX ON placex(country_code)'.

Importing from a JSON dump file

Use the -import-file parameter. You can pass a filename or - to read from standard input.

zstd --stdout -d photon-dump.jsonl.zst | java -jar photon.jar import -import-file -

When implementing synonyms and classification terms, follow these guidelines to avoid degrading search quality:

• Use sparingly: Only add terms if you are certain they target the intended part of the address.
• Avoid short/frequent terms: Common abbreviations can cause unintended side-effects. For example, mapping St to Saint will cause all searches for Street to also search for Saint.
• Avoid overlap: Do not create synonyms for terms that are already defined as classification terms.
• Single words only: For search_synonyms, ensure terms do not contain spaces or hyphens.

photon can operate in two modes:

1. Embedded Mode (Default): photon starts a private instance of OpenSearch. Data is saved in a directory named photon_data. Use the -data-dir parameter to specify a different location.
2. External OpenSearch: For large-scale or distributed installations, connect to an external OpenSearch 3.x instance. Use the -transport-addresses parameter with a comma-separated list of node addresses. You can specify a custom cluster name using the -cluster parameter.