Migrating from Nominatim

First up, let's be clear: we love nominatim. So much so that our CTO is one of the top three nominatim code contributors of all time.

Nominatim is one of the main geocoders we run behind our API. But, we also run many others.

Why? The same reason you don't eat all your meals with a spoon. Different tools are better for different tasks; different geocoders and different datasets are better for different types of queries.

But rest assured we love OpenStreetMap and nominatim, and we're proud to be corporate members of the OpenStreetMap Foundation and do our part to support open data and open source software.

If you are considering using OpenStreetMap's public hosted nominatim service for anything other than a small hobby project, you should not. That's not our opinion, it's the official OSM usage policy. The service they offer is designed for mappers to query OSM, it is not an enterprise level service. The official OSM instance of nominatim offers limited and/or no support, no SLA or uptime guarantee.

Running your own instance of nominatim is certainly doable if you have the operational skills. That's the great thing about open-source software; it is there for all to use (and contribute back to). Nevertheless, in the same way that you can repair your own car or bake your own bread, most people find it more convenient to leave it to the experts.

We have multiple, fully-redundant data centers. Our service is continually (and publicly) monitored by an independent third-party (see our status dashboard), and we're serving hundreds of customers around the world.

We are a long-term, stable partner who removes the operational headaches of operating and maintaining your own service.

We enhance our results with annotations (information like timezones, calling codes, FIPS codes, currency, what3words, time of sunrise/sunset, and more), well formatted address strings, and confidence scores.

The end result is we save expensive developer time and effort.

You should of course take a look at our API documentation for the full details (don't worry it is a single page), but here we attempt to layout some of the key conceptual differences between the two services.

API End Points	The OpenCage Geocoding API has a single end point for both forward and reverse geocoding. Nominatim has multiple different end points.
Authentication	We require an API key, supplied in the key= parameter. You will find your key in your account dashboard. OpenStreetMap's hosted Nominatim doesn't require authentication but does ask you to supply an email
Query Parameters	Nominatim requires different parameters depending on which end point you are querying and the type of query you are making, for example the q= parameter for forward geocoding and lat= and lon= for reverse geocoding. We instead require q= for both forward and reverse geocoding. See the request format documentation where you can also learn about the various optional parameters we support.
Output Formats	We support JSON, XML, and GeoJSON. Nominatim supports XML, HTML, and two versions of JSON.
Structured Queries	Nominatim supports some types of structured queries. We do not. This is intentional, our goal is to keep the service as simple as possible for developers to comprehend and get productive with our service. Please follow the steps laid out in our guide to query formatting.
Annotations	By default we provide lot of other relevant information about the location of each result, things like the local timezone, currency, various other ways of referring to the locations (geohash, what3words, etc), and much more. We call these annotations. You can use an optional parameter to request additional information from nominatim, but only the information that is in OSM.
Address Components	Both services return different components of the location hierarchy, Nominatim does this in a field called address, we do it in the components portion of the result. Learn more about our components. The comprehensiveness and values may differ between the two services.
Display Name	We convert the various pieces of the address (the components) into a well formatted (according to the norms of the local country) display name. You can find this in the formatted field of our response. Nominatim returns a field called display_name with relevant information but it is not in the format of local addresses. It is just a csv of all the pieces of the address. As an example, if you geocode the coordinates 52.51627,13.37769 we return the correct address format for Germany: Brandenburg Gate, Pariser Platz 1, 10117 Berlin, Germany Nominatim returns correct information, but not formatted correctly: Brandenburg Gate, 1, Pariser Platz, Mitte, Berlin, 10117, Germany
Location Type	Nominatim returns the type of match in a field called type. We provide a confidence score that tells you the size of the result. Seperately we also provide the _type key and value in the components portion of the result.

Please get in touch if you have any questions about how our service differs from OpenStreetMap's nominatim (or any of the other open geocoders we rely upon).