Frequently Asked Questions

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

Yes, with our API you can do "forward geocoding" which is the process of turning an address or place name into coordinates.

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

If you'd like to learn more about reverse geocoding you may find our comprehensive guide to reverse geocoding useful.

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.

No. As above, we focus on doing one thing well - a geocoding API. If you need routing, we recommend having a look at Graphhopper and Verso (who focus on routing optimization). Both are great open-source / open data based companies.

Our API accepts only a single location (pair of coordinates) per request, we do not accept tracks or a series of points. We do allow you to geocode to the nearest road by using the optional roadinfo setting. Please see the relevant details in the API documentation.

Yes! We call it Geosearch.

Please see our guide to the differences between geocoding and geosearch.

No. We focus on doing one thing well: geocoding.

Please see our detailed guide to difference between IP geolocation and geocoding.

No, that's a process known as browser geolocation, it's a different concept than geocoding.

Please see our detailed guide to browser geolocation and how to use it in combination with geocoding.

No. There are tutorials that phone number parsers (e.g.'phonenumbers' Python library), but they only return the country of the phone number. Please see our blog post about this.

Sorry, but yes, you are wrong.

Peek behind the curtain over on our about us page.

Yes, in your account dashboard you can change your email address at any time. You will just need to confirm the new address by clicking on a link in the confirmation email we send you.

Anyone can use your API key, all they need is the key. Subscription customers can create multiple API keys and can assign the API keys labels in their account dashboard, for example "testing", "dev", "production", etc.

Each account is tied to one email address, we do not have any sort of limited account access, or administrator role. If you want to make access available to a team the simplest way to do that is by using a generic email address.

Yes. Customers can specify an email address for all billing related matters in their account dashboard.

Yes. We support 2FA via authenticator apps like Google Authenticator and Authy You can enable 2FA in the "Account" section of your dashboard.

Yes, you can do so in the "Account" section of your dashboard. If you are a subscription customer you will have to first cancel your subscription.

Please note: inactive accounts are automatically deleted after three months.

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

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

The free trial 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, upgrade to a paid plan.

We pride ourselves on our reliability, and target 100% uptime with no scheduled maintenance windows. We use independent, 3rd-party monitoring to measure uptime of our site and API, please have a look at our recent performance.

If in doubt please get in touch, we work with hundreds of customers large and small around the world, and feel confident we can deliver a solution that works for you.

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!

Yes, we also offer one-time plans in various sizes, you can find the details on our pricing page.

If you don't have the technical skills to query the API yourself you may wish to use our spreadsheet uploading service, which you can find in your account dashboard.

If in doubt, please get in touch with us.

We are much more affordable and customer-friendly (no surge pricing).

Here's a detailed pricing comparison with numbers.

Excellent, we have several customers who fall into that category. Please see our Enterprise offering. We look forward to working with you.

No. All data is supplied "as is" and with no warranty. Use common sense.

Yes, please see our page about GDPR and data protection.

Yes, please see our page about HIPAA compliance.

Gladly, if you are a paying customer. Please see our HIPAA compliance page.

On your about page or similar page where it can easily be found add "Geodata copyright OpenStreetMap contributors". It should 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.

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.

Please see the citation section of our branding page for the exact wording you should use.

Please see the citation section of our branding page for the exact wording you should use.

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.

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

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.

No. Here is why we do not.

We do however offer the ability for you to upload a spreadsheet of addresses or coordinates which we will geocode for you. Please see the spreadsheets section below.

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

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.

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 the geo meetup Geomob), 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.

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 Maps geocoding, which goes into more detail on the exact differences between the services.

That said, there is no requirement that you use only our service. Many people use our service AND other services like Google. This typically works out to be more cost effective than just using an expensive service like Google.

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

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

We're currently updating from OpenStreetMap daily. Our experiments have shown that more frequent updates are not very useful as they lead to a hit on database speed. OpenStreetMap averages several million edits per day.

No. We discuss the reasons why not in the API documentation.

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

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

Yes.

Yes, but you may be better off using our spreadsheet upload functionality. See the details below.

Nevertheless, we also have tutorials on how to use the geocoding API in Google Sheets or in Excel.

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. Here's a tutorial covering how to add an address to OpenStreetMap.

You specify which format you want in the URL you request. We 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 details.

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 geocoding query formatting.

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

Yes. Please make all your requests via https. Please note, as a security measure, from 15 September 2020 we will drop support for HTTPS requests using HTTPS TLS 1.0 and 1.1, this was announced on our blog in May 2020.

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.

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

Because subscription accounts do not have hard limits, we do not include rate limiting information in the response for paid accounts. In all other respects the results are the same.

Some annotations are resource intensive, it isn't viable to have them on by default for everyone, instead they are only available to paying customers and need to be specifically enabled for the customer account.

If you are a subscription customer, yes. If not, no.

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.

If you are a subscription customer, yes. If not, no. Details here.

Not exactly. Subscription customers can specify a CORS header which will limit AJAX requests to a specific domain. Please see the details in our API documentation.

Sure, happy to discuss it if you're a large or enterprise subscription customer.

Please see our detailed guide to geocoding more quickly.

Yes, many, and we're always working on more. They're all open source, please contribute; we're looking forward to your pull requests.

If we don't yet have your programming language of choice, apologies. 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 our SDK guidelines.

Unfortunately, no.

The world is, as you've possibly experienced, a crazy and chaotic place. The great strength of a crowd-sourced project 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 is that, as hundreds of thousands of people around the world have been entering data, it can, at times, be a little chaotic.

Nevertheless, best practices have emerged and usually the output is well structured. But unfortunately not always.

It's exactly for this reason that we provide a formatted place name. We also provide the _type and _category keys in the components list. In this way you can know what type of thing we matched and what category it belongs to. Please see the API docs to learn more.

Sometimes users of the API are surprised when we return much larger bounding boxes than they expect. Good examples are searches for places like "The United States" or "France". The bounding box we return will include territories like Guam or French Guiana, and thus may be much larger than you expected. This comes up with many countries, but smaller administrative regions can also have exclaves (An example: the German city/state Hamburg includes the Nationalpark Hamburgisches Wattenmeer).

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.

If you put it out there on the internet, yes, it is certainly possible. Please see our detailed guide to protecting your API key(s). 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.

If you are a subscription customer you can turn on IP restriction and specify a CORS header.

We're looking at other ways to limit access, we know keys alone aren't perfect.

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

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

It depends. Please get in touch if you think there is a critical feature preventing you from using our service.

Yes. You may notice this if you do a forward query and then plug the resulting coordinates back in to the geocoding API 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.

In your account dashboard (in the "Usage" tab) we provide charts showing historic usage, you can also access the data used to make the charts as a CSV file via a URL that can be found in your account dashboard.

In your account dashboard you will see section labeled "Geocoding Spreadsheets" where you can upload a file which we will then geocode row by row.

Free trial users can geocode spreadsheets with up to 100 rows for free while testing.

Paying customers (whether on a one-time plan or a subscription) can upload files with more rows. Each row is treated as a geocoding API request.

The pricing of the various geocoding one-time plans and subscriptions can be seen on our pricing page.

We support the following file types: .csv, .ods, .tsv, .txt, .xls, .xlsx

Please note: we do NOT (yet) support uploading compressed files (.zip, .tgz, etc).

Regardless of the format you upload, we will output a CSV (comma separated value) file for you. You can then import that file into Excel, Google Sheets, or any other spreadsheet software.

Please see our detailed guide to formatting your spreadsheet for geocoding.

While we will do our best with whatever you upload, it helps us a lot if the first row of the file can be a header row, telling us what the columns mean.

For forward geocoding we recommend you put the entire address into a single column. Also the address should include the country. Many, many countries share languages and have places with the same name. If you make us guess, there is a chance we will get it wrong. Please see the formatting guide.

You can instead also have the parts of the address in separate columns, for example house number, road, city, postcode, state, country We will do the best we can to turn those columns into a single address.

For reverse geocoding (coordinates to address), you will need to provide a header row, as otherwise there is no way for us to know if a number is latitude or longitude. Coordinates should be in decimanl format, not degrees, minutes, seconds (DMS).

No, you can gladly provide city names, states, postal (zip) codes, etc

At the start of upload process you will configure which data you want us to append. By default it is just the coordinates (for forward geocoding) of the address (for reverse geocoding), but you can also select various other fields like city, state, type, etc. Not every result may have every field - if you ask us to geocode coordinates in the middle of the ocean, we aren't going to be able to set a city, for example. The data comes from the components portion of the API response, please take a second to read the relevant portion of the API documentation.

In the future we may add the ability to also append data from annotations, things like timezones, FIPS codes, NUTS codes, etc.

By default files are deleted after 90 days, though you can also delete any of your files manually whenever you like. We encourage you to download your files and then delete them from our service. Don't worry, we have plenty of our own data, we don't also need yours.

If you delete your account, all of your files are also deleted immediately.

Yes, forward geocoding (converting addresses in coordinates) is the first step to displaying locations as points on a map. That said, our service will not display the data on a map for you. We may offer that service in the future.

Please see the "Common Questions" section of our geosearch page.