Migrating from Nominatim



This page lays out some of the differences between our service and OpenStreetMap's Nominatim service, and hopefully helps make the transition to the OpenCage geocoding API as easy as possible.

Comparing geocoding services?

See our Geocoding Buyer's Guide for a full list of all the factors to consider.

Technical differences in API request and response

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.


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.


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 comma separated list in smaller to larger order of 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. Separately we also provide the _type and _category values in the components portion of the result.

One final thing ...

If you do run your own Nominatim we encourage you to join us in also contributing to the Nominatim project and joining the OpenStreetMap Foundation. Open source and open data only thrive with an active, well-resourced community.

On our about page you can see a list of our efforts to support the community. Join us!

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).

Start your free trial

2,500 geocoding API requests per day.

No credit card required.