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-API-KEY

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 and Stadia Maps.

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 an location autosuggest for search forms?

No, currently we do not provide an autosuggest functionality. It’s a difficult feature to provide cost-effectively, especially for the entire world. We may add it in the future, but right now our focus is only on our forward and reverse geocoding API.

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. We use ipinfo, as explained in this post on our blog.

Do you support more than one location per requests (sometimes known as “batch geocoding”)?

No. You can send us only one location (address or coordinates) per request. We intentionally don’t support more as our experience is the the conceptually much simpler “one location, one request” model is much less likely to lead to misunderstandings or errors of implementation, thus saving engineering time, which is the most valuable resource for most companies. Our entire goal is simplicity.

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.

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 continually improving at the rate of many millions of edits per day (thanks OSM volunteers!).

What's behind the geocoder API?

Other geocoders and lots and lots of open data.

Some well known opensource geocoders that we use are Nominatim, Data Science Toolkit and the Two Fishes geocoder, but there are also others.

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

Here's a detailed overview of how our service compares to Nominatim.

I'm already using Google's geocoding API, why should I switch to the OpenCage geocoder?

The two main reasons are better terms of use (because we use open data) and significantly lower cost.

Please see our full overview of migrating from Google's geocoder service, which goes into more detail on the exact differences between the services.

Will you add more geocoders in the future?

Yes, we regularly add more geocoders, typically country-specific geocoders. Please get in touch if you have a specific suggestion.

How are the results ordered?

Results are ordered from most relevant to least. Please see details of ranking on the API page.

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 several million edits per day.

Can I use the API behind a firewall, or in software that requires users to register?

Yes. You can use our API for public and private projects.

Can I use the API in desktop software?

Yes. Your software does not need to be publicly visible on the web.

Can I use the API in closed-source software?

Yes, feel free.

Can I use the API in Google Docs?

Yes, please see instructions on how to use the geocoder in Google Sheets .

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 ( via our contact form), and we'll figure out what the problem is. if possible please include the exact query you made, including all optional parameters. It will help us answer you more quickly.

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.

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?

That said, we really recommend you use our format, as some aspects of our service are different. Please see our full overview of migrating from Google's geocoder service.

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 at multiple, redundant locations in Germany, hosted with a leading hosting provider: Hetzner. They're great and very well connected from a networking standpoint.

Do you need to whitelist my IP address

No, you can access our service via any IP address.

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. Before you fire up your editor though, please read our library guidelines.

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.

Does the OpenCage geocoder return some sort of permanent id or identifier for each location?

No, there is no permanent id that represents a specific location across time. This is a result of us aggregating many different geo databases behind our API.

That said, in the annotations portion of the response we do return numerous types of identifiers for that specific location, that you may be able to use as a succinct identifier.

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. Here's a tutorial explaining how to run the query to our servers from Google Cloud.

We're looking at other ways to limit access, we know keys alone aren't perfect. Here's a good article on techniques for protecting your API key while developing.

Can I cache the results?

Yes, you can store the results as long as you like. Please see our detailed comments on caching.

Do I have to delete the results after I stop being a customer?

No, you can store the results as long as you like.

When will you have feature X?

Can forward and reverse geocoding results be inconsistent?

Yes. You may notice this if you do a forward query and then plug the resulting coordinates back in to the geocoder you may not end up with your original query. Please keep in mind that behind the scenes we are using many different open geocoders. Some are better for forward geocoding, some for reverse geocoding. Entirely different algorithms may come into play. As a result, there is no guarantee that a “round trip” will work.

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

Is OpenCage GDPR (General Data Protection Regulation) compliant?

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.

Does OpenCage store the data I send to be geocoded?

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 six months 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.

Please see our page about GDPR, data protection, and privacy.

Are your servers in the EU?

Our hosting is with Hetzner in Germany, in the EU. Our logs never leave Europe.

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.

Can OpenCage sign a HIPAA Business Associate Agreement (BAA) with my business?

Gladly, if you are a paying customer.

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.

Start your free trial

2,500 API requests per day.

No credit card required.