We are happy to announce the release of Photon 1.0.0. With its first major release Photon fully switches to OpenSearch, sees a lot of improvements in performance and gets some new features on the query side.

This release marks a major milestone in the journey to make Photon a more efficient and flexible geocoder. Over the last year the code has seen a lot of modernization. We are moving away from being a simple search front end to Nominatim, towards becoming a fully featured geocoder where OpenStreetMap data can be one of many sources.

Here are the most important highlights for this 1.0 release:

Streamlined database structure

Photon’s internal database structure has been streamlined. Any metrics that are not relevant for the geocoding problem have been dropped. We’ve also dropped all language-specific indexes. Using those has slowed down queries for very little gain in accuracy.

Altogether the database is now about half the size than a 0.7 database. A planet needs about 95GB of disk space as of early 2026.

Revamped CLI

Over the years Photon has collected quite a few command-line options to tweak the import and the operation of the server. To bring a bit of order into this mess, the command-line is now organised in git-style subcommands for import, update and serving. You can ask for help for each of the commands with the ‘-h’ parameter and will get a more compact response with parameters neatly organised in groups. Have a look at the new usage documentation to learn more about the available commands.

The changes to the CLI are backwards-compatible. When no command is given then Photon will fall back to the old-style command-line parameters. This will give everybody some time to adapt their scripts to the new layout. But don’t wait too long. The old-style parsing will be removed with the next major version.

New query features

The /structured endpoint, which was optional in previous releases, is now available by default and can be used together with the database dumps from the export server. Be aware though that structured search is still somewhat new and little tested. You are welcome to provide feedback on the Github discussion page.

Version 1.0 newly introduces categories. These are custom tags that can be added to the import data and can then be used for filtering queries. This is much more powerful than the current layer and osm-tag filters. In fact, categories will replace the osm-tag filters eventually. There are currently special categories included except for a category that represents the OSM main tag. So this is mainly something you can use right now when customizing your data to create a specialised search engine.

Finally, there is a new dedupe parameter which switches off the internal result deduplication. This can for example be useful when a street is cut into many sections in OSM and you would like to get all sections instead of just one representative.

JSON import and export

Version 0.7 already introduced an experimental feature for exporting to and importing from JSON dumps. With version 1.0 we have finalized the format and published the official specification. JSON dumps of the OSM planet and selected abstracts are available on the export server. Use them to filter and adapt the data before importing into Photon, to create databases with custom settings (like additional languages) or add your own custom data. We are looking forward to hear what you are doing with this new feature.

Server metrics

If you are running Photon in a production environment that is monitored by prometheus, then the server is now able to export internal metrics like number of queries and query duration or memory usage. The endpoint isn’t enabled by the default, you need to switch it on when starting the server.

 

With this major release, Photon will switch to a more conventional use of the semantic versioning schema. From now on, patch releases will only bring bug fixes and dependency updates. Minor releases may contain new features or change existing ones trying to maintain backwards compatibility. Major releases are reserved for breaking changes in functionality and for changes that require a database reimport. We have a few ideas for more major changes to come, so don’t expect another 12 years to pass before Python 2.0.

Many thanks to Graphhopper, Komoot and Entur for their continued support of Photon development, which has made this release possible.