Guides:
Overview
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.
The major differences between OpenCage and Nominatim
- We use Nominatim, but we also use other open geocoders
- We provide enterprise level reliability
- We enhance the geocoding results with additional information
- Some technical differences
Comparing geocoding services?
See our Geocoding Buyer's Guide for a full list of all the factors to consider.Nominatim, and more
First up, let's be clear: we love Nominatim. So much so that our CTO
is one of the top two Nominatim code contributors of all time.
We are proud to help fund the work on Nominatim, and contribute
our own patches. Nominatim is one of the main geocoders we run
behind our API.
But ...
we also run many other geocoders based on open data.
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.
Rest assured, though, 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.
Enterprise level reliability
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.
More is more
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.
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.
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).
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
and
_category
values in the
components
portion of the result.
|