What is a geocoder?
A geocoder turns geographic coordinates (latitude and longitude) into a geographic reference - such as an address, a place name, or locality - or vice versa. The good folks at Wikipedia explain this far better than we can.
Do you do forward geocoding?
Yes, with our API you can do "forward geocoding" which is the process of turning an address or place name into coordinates.
What about reverse geocoding?
Yes, we can gladly also do "reverse geocoding" which means turning coordinates into a human understandable place name or address. Just pass the coordinates as a latitude and a longitude, separated by either a comma or a (URL encoded) space and the API will automagically work out that you want to reverse geocode. Here's an example:
Do you make maps?
No. We focus on doing one thing well - a geocoding API. If you need custom maps, there are many great services out there. We recommend Thunderforest.
Do you provide routing?
No. As above, we focus on doing one thing well - a geocoding API. If you need routing, we recommend having a look at Graphhopper a great OpenStreetMap based routing service.
What countries can you geocode for?
All of them; there's worldwide, global coverage. But it will vary from country to country, and even within countries. Coverage will depend on the data sources we use. At a minimum we're as good as OpenStreetMap is, and OpenStreetMap is constantly improving (thanks OSM volunteers!). Here's a great tool that allows you to get an overview of OSM's coverage and evolution over time.
What's behind the geocoder API?
Other geocoders and lots and lots of open data.
There's Nominatim, Data Science Toolkit and the Two Fishes geocoders.
All of this is built on open geospatial data including OpenStreetMap, Yahoo! GeoPlanet, Natural Earth Data, Thematic Mapping, Ordnance Survey OpenSpace, Statistics New Zealand, Zillow, MaxMind, GeoNames, the US Census Bureau and Flickr's shapefiles plus a whole lot more besides. Here's the full list of datasources.
So why shouldn't I just use those opensource geocoders directly?
A few reasons.
First up, hosting your own software and keeping it up to date (and keeping the underlying data up to date) can be a non-trivial technical challenge. It will cost you time and effort. If that type of opsy problem is your thing, go for it. Or you can just let us handle it, and instead get on with geocoding.
There are proprietary geocoding services, and technically some are really very impressive. But typically they cost a lot and/or severly limit what you can do with the results.
There are other hosted open geocoding services, most obviously OpenStreetMap's own Nominatim service. However that is designed to be used as a tool by mappers, not as an enterprise level geocoding service, and indeed the usage policy explicitly says it "has a very limited capacity" and users may be blocked if querying too frequently.
Finally, you can feel good about the fact that we're regularly sponsoring open geo events (we run #geomob in London), contributing code back to the major OSM software projects, opensource many of our own projects (pls send patches!), and are corporate members of the OpenStreetMap Foundation.
I'm already using Google's geocoding API, why should I switch to the OpenCage geocoder?
Will you add more geocoders in the future?
Yes, please get in touch if you have a specific suggestion.
How are the results ordered?
Results are ordered from most correct to least. They are NOT
is purely a measure of size of the resulting bounding box. As an
example, a search for "London" will return "London, UK" first even
though it has a lower confidence score than "London, Ontario,
Do you support bulk geocoding?
No, currently the OpenCage Geocoder can only be accessed via our API on a single request basis. If bulk geocoding is important for you let us know.
Can I use the API in Google Docs
Yes, please see instructions on how to use the geocoder in Google Sheets.
How frequently is the underlying data updated?
We're currently updating from OpenStreetMap daily. During our beta period we saw that more frequent updates were not very useful while leading to a hit on database speed. OpenStreetMap averages well over a million edits per day.
The results you're giving me are wrong; have I found a bug?
It's possible. You might have found a bug in the API, but you might also have found a hole in the underlying data. Let us know and we'll figure out what the problem is. We're continually working on making it much easier to feed corrections back to us (and of course back to OpenStreetMap).
I always call it OpenStreetMaps (with s), am I wrong?
Yes, you are wrong.
Who makes the OpenCage Data geocoder?
Peak behind the curtain over on our about us page.
What output formats do you support?
JSON (and jsonp) because it's (mostly) easy for humans to
read and easy for applications to parse. Some people like XML
or GeoJSON, we support those too.
We also support Google's JSON response format
if you want a drop in replacement - see below. Finally we also
format which returns the HTML for displaying a map
with the results. You
specify which format you want in the URL you request.
JSON and XML mean nothing to me, why can't I see the results on a map?
Ahh but you can! Just use
as the output format when
you're calling the API and instead of
get back HTML that renders a map. If you're calling the geocoder
in the browser you'll see the map, otherwise if you're using geocoder
from the command line you'll need to view the resulting file in
Do you support Google's request or response format?
Yes, by using the
output format. At a
high level swapping from using v3 of Google's geocoder is as
simple as changing the URL of a geocoding request from using
On the request side we support the address parameter, we don't currently support Google's components, bounds, language or region parameters. On the response side, the JSON data you get back from the geocoder should be identical to Google's.
Do you support geocoding over HTTPS?
Yes. Please do all your requests via https.
How many requests can I make per second?
It depends if you are on the free trial or a paying customer. Free trial users are limited to one request per second. Paying customers can go much faster, please see the pricing page for exact numbers.
Where are the OpenCage servers?
Our servers are in Germany, hosted with a leading hosting provider. They're great and very well connected from a networking standpoint.
Will you add servers in region X (where X is whatever your favourite place is)?
Sure, happy to discuss it if you're a large or enterprise customer.
What can I do to make queries faster?
Several things can help us get you an answer more quickly.
Do you need the annotations? If not adding the optional
no_annotations=1will skip that step and let us respond slightly more quickly. It also reduces the size of the response considerably.
Likewise, turning pretty printing off, ie NOT using
pretty=1marginally reduces the response size.
- The fastest request is the one you don't make. Can you do more caching ?
- Behind the scenes when you make a request, we make a request to 3scale, the service we use for account management and rate limiting. We turn that step off for customers, since they have no hard limits. So becoming a customer, even an x-small customer makes it faster.
I don't want to write code to use an API, do you have any ready made libraries?
Yes several, and we're working on more . They're all on github, feel free to contribute; we're looking forward to your pull requests. If we don't yet have your language of choice, apologies. We're working on it. Feel free to help move things along more quickly by creating your own library which we'll gladly feature.
Is there a definitive list of all the possible keys of the
field of the response?
Unfortunately, no. The world is, as you've possibly experienced,
a crazy and chaotic place. The great strength of crowd-sourced
projects like OpenStreetMap is that it is very flexible, to allow
on the ground to enter whatever he or she needs. The flip side
of that, though, is that hundreds of thousands of people around
the world have been entering data. So it can, unfortunately, be
a little chaotic. Over time best practices have emerged and
usually the output is well structured. But not always.
It's exactly for this reason that
we provide a formatted place name.
We also provide the
key in the
list which is the type of thing we
have matched. Please
see the API docs to learn more.
Can I cache the results?
Yes, you can store the results as long as you like. Please see our detailed comments on caching.
When will you have feature X?
How much does it cost?
Please see all the details of pricing and free trials on the pricing page.
Can you give me uptime guarantees and a service level agreement (SLA)?
For paying customers, yes. Please see the details on our pricing page. But all users should rest assured that in the spirit of eating our own dog food, we're using the geocoder ourselves and if it's down for you, it'll be down for us too and we'll be trying to fix it. Please follow us on twitter where we'll communicate in the rare event of any outage.
Why can't I just register lots of accounts and use them up to the free limit as a way to get out of paying anything?
First up, many thanks to all of you that don't do this. By playing within the rules you enable us to work on this service (and the open source software that it runs on). You are awesome.
But assuming you have no moral qualms about abusing our generous service, be warned that when we see you doing this we will start feeding you back randomly wrong results. Enjoy!
What restrictions are there on using OpenCage results?
The geocodes the API returns are jointly licensed under the ODbL and CC-BY-SA licenses. You can cache your geocodes, store them however you want, use them however you want, even commercially. You will need to attribute properly, please see example in the next question
How do I attribute OpenStreetMap properly?
On your about page or similar page where it can easily be found add "Geodata copyright OpenStreetMap contributors". It should of course be in the language of your service, not necessarily in English.
Learn more about attributing OSM over on the OpenStreetMap site. And of course now that you are using OpenStreetMap data, maybe you're interested in becoming a mapper yourself? If so Learn OSM is a great resource for getting started.
Do I need to attribute OpenCage or just OpenStreetMap?
There is no need to attribute us, it's not our data. Nevertheless if you find our service useful it would be absolutely ace if you told the world. Good karma will flow to you like an unending river, which is always helpful.
What about privacy?
Our goal is to help you geocode, not to spy on you. We require registration so that we can track usage. To do that we work with a third party (3scale) who are experts at API management. When you register for your key, you will need to provide them and us with an email address.
When you query our API we ask 3scale how many queries you have used. 3scale never sees your actual query, only we do.
We are currently in the process of moving away from 3scale, we hope to no longer be using the service by the end of Q1 2017.
If you have concerns about us seeing the query please see below
Do you store the data I give to you to be geocoded?
Indirectly yes. We're not interested in what data you send to us, but as the data is part of the query you send to the API, it'll be stored in our server logs. If something goes wrong, we use the logs to help us work out what went wrong and how to fix it. After a few weeks the logs are automatically deleted.
You can use the optional
the full list optional query parameters
in which case we do not log the query you send to us.
We still record that you made a request, but not the specific
query you made.
Are your servers in the EU? Does my data leave the EU?
Our hosting is with Hetzner in Germany, in the EU. Our logs never leave the EU.
Can I hold OpenCage Data liable if I use this data?
No. All data is supplied "as is" and with no warranty. Use common sense.
That all sounds good, but surely you have really complicated terms and conditions?
No. Please see our terms and conditions. We keep it as simple as possible. Basically, obey all laws, obey the data license, and you can't hold us responsible for the correctness of results. If you abuse the service we may cancel your account. So don't do that.
We look forward to working with you.