Frequently Asked Questions

General

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:

https://api.opencagedata.com/geocode/v1/json?q=51.4277844+-0.3336517&pretty=1&key=your-key-here

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.

Do you provide ip address to location (often called "geoip" or "ip2location")?

No. We focus on doing one thing well - a geocoding API. If you need ip to location lookups, there are several free and paid services out there. Have a look at ipinfo, IP Sidekick, or IP Vigilante.

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 requesting too frequently.

Also, we do a lot to enhance the results we send you, adding confidence scoring, annotations, well formatted nice-names.

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?

Better terms and lower cost. Our terms of use make the OpenCage geocoder a more useable and flexible proposition than proprietary geocoders. We don't restrict what you can and can't do with the geocodes you get back, we don't stop you using geocodes for commercial purposes, and we don't try to force you into displaying geocodes on a particular type of map. Finally, you can store the results you receive from us as long as you like.

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 ordered by confidence. Confidence 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, Canada".

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.

Technical

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 support map format which returns the HTML for displaying a map with the results. You specify which format you want in the URL you request.

If customers ask for other formats we'll gladly support them as well. Except Aaron Straup Cope's DSON.

JSON and XML mean nothing to me, why can't I see the results on a map?

Ahh but you can! Just use map as the output format when you're calling the API and instead of json or xml and you'll 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 your browser.

How should I format the address when forward geocoding?

Great question. There is a lot that you can do to make it easier for us to find the correct result. Please see our detailed guide to forward query formatting .

Do you support Google's request or response format?

Yes, by using the google-v3-json 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 https://maps.googleapis.com/maps/api/geocode/json? to using https://api.opencagedata.com/geocode/v1/google-v3-json?

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

Are there other technical difference between the free trial and paid accounts?

There is no difference in the quality of the results. We try to answer all queries as quickly and correctly as possible.

Because paid accounts do not have hard limits, we do not include rate limiting information in the response for paid accounts.

Can I have multiple API keys, each with their own reporting?

If you are a paying customer, yes. If you're on a free trial, no.

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 get responses more quickly?

Several things can help us get you an answer more quickly.

  • Do you need the annotations? If not adding the optional parameter no_annotations=1 will 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=1 marginally reduces the response size.
  • The fastest request is the one you don't make. Can you do more caching ?
  • We cache forward geocoding requests, unless you have specified no_record=1 So it may be slightly faster if you don't use that optional parameter, though it will depend on how common your requests are.
All that being said, generating the response is typically very fast, almost always the bulk of the time is spent in crossing the internet. Our servers are in Frankfurt, Germany and are well connected to the major networks. Nevertheless, there is no escaping the fact that a request from the US west coast - for example - has to cross the Atlantic twice.

Our server performance in monitored by StatusCake You can see our performance here .

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 components 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 the mapper 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 _type key in the components list which is the type of thing we have matched. Please see the API docs to learn more.

I'm nervous about putting my API key in client side javascript. Won't people steal it?

If you put it out there on the internet, yes, it is certainly possible. Our recommendation is to have your javascript send requests to your server where you then call our API. In this way the key is never exposed to the world. We're looking at other ways to limit access, we know keys alone aren't perfect.

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?

Pricing

How much does it cost?

Please see all the details of pricing and free trials on the pricing page.

How does the free trial work?

The free trial tier is limited to 2,500 requests per day. Please see all the rate limiting details . You can use the free trial as long as you like, but please bear in mind that it is designed to be used as a way to test if our service meets your needs. Please do NOT run production services on a free trial. If you want to depend on our service please upgrade to a paid package.

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 we're using the geocoder ourselves. 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 event of any outage.

We use the independent 3rd party service StatusCake to measure uptime of our site and API, please have a look at our recent performance.

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

If you want to learn more please read the human versions of the ODbL and CC-BY-SA licenses as well, just to make sure.

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 wiki. The OpenStreetMap Foundation (of which we're proud to be a corporate member) has released geocoding guidelines in which they make clear that "the share-alike obligations of the ODbL are not triggered" by almost all geocoding cases.

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. When you register for your key, you will need to provide us with an email address.

If you have concerns about us seeing your queries please see below regarding the no_record parameter.

Do you store the data I give to you to be geocoded?

Indirectly yes. We're not interested in what you send to us, but as the query is part of the request 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 no_record parameter (see the full list optional request 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.

Get started with our free geocoding plan

No credit card required

Create your free account