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 Photon 2.0.

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

One of the important applications for geocoding is routing: you give the router a start and a destination address and then expect it to find a route in between. Start and destination address are usually sent to a geocoder to convert them into a set of coordinates. The problem here is that geocoders and routers have a slightly different view of the world: when a geocoder is asked for an address, it will return the building that belongs to the address. The router on the other hand only knows about the road network. So it has to make an educated guess on which street you actually want to start your journey. That usually works okay for smaller buildings but when it comes to larger structures like parks or airports the outcome might not be what you expect:

That’s where entrances come into play. Instead of just returning the center point of a location, Nominatim now adds the information where the location can be entered and exited. An entrance is usually much closer to a street from which the router can start the journey. Here is an example for Comox Airport, British Columbia:

The blue circle describes the point that Nominatim returns to the router per default. The red circles are the entrances. Using them, them router can bring you right to the terminal.

To use the new information, add the entrances=1 parameter to your request. If the result has entrance information an entrances field with a list of entrances will be added. For each entrance you get its type, coordinates and any extra tags that might be available. Please give it a try, especially if you are writing or using a routing engine, and let us know what kind of information about the entrance is useful for you.

Entrances are widely mapped in OpenStreetMap but not much used so far. That means that the tags around entrances are not well standardized yet. Making them more visible and usable through Nominatim hopefully helps getting a wider discussion going. There are a couple of limitations to the new entrance feature that need more discussion:

• Entrances are only added for OSM ways. Multipolygons or sites that are mapped as OSM relations are currently ignored because it is unclear where to look for entrances. There is a proposal for a special entrance member for relations but it isn’t widely used yet. Another option would be to look for entrances on outer members.
• When dealing with complex locations like shopping malls or airports, then finding the routing endpoint can become much more complex than just going to the main door. The right access point may depend on your mode of transport, the purpose of your visit (departure or arrival) and which parts of the location you want to access. This might need more fine-grained tagging in OSM or it might be solved through more complex routing algorithms or more precise geocoding.
• Entrances are of limited use, when the location you want to get to is part of a larger complex with special entrances. To reach an address in a gated community, you need to be routed to the guest entrance of the community, not the address directly. As before, there is no suitable tagging for OSM yet, to express such a fact.

Entrance output is available in preview on https://nominatim.openstreetmap.org. Right now only entrances for recently edited data is available. You can check in the details view of the Nominatim UI, if entrances for a location are in the database: search for the location, then click on ‘Details’.

Many thanks to @emlove for implementing this new feature and to @mtmail for adding entrance display to the Nominatim UI.

Region extracts replace country extracts

The old site used to host one large planet dump and then country extracts in the extracts/by-country-code/ directory. The new layout rearranges how you can find extracts: they are now organised by continent with each continent giving you a list of available country extracts. For you as a user that means that all file locations and names have changed.

Some of the country extracts were really tiny and didn’t make much sense to have on their own. They have been merged to subregions like the Caribbean islands. If you need a single country from that subregion, download the JSON dump and create a Photon database with a country filter. The section on JSON dumps below explains how this works.

With the new structure, there will now also be extracts for continents on offer. This will hopefully reduce the hardware requirements on disk space for those of you that don’t need the entire planet but still want to have multiple countries.

Photon database dumps

The database dumps are the unzip-and-go database dumps we have always provided. These are now available for the planet, all continents and some selected countries. Do remember that the naming schema has changed slightly. Database dump file names now start with ‘photon-db-‘ and have the suffix ‘.tar.bz2’.

Usage of these dumps hasn’t changed: download the dump, unpack it and start Photon.

There are no database dumps anymore for smaller, less popular countries. If you need a Photon database for those countries, you have to create your own database from the JSON dumps as described in the next section. This usually won’t take more than an hour.

With version 0.7 being a transitional release between the old ElasticSearch backend and the new OpenSearch backend, we publish dumps for both versions. Please make sure that you download the right dump. Photon 0.7.3 and later will refuse to start if you use the wrong file.

Photon JSON dumps

The download site now also allows you to download JSON dumps of the Photon data. These dumps are available for the planet, continents and as country extracts. JSON dump files start with ‘photon-dump-‘ and have the suffix ‘.jsonl.zst’. They use the newer zstd for compression. Make sure you have the appropriate tool installed.

JSON dumps give you the raw data with which you can build your own Photon database. Apart from being much smaller than the database dumps, they are also more versatile: they contain a lot more languages¹, the (almost) full set of OSM tags as ‘extratags’ and the full geometries of the objects. Starting from a JSON dump, you can create localized databases, databases that allow structured search and databases that return the full geometry.

You can also combine smaller extracts into one database. Need a geocoding server for Benelux? Download the extracts for Belgium, the Netherlands and Luxemburg. Then create the database by concatenating the downloaded files together:

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

Or you can go the other way around. Download the JSON dump for Europe and then filter for the countries you are interested in during the import:

zstd --stdout -d photon-dump-europe-0.7-latest.jsonl.zst | java -jar photon.jar -nominatim-import -import-file - -countries be,nl,lu

Updating a database from JSON dumps

Once you have created your Photon database from a JSON dump, you might want to update the data from time to time using a more recent JSON dump. You can do this while the old database is up and running. Just make sure you use a different cluster name and database location while you do the reimport.

In short, the steps are:

1. Create a directory for the reimport and change into the directory:

   mkdir /srv/photon-reimport
   cd /srv/photon-reimport
   

2. Download the newest extract. Then import it with the same options you used for the original import, adding the cluster parameter:

   zstd --stdout -d photon-dump-*.jsonl.zst | java -jar photon.jar -nominatim-import -import-file - -cluster photon-reimport
   

3. Switch out the original database with the newly imported one (here we assume the original one is in /srv/photon):

   mv /srv/photon/photon-data /srv/photon/photon-data.old
   mv photon-data /srv/photon/photon-data
   

4. Restart your Photon server. The newly imported database will now run inside the original cluster ‘photon’.

Which version do I need?

The new download site points you now directly to the right dump to match the Photon version you are using. We will usually provide extracts for one or two versions back, so you have a bit of time to switch over your setup. Keep in mind though that only the dumps for the latest version are guaranteed to receive weekly updates.

You will also always find a master version of the dumps. These are the dumps created from the current main development branch. (They used to be found in the ‘experimental’ directory before the restructuring.) They are mainly meant for testing for developers but you are welcome to try out the latest features and give us feedback.

Try it out!

The new layout will hopefully make it easier to find and use the appropriate data to create your own customized geocoding database. The old file locations will keep working for another couple of months. So you have some time to adapt your setups. The old files won’t receive updates though. If you need it fresh, switch now.

Many thanks to Graphhopper who make the Photon export service possible by generously sponsoring the server.

Auto-completion and spelling correction

Search-as-you-type and some leniency towards spelling mistakes are without a doubt on the top of the list of feature requests for Nominatim. Search-as-you-type will require to change how the internal search indexes are built and accessed. Nominatim’s current search model is not compatible with resolving incomplete queries. When it comes to spelling correction, we are going to need a good model for estimating the similarity between a query and the place names in the database. Simple approaches like Levenshtein distance are difficult for a multi-lingual database of proper names.

Performance and Index Optimisations

A full planet database requires now more than 1TB in disk space. This means that it reaches the limits of what can be done with of-the-shelf hardware. Worse, the search indexes in our backing PostgreSQL database have grown to a size where lookups are becoming noticeably slow. It is time to revisit our database schema, see where tables can be optimised and trimmed down, and consider how search indexes might be better organised differently to trim them down to what is relevant for finding the right place.

Complex OSM objects

Nominatim’s entire processing pipeline is built in a way that it considers one OSM object at the time. That makes processing and updating easy but it doesn’t fit well anymore with how data is modelled in OSM. We increasingly see detailed mapping where multiple OSM objects make up a single real-world object that you may want to find with search. To accommodate that Nominatim’s processing pipeline needs to be adapted, so that it can work with places that do not have a 1:1 equivalent in the OSM world. This also means that the output needs to change. Every result of a search is currently tied to an OSM object. In the future, it is more likely that you will get an abstract place description with references to all the relevant OSM objects.

Addresses as first-class citizens

Physical addresses are not considered searchable places on its own in Nominatim right now. Addresses only appear as an attribute of a place and when you search for an address, you will in fact get all place objects which happen to have the address assigned. That can cause a lot of issues. For example, the more detailed the mapping in OSM becomes, the more objects will be returned for an address search, even though you would have expected exactly one result. Inversely, there are sometimes OSM objects that have more than one address. For example, some house entrances come with multiple house numbers. Or there are houses where the address has changed and which you’d still want to find under its former address. All this cannot be modelled in Nominatim right now.

To enable a true address search, addresses need to become first class citizens in Nominatim that can be directly returned as a result. Places would of course still keep their address attributes but those will only be references to one or more address they can be found under.

Complex categories

Every place in Nominatim currently gets a simple category which is derived from the main tag of its OSM object. This puts some limitation on what kind of category search Nominatim can do. For example, you cannot search for a “vegan restaurant” or a “catholic church” because the main tags only classify “restaurants” and “places of worship of any religion”.

Another issue with the current classification system is that it is bad at handling OSM objects with multiple functions (say, a hotel with an attached restaurant mapped with the same POI node). Nominatim will simply duplicate the OSM object in its database to cover both functions. That unnecessarily blows up the database size.

So it is time to get a way from using OSM tags directly and introduce the ability to define custom classifications. The idea here is to have hierarchical categories (e.g. food.restaurant.vegan) and allow to assign an arbitrary number of categories to each object.

These are the main open issues right now. If one of them sparks your interest and you’d like to help moving them along, don’t hesitate to get in touch. The discussion section on Github and the OSM community forum are great places to start a discussion.

This release finishes the mutation of Nominatim into a Python package. The PHP frontend, bundled osm2pgsql and cmake build scripts have now been removed for good. If you are still using one of these features, then you should update your software to Nominatim 4.5 and then move to the new Python frontend and pip installation. Once done, you can easily update to the latest version 5 release.

Also in this release, the osm2pgsql import style configuration has been largely be rewritten. If you are using one of the built-in styles, this will not make much of a difference. If you are maintaining your own custom style, however, this should become much easier. Most notable, it is now possible to start with one of the existing styles and add your customizations on top. That should make it much easier to keep in sync with the latest changes in Nominatim. Have a look at the updated documentation for details. The new implementation is largely backwards compatible, so your old scripts will keep working for now.

With the new osm2pgsql style implementation comes the ability to use Nominatim together with osm2pgsql-themepark. This comes in handy when you want to combine Nominatim with other osm2pgsql flex styles in order to host OSM data for different purposes in the same database. Check out the updated cookbook about how to run Nominatim with osm-carto to learn how to use this feature.

Finally, Nominatim has a new hook for adding pre-processing functions for incoming search queries, allowing to apply custom filtering. The first filter to use this new functionality breaks up Japanese addresses into their parts.

A full list of changes can as always be found in the Changelog.

Participating in an open-source software project like Nominatim or Photon is not just about the implementation of fancy new features or clever algorithms to improve performance or the user experience. A lot of work happens quietly behind the scene: user questions need to be answered and bug reports followed up. Dependent software needs to be monitored and updated as necessary. The own code needs to be reviewed and polished regularly to prevent it from ageing and slowly falling apart. CI pipelines are a great tool for a maintainer but they do break with an astonishing regularity and therefore need regular attention. Not to mention that a CI is useless without a set of well-maintained tests.

With its new Sovereign Tech Fellowship programme, the Sovereign Tech Agency recognises the importance of this maintenance work for the general functioning of the open source ecosystem. The programme will financially support my day-to-day tasks of software maintainership: responding to issues on Github, reviewing and merging pull requests, fixing reported bugs and addressing security issues, improving documentation and tests, preparing releases etc. On top of that there are some other not so glorious maintenance tasks that are planned for this year.

Nominatim’s import module relies on a datrie library, which has been unmaintained for some years and no longer compiles with the newest GCC compilers. We need to find a solution to that by either switching to a new library or taking over maintenance. A similar fate is likely in store for the testing library behave. With the latest stable release from 2018 and very few activity since, it is unclear how long it will remain functional with new versions of Python.

Photon has seen the move to OpenSearch 8 last year. This transition is far from finished. For example, there is still no proper support for using an external instance of OpenSearch instead of the embedded one. And ElasticSearch/OpenSearch itself has also seen some improvements in the last three versions we have skipped. It’s well worth investigating how geocoding can benefit from them.

These will, of course, not be the only things happening in 2025 for Nominatim and Photon. There will also be shiny new features and I have some ideas for improving performance and how to better handle the increasing complexity of OSM data. However, none of this can really happen, if the basis isn’t there and the general maintenance isn’t cared for.

Many thanks to the Sovereign Tech Agency for this great opportunity and the recognition of the importance of maintenance work for software.

If you want to support development and maintenance of Nominatim, too, please consider becoming a Github sponsor.

The most important change in this release is that Nominatim is now available via pypi.org and can be installed with a simple pip install nominatim-db nominatim-api. We had to change the package structure slightly to make this possible, splitting the nominatim package into two parts: nominatim-db (the database importer) and nominatim-api (the search frontend). Please carefully read the migration guide about how this change might affect you. The old way of installing with CMake is still available in this release. So you can take your time updating to the new installation method. Nominatim 5 will then only be installable via pip.

Other new features in this release include the possibility to customize API output for web installations, a streamlined file format for wiki importances, improvements to ordering results according to how well address parts match and a more consistent assignment of countries in disputed areas. A more complete list of changes can be found in the Changelog.

This is the last release to have support for PostgreSQL 9.6 and 10 and Postgis 2.x. These version have long gone out of support, so it is time to drop them.

Furthermore, the following Nominatim features will be removed with the next release:

• PHP frontend. Please switch to the newer Python frontend instead.
• Legacy tokenizer. If your database still uses this tokenizer, you need to reimport using the ICU tokenizer.
• Installation via CMake. Switch to using pip install instead.
• Bundeling of osm2pgsql. Use a stock osm2pgsql version 1.8 or higher. Ubuntu 24.04 and Debian >= 11 have appropriate packages. The packages of older Ubuntu version are too old and you need to compile a newer osm2pgsql from source.

Looking at a places’ type (city vs village), size, OpenStreetMap tags, population all have disadvantages, usually simply lacking a good data source for the whole world. We even tried looking at how often tiles were loaded for regions on tile.openstreetmap.org (Google Summer of Code project 2022) but that’s not granular enough.

Wikipedia turned out to be a good approximation or “importance”. Basically if a place has a Wikipedia article, and how many other articles link to it? And we can turn that into a single number.

As early as 2014 (version 2.2) Nominatim had the option to imported additional scoring files. Those files were created from Wikipedia metadata. First using their pageviews, later based on links between Wikipedia article, links between Wikipedia projects (languages), then including redirects and now even taking Wikidata into account.

The scoring file contains language code, Wikipedia article title, Wikidata id, redirect titles and a score number for 17 million titles. Nominatim matches the title against place names.

Many places in OpenStreetMap data already have the wikipedia and wikidata tags. That’s helpful for us, please continue to add those. On Wikipedia many places contain coordinates. Again that’s helpful: we can determine if an article is about a place instead of for example a movie title, band name or pastry.

Over the years creating the scoring file became unmaintained while the data to process grew massively. Just English Wikipedia contains 900 million links! The metadata for the 40 largest languages is 40GB compressed (about 90% compression rate). We had a major rewrite of the processing during the Google Summer of Code 2019 project but it loaded all data into a database. Processing took several days each time, was error-prone and we rarely ran it.

In the last year we got the processing down to a manageable 12 hours. This will allow us to publish updated importance file much more frequently. We have also streamlined the format and publish it now as a simple CSV file. If you have other uses besides geocoding in mind, you are welcome to use it. You can read the full details about how the file is made and what it contains at https://github.com/osm-search/wikipedia-wikidata#readme. The updated file can be downloaded at https://nominatim.org/data/wikimedia-importance.csv.gz.

Nominatim itself will receive full support for reading then new CSV file format in the upcoming version 4.5.

Version 4.4.0 of Nominatim brings many bug fixes and performance improvements for the new Python frontend, which was introduced in version 4.3.0. It can now be considered stable and has become the frontend recommended to be used for new installations. You find deployment guides for the Python frontend in the documentation. There is no need to reimport your existing database. It will work perfectly fine with the new frontend.

A new feature in this release is experimental support for exporting a Nominatim database to SQLite. The SQLite database can then be used with the new Python frontend or when using the Nominatim library. For more information about this, watch the talk at SotM-EU 2023 or read about it in the SQLite blog posts.

Version 0.5.0 of Photon brings back the ability to update a Photon database from a Nominatim database. The new mechanism is better decoupled from the Nominatim update process, making it easier to handle. A long-standing issue around UIDs of house numbers documents has been fixed so that all data should now be correctly handled. This version also introduces a new API endpoint /nominatim-update/status which allows scripts to check if an update is already in progress. To find out if your Photon database is indeed up-to-date use the newlt added /status endpoint.

If you do not use the update facility, then the Photon release remains compatible with version 0.4 database dumps including the ones available on https://download1.graphhopper.com/public. If you want to run updates, you need to create a fresh import using this release. Please be aware that updates now require an additional preparation step. Consult the README for more information.

Changes in Nominatim 5

To make the rewrite of backend and frontend as smooth as possible for the users, there is a lot of code in Nominatim right now, which still supports much of the behaviour from before the rewrite. Getting rid of this code not only makes Nominatim easier to maintain but also opens up the possibility to convert it into a pure Python package.

Removal of PHP

With the frontend renovatations finished, all major parts of Nominatim are now written in Python, it is time to remove the last traces of PHP code. With version 5 the PHP frontend code will be completely removed.

Unbundling osm2pgsql

For many years Nominatim has shipped its own version of osm2pgsql. This was because it didn’t use the standard output of osm2pgsql but came with its very own gazetteer output. Nominatim and the gazetteer code needed to be in sync to function optimally. About a year ago, Nominatim has switched to osm2pgsql’s flex output. All customization can now be kept in simple Lua configuarion files within Nominatim and used with an off-the-shelf version of osm2pgsql. Version 5 will remove the ability to work with the former gazetter output and require that you install osm2pgsql externally. This should not be a big issue as osm2pgsql is well supported by all major distributions.

Removing the legacy tokenizer

The final part to be removed in version 5 is the legacy tokenizer. The code is a reminder from the rewrite of the import backend. It is far less powerful than the ICU tokenizer, which has been the default since many versions. The legacy tokenizer also requires a special PostgreSQL plugin which is difficult to compile and run. Removing the legacy tokenizer will allow to simplify the code in many places.

Changing from CMake to pip

With osm2pgsql and PHP code removed, Nominatim becomes an almost pure Python application. As such is will be possible to get rid of the heavy CMake build system and switch to Python installation methods. Installing Nominatim will be become as easy as pip install nominatim in version 5.

Without C code to compile, there is also nothing in the installation process anymore that prevents Nominatim from being installed on Windows and MacOS.

Timeline

The list of changes might look large and intimidating but you don’t need to worry. All this will not happen suddenly and there will be ample time for you to adapt your installation. Here is the timeline of planned versions for next year:

• 4.4.x - Q1 2024

  This version will remove the experimental flag from the Python frontend and make it the default choice. If you have an existing installation, you should change from PHP to Python at this point.

• 4.5.x - Q3 2024

  This version deprecates the bundled osm2pgsql, the legacy tokenizer and the PHP frontend. It introduces the new installation method via pip while still offering the old CMake method of installation in parallel. The pip installation will also make it easy to use Nominatim as a Library. If you run automated installation scripts for your production machines, you should update them with this version.

• 5.0.x - Q4 2024

  The first major version of Nominatim 5 has all deprecated modules removed and can only be installed via pip.