OpenCage Geocoding API Documentation

Forward and Reverse Geocoding API

Overview

The OpenCage Geocoding API provides worldwide, reverse (latitude/longitude to text) and forward (text to latitude/longitude) geocoding based on open data via a REST API.

Quick Start

1. Sign up for your geocoding API key or test the API on our demo page.

2. Once you have an API key, start geocoding by requesting a URL:

  • Reverse geocoding

    https://api.opencagedata.com/geocode/v1/json?q=LAT+LNG&key=YOUR-API-KEY

  • Forward geocoding

    https://api.opencagedata.com/geocode/v1/json?q=URI-ENCODED-PLACENAME&key=YOUR-API-KEY

Or use one of the many SDKs (30+ programming languages).

3. See below for all the details of best practices, optional params, response format, caching, free trial rate limiting, and much more.

Wondering how we compare with others?

See our guide to comparing geocoding services for an overview of all the factors to consider.

Authentication

Using the OpenCage geocoding API requires a valid API key that you must pass with each HTTP request as the value of the key parameter (one of two required parameters). It is NOT necessary to set any headers for authentication.

Sign up for your geocoding API key

Request Format

A geocoding API request is in the following form:

https://api.opencagedata.com/geocode/version/format?parameters

Both the HTTP 1.1 and HTTP/2 protocols are supported. All requests should use the HTTP GET method. Requests that use other methods will recieve a response with status 405 - Method not allowed.

Both http and https schemes are supported. We strongly recommend https as requests made using http are not encrypted. https requests must use TLS 1.2 or higher. https requests that use an older (insecure) TLS will fail. If you are stuck with ancient software that does not support TLS 1.2 or higher you should use http, and find a way to upgrade as soon as possible.

The version component of the URL should be replaced with a version of the format v + version number. The current version is v1. Requests with an incorrect version number will receive a response with status 400 - not a valid version.

The format component of the URL should be replaced with one of the following:

json response returned as JSON
geojson response returned as GeoJSON
xml response returned as XML
google-v3-json the OpenCage geocoding API supports a subset of the Google v3 Geocoding API and returns a JSON response that is compatible with Google's. Please note, we provide this format as a convenience and do not actively maintain it. It is not widely used, and will likely be discontinued. We encourage you to use the json or xml format. Please see details of our Google compatibility .
API requests with any other format will recieve a response with status 400 - not a valid format.

Request Parameters

Required Parameters

key

a 30 character long, alphanumeric string.

Example usage: key=YOUR-API-KEY

You will find your API key in your account dashboard.

By default accounts are limited to one active key. Subscription customers can have multiple API keys.

Please see our guide to protecting your API key(s).

Note, your geocoding API key is used only for the geocoding API and is NOT used to authenticate for our geosearch/autosuggest service.

q

the query string to be geocoded: a latitude, longitude or a placename/address.

Example usage:

reverse geocoding: q=52.3877830+9.7334394
forward geocoding: q=Berlin,+Germany

The query should be URL encoded. Instead of, for example, non-ascii strings like München you should send us M%C3%BCnchen.

When reverse geocoding the query should be in latitude, longitude order in decimal format. Use periods as the decimal seperator, not commas.

There is no reason to send more than six or seven digits past the decimal as that is the precision of a centimeter - see Wikipedia about decimal degree precision. If impossible coordinates are supplied you will receive a response with status 400 invalid coordinates.

When forward geocoding there are many things you can do to help improve our chance of finding the correct answer and answering more quickly.

Please note:

  • the optional parameters especially bounds and countrycode.
  • our detailed guide to formatting your forward geocoding query.
  • we do NOT support fuzzy matching.
  • the query value must be at least two characters long. Queries that are too short will fail with status 400 missing or bad query.
  • queries that are too long will fail with status 400 query too long.
  • queries that contain obvious erroneous data will fail with status 400 missing or bad query.

Finally, please see our best practices.

Optional Parameters

abbrv

When set to 1 we attempt to abbreviate and shorten the formatted string we return.

Example usage: abbrv=1

Learn more about formatted placenames. Are we missing abbreviations in your language? If so please help us by contributing improvements. Thanks!

address_only

When set to 1 we include only the address (exluding POI names) in the formatted string we return.

Example usage: address_only=1

As an example, by default a reverse geocoding request for the coordinates 50.976004, 11.336753 returns a formatted value of Goethes Gartenhaus, Corona-Schröter-Weg 1, 99425 Weimar, Germany, but if address_only=1 is specified the value would be simply Corona-Schröter-Weg 1, 99425 Weimar, Germany. This can be particularly useful when there are many stores/restaurants/whatever at a single location (for example a multi-story building).

Learn more about formatted placenames.

add_request

When set to 1 the various request parameters are added to the response for ease of debugging.

Example usage: add_request=1

bounds

Used only for forward geocoding. This value will restrict the possible results to a defined bounding box.

Example usage: bounds=-0.563160,51.280430,0.278970,51.683979

The value of the bounds parameter should be specified as two coordinate points forming the south-west and north-east corners of a bounding box (min longitude, min latitude, max longitude, max latitude). Values that are not valid coordinates are ignored.

You may find our small, map-based tool to easily see bounds values to be useful.

countrycode

Used only for forward geocoding. Restricts results to the specified country/territory or countries.

Example usage: countrycode=de

The country code is a two letter code as defined by the ISO 3166-1 Alpha 2 standard. E.g. gb for the United Kingdom, fr for France, us for United States.

Non-two letter country codes are ignored.

You can specify multiple country codes by supplying a comma separated list. For example countrycode=ca,us would limit results to either the United States or Canada.

Please note, many territories have their own ISO 3116-1 codes, despite being part of another country. An example is Puerto Rico which has ISO code PR, despite being part of the United States, US. In the components portion of results we return both - see details below.

Many parts of the world have complex or even disputed political structures and/or share postal systems with another country, and thus may be treated as a single or multiple country by some of the geocoders we rely upon. It may make sense to specify multiple country codes.

As an example, when searching for locations on the island of Aruba - technically a constituent country of the Kingdom of the Netherlands - we will do better if you specify countrycode=aw,nl rather than just countrycode=aw.

As a convenience we have compiled a list of country codes for dependent territories .

jsonp

Wraps the returned JSON with a function name.

Example usage: jsonp=myfuncname

If you are calling our service via AJAX you may also find our documentation on CORS headers and/or our jQuery tutorial helpful.

language

An IETF format language code (such as es for Spanish or pt-BR for Brazilian Portuguese), or native in which case we will attempt to return the response in the local language(s).

Example usage: language=de

If no language is explicitly specified, we will then look for an HTTP Accept-Language header like those sent by a browser and use highest quality language specified (please see RFC 4647 for details). If the request did not specify a valid header, then en (English) will be assumed.

Please note, setting the language parameter does NOT mean results will only be returned in the specified language. Instead it means we will attempt to favour results in that language.

Please see our detailed comments on language below, particularly the caviats around specifying language=native.

limit

The maximum number of results we should return. Default is 10. Maximum allowable value is 100.

Example usage: limit=1

no_annotations

When set to 1 results will not contain annotations.

Example usage: no_annotations=1

The only exception is if the optional roadinfo parameter is set (see below).

no_dedupe

When set to 1 results will not be deduplicated.

Example usage: no_dedupe=1

no_record

When set to 1 the query contents are not logged.

Example usage: no_record=1

Please use this parameter if you have concerns about privacy, and want us to have no record of your query. Learn more about our approach to privacy.

pretty

When set to 1 results are 'pretty' printed for easier reading/debugging.

Example usage: pretty=1

proximity

Used only for forward geocoding. Provides the geocoder with a hint to bias results in favour of those closer to the specified location. Please note, this is just one of many factors in the internal scoring we use for ranking results.

Example usage: proximity=52.3877830,9.7334394

The value is a point with latitude, longitude coordinates in decimal format. Values that are not valid coordinates are ignored.

roadinfo

When set to 1 the behaviour of the geocoder is changed to attempt to match the nearest road (as opposed to address).

Example usage: roadinfo=1

If possible we also fill additional information in the roadinfo annotation. Please see details below.

Rate/Usage Limits

The OpenCage geocoding API uses rate limits to ensure that the service stays available to all users.

Free trial usage limits

Free trial accounts have a hard limit of 2,500 requests per day for testing purposes. Our day is based on the UTC timezone. Daily counts reset at midnight (24:00 UTC - see current UTC time).

Free trial accounts are limited to one request per second, and if you exceed that rate you may see a 429 - Too many requests response.

If you wish to use our geocoding API at higher volume, speed or on an ongoing basis, please become a customer. For the avoidance of any doubt: if you are regularly depending on our service, you are not testing, and should become a customer. See pricing.

Paying customers can use our service at higher volumes and much faster rate (requests per second) depending on pricing tier.

We have two different paid usage models: subscriptions (monthly and annual) and one-time plans. Please see our pricing page for the exact details of the different tiers available under each model.

Hard versus soft limits

Free trial and one-time plan customers face hard limits. Subscription customers do not.

Hitting the usage limits

  • If you send a request after you have reached your hard limit a response with status of 402 - Payment Required will be returned
  • Free trial accounts that continually request beyond the hard limit (if you ignore the 402 response) will eventually be blocked and see a 403 - Forbidden response. So please, don't do that. Thanks.
  • If you exceed the request per second rate you may see a 429 - Too many requests response.

Please see below for a full list of all possible response codes and various API keys you can use to generate a 402 or 403 response for testing.

Seeing your real-time API use

Real-time usage information for accounts with hard limits is returned by the API in both the rate element of the response body and HTTP response headers. Note: Responses to subscription customers do NOT contain the rate element of the response body or X-Ratelimit HTTP headers, because they do not face hard limits.

rate key HTTP Header meaning
limit X-RateLimit-Limit total number of API requests your account is limited to over given time period
(24 hours for free trials)
remaining X-RateLimit-Remaining number of API requests remaining until hard limit is reached
reset X-RateLimit-Reset Unix time at which count resets

Here is an example (in JSON format) of the information in the API response body for accounts with hard limits. 

"rate" : {
  "limit" : 2500,
  "remaining" : 2498,
  "reset" : 1605312000
},

Seeing your past API use

A graph of daily usage is shown in the "Geocoding API" tab of your account dashboard. There you will also find a link to a URL with a unique access token where you can download your daily usage as a csv file.

OpenCage account dashboard, geocoding API usage chart
Geocoding API usage chart in your account dashboard

Response Codes

The status element of the API response contains the following:

code a three digit code
message a brief, human-readable explanation of the response code

The following response codes are possible:

code meaning
check message in API response for specific details
200 OK (zero or more results will be returned)
400 Invalid request (bad request; a required parameter is missing; invalid coordinates; invalid version; invalid format)
401 Unable to authenticate - missing, invalid, or unknown API key
402 Valid request but quota exceeded (payment required)
403 Forbidden (API key disabled or IP address rejected)
404 Invalid API endpoint
405 Method not allowed (non-GET request)
408 Timeout; you can try again
410 Request too long
426 Upgrade required (unsupported TLS)
429 Too many requests (too quickly, rate limiting)
503 Internal server error

API keys for testing

For testing purposes you can use the following API keys:

key response
6d0e711d72d74daeb2b0bfd2a5cdfdba 200 - OK *
4372eff77b8343cebfc843eb4da4ddc4 402 - quota exceeded
2e10e5e828262eb243ec0b54681d699a 403 - disabled
6c79ee8e1ca44ad58ad1fc493ba9542f 403 - IP address rejected
d6d0f0065f4348a4bdfe4587ba02714b 429 - requesting too quickly
* the 200 - OK key will behave as if the q parameter of the request had been 51.952659,7.632473 regardless of what was actually specified.

Response Format

The API response is formatted according to format component of the request URL. The response can vary slightly depending on which, if any, of the optional request parameters are used, and whether or not you are a subscription customer.

All returned coordinates use WGS 84 (sometimes also known as EPSG:4326) as reference coordinate system.

Some developers prefer to use API inspection tools to examine the API response. We have tutorials for accessing the API via Postman or via Insomnia.

Here are example responses to reverse and forward geocoding requests with no optional parameters:

Reverse Geocoding Response Format

JSON format request for coordinates -22.6792, 14.5272.

https://api.opencagedata.com/geocode/v1/json?q=-22.6792%2C+14.5272&key=YOUR-API-KEY&pretty=1

The JSON response: 

{
   "documentation" : "https://opencagedata.com/api",
   "licenses" : [
      {
         "name" : "see attribution guide",
         "url" : "https://opencagedata.com/credits"
      }
   ],
   "rate" : {
      "limit" : 2500,
      "remaining" : 1559,
      "reset" : 1673654400
   },
   "results" : [
      {
         "annotations" : {
            "DMS" : {
               "lat" : "22\u00b0 40' 45.05736'' S",
               "lng" : "14\u00b0 31' 36.48576'' E"
            },
            "MGRS" : "33KVQ5139191916",
            "Maidenhead" : "JG77gh36fx",
            "Mercator" : {
               "x" : 1617116.157,
               "y" : -2576798.589
            },
            "OSM" : {
               "edit_url" : "https://www.openstreetmap.org/edit?node=4488973891#map=16/-22.67918/14.52680",
               "note_url" : "https://www.openstreetmap.org/note/new#map=16/-22.67918/14.52680&layers=N",
               "url" : "https://www.openstreetmap.org/?mlat=-22.67918&mlon=14.52680#map=16/-22.67918/14.52680"
            },
            "UN_M49" : {
               "regions" : {
                  "AFRICA" : "002",
                  "NA" : "516",
                  "SOUTHERN_AFRICA" : "018",
                  "SUB-SAHARAN_AFRICA" : "202",
                  "WORLD" : "001"
               },
               "statistical_groupings" : [
                  "LEDC"
               ]
            },
            "callingcode" : 264,
            "currency" : {
               "alternate_symbols" : [
                  "N$"
               ],
               "decimal_mark" : ".",
               "disambiguate_symbol" : "N$",
               "format" : "%n %u",
               "html_entity" : "$",
               "iso_code" : "NAD",
               "iso_numeric" : "516",
               "name" : "Namibian Dollar",
               "smallest_denomination" : 5,
               "subunit" : "Cent",
               "subunit_to_unit" : 100,
               "symbol" : "$",
               "symbol_first" : 0,
               "thousands_separator" : ","
            },
            "flag" : "\ud83c\uddf3\ud83c\udde6",
            "geohash" : "k7fqfx6h5jbq5tn8tnpn",
            "qibla" : 31.02,
            "roadinfo" : {
               "drive_on" : "left",
               "road" : "Woermann Street",
               "speed_in" : "km/h"
            },
            "sun" : {
               "rise" : {
                  "apparent" : 1673584200,
                  "astronomical" : 1673579100,
                  "civil" : 1673582700,
                  "nautical" : 1673580900
               },
               "set" : {
                  "apparent" : 1673632260,
                  "astronomical" : 1673637360,
                  "civil" : 1673633760,
                  "nautical" : 1673635500
               }
            },
            "timezone" : {
               "name" : "Africa/Windhoek",
               "now_in_dst" : 0,
               "offset_sec" : 7200,
               "offset_string" : "+0200",
               "short_name" : "CAT"
            },
            "what3words" : {
               "words" : "integrate.laughter.teller"
            }
         },
         "bounds" : {
            "northeast" : {
               "lat" : -22.6791326,
               "lng" : 14.5268516
            },
            "southwest" : {
               "lat" : -22.6792326,
               "lng" : 14.5267516
            }
         },
         "components" : {
            "ISO_3166-1_alpha-2" : "NA",
            "ISO_3166-1_alpha-3" : "NAM",
            "ISO_3166-2" : [
               "NA-ER"
            ],
            "_category" : "commerce",
            "_type" : "restaurant",
            "city" : "Swakopmund",
            "continent" : "Africa",
            "country" : "Namibia",
            "country_code" : "na",
            "postcode" : "22001",
            "restaurant" : "Beryl's Restaurant",
            "road" : "Woermann Street",
            "state" : "Erongo Region",
            "suburb" : "Central"
         },
         "confidence" : 9,
         "formatted" : "Beryl's Restaurant, Woermann Street, Swakopmund 22001, Namibia",
         "geometry" : {
            "lat" : -22.6791826,
            "lng" : 14.5268016
         }
      }
   ],
   "status" : {
      "code" : 200,
      "message" : "OK"
   },
   "stay_informed" : {
      "blog" : "https://blog.opencagedata.com",
      "mastodon" : "https://en.osm.town/@opencage",
      "twitter" : "https://twitter.com/OpenCage"
   },
   "thanks" : "For using an OpenCage API",
   "timestamp" : {
      "created_http" : "Fri, 13 Jan 2023 12:37:23 GMT",
      "created_unix" : 1673613443
   },
   "total_results" : 1
}

GeoJSON format request for coordinates -22.6792, 14.5272.

https://api.opencagedata.com/geocode/v1/geojson?q=-22.6792%2C+14.5272&key=YOUR-API-KEY&pretty=1

The GeoJSON response: 

{
   "documentation" : "https://opencagedata.com/api",
   "features" : [
      {
         "geometry" : {
            "coordinates" : [
               14.5268016,
               -22.6791826
            ],
            "type" : "Point"
         },
         "properties" : {
            "annotations" : {
               "DMS" : {
                  "lat" : "22\u00b0 40' 45.05736'' S",
                  "lng" : "14\u00b0 31' 36.48576'' E"
               },
               "MGRS" : "33KVQ5139191916",
               "Maidenhead" : "JG77gh36fx",
               "Mercator" : {
                  "x" : 1617116.157,
                  "y" : -2576798.589
               },
               "OSM" : {
                  "edit_url" : "https://www.openstreetmap.org/edit?node=4488973891#map=17/-22.67918/14.52680",
                  "note_url" : "https://www.openstreetmap.org/note/new#map=17/-22.67918/14.52680&layers=N",
                  "url" : "https://www.openstreetmap.org/?mlat=-22.67918&mlon=14.52680#map=17/-22.67918/14.52680"
               },
               "UN_M49" : {
                  "regions" : {
                     "AFRICA" : "002",
                     "NA" : "516",
                     "SOUTHERN_AFRICA" : "018",
                     "SUB-SAHARAN_AFRICA" : "202",
                     "WORLD" : "001"
                  },
                  "statistical_groupings" : [
                     "LEDC"
                  ]
               },
               "callingcode" : 264,
               "currency" : {
                  "alternate_symbols" : [
                     "N$"
                  ],
                  "decimal_mark" : ".",
                  "disambiguate_symbol" : "N$",
                  "format" : "%n %u",
                  "html_entity" : "$",
                  "iso_code" : "NAD",
                  "iso_numeric" : "516",
                  "name" : "Namibian Dollar",
                  "smallest_denomination" : 5,
                  "subunit" : "Cent",
                  "subunit_to_unit" : 100,
                  "symbol" : "$",
                  "symbol_first" : 0,
                  "thousands_separator" : ","
               },
               "flag" : "\ud83c\uddf3\ud83c\udde6",
               "geohash" : "k7fqfx6h5jbq5tn8tnpn",
               "qibla" : 31.02,
               "roadinfo" : {
                  "drive_on" : "left",
                  "road" : "Woermann Street",
                  "speed_in" : "km/h"
               },
               "sun" : {
                  "rise" : {
                     "apparent" : 1673584200,
                     "astronomical" : 1673579100,
                     "civil" : 1673582700,
                     "nautical" : 1673580900
                  },
                  "set" : {
                     "apparent" : 1673632260,
                     "astronomical" : 1673637360,
                     "civil" : 1673633760,
                     "nautical" : 1673635500
                  }
               },
               "timezone" : {
                  "name" : "Africa/Windhoek",
                  "now_in_dst" : 0,
                  "offset_sec" : 7200,
                  "offset_string" : "+0200",
                  "short_name" : "CAT"
               },
               "what3words" : {
                  "words" : "integrate.laughter.teller"
               }
            },
            "bounds" : {
               "northeast" : {
                  "lat" : -22.6791326,
                  "lng" : 14.5268516
               },
               "southwest" : {
                  "lat" : -22.6792326,
                  "lng" : 14.5267516
               }
            },
            "components" : {
               "ISO_3166-1_alpha-2" : "NA",
               "ISO_3166-1_alpha-3" : "NAM",
               "ISO_3166-2" : [
                  "NA-ER"
               ],
               "_category" : "commerce",
               "_type" : "restaurant",
               "city" : "Swakopmund",
               "continent" : "Africa",
               "country" : "Namibia",
               "country_code" : "na",
               "postcode" : "22001",
               "restaurant" : "Beryl's Restaurant",
               "road" : "Woermann Street",
               "state" : "Erongo Region",
               "suburb" : "Central"
            },
            "confidence" : 9,
            "formatted" : "Beryl's Restaurant, Woermann Street, Swakopmund 22001, Namibia"
         },
         "type" : "Feature"
      }
   ],
   "licenses" : [
      {
         "name" : "see attribution guide",
         "url" : "https://opencagedata.com/credits"
      }
   ],
   "rate" : {
      "limit" : 2500,
      "remaining" : 1557,
      "reset" : 1673654400
   },
   "status" : {
      "code" : 200,
      "message" : "OK"
   },
   "stay_informed" : {
      "blog" : "https://blog.opencagedata.com",
      "mastodon" : "https://en.osm.town/@opencage",
      "twitter" : "https://twitter.com/OpenCage"
   },
   "thanks" : "For using an OpenCage API",
   "timestamp" : {
      "created_http" : "Fri, 13 Jan 2023 12:37:24 GMT",
      "created_unix" : 1673613444
   },
   "total_results" : 1,
   "type" : "FeatureCollection"
}

XML format request for coordinates -22.6792, 14.5272.

https://api.opencagedata.com/geocode/v1/xml?q=-22.6792%2C+14.5272&key=YOUR-API-KEY&pretty=1

The XML response: 

<response>
  <documentation>https://opencagedata.com/api</documentation>
  <licenses>
    <license>
      <name>see attribution guide</name>
      <url>https://opencagedata.com/credits</url>
    </license>
  </licenses>
  <rate>
    <limit>2500</limit>
    <remaining>1558</remaining>
    <reset>1673654400</reset>
  </rate>
  <results>
    <result>
      <annotations>
        <DMS>
          <lat>22° 40' 45.05736'' S</lat>
          <lng>14° 31' 36.48576'' E</lng>
        </DMS>
        <MGRS>33KVQ5139191916</MGRS>
        <Maidenhead>JG77gh36fx</Maidenhead>
        <Mercator>
          <x>1617116.157</x>
          <y>-2576798.589</y>
        </Mercator>
        <OSM>
          <edit_url>https://www.openstreetmap.org/edit?node=4488973891#map=17/-22.67918/14.52680</edit_url>
          <note_url>https://www.openstreetmap.org/note/new#map=17/-22.67918/14.52680&amp;layers=N</note_url>
          <url>https://www.openstreetmap.org/?mlat=-22.67918&amp;mlon=14.52680#map=17/-22.67918/14.52680</url>
        </OSM>
        <UN_M49>
          <regions>
            <AFRICA>002</AFRICA>
            <NA>516</NA>
            <SOUTHERN_AFRICA>018</SOUTHERN_AFRICA>
            <SUB-SAHARAN_AFRICA>202</SUB-SAHARAN_AFRICA>
            <WORLD>001</WORLD>
          </regions>
          <statistical_groupings>LEDC</statistical_groupings>
        </UN_M49>
        <callingcode>264</callingcode>
        <currency>
          <alternate_symbols>N$</alternate_symbols>
          <decimal_mark>.</decimal_mark>
          <disambiguate_symbol>N$</disambiguate_symbol>
          <format>%n %u</format>
          <html_entity>$</html_entity>
          <iso_code>NAD</iso_code>
          <iso_numeric>516</iso_numeric>
          <name>Namibian Dollar</name>
          <smallest_denomination>5</smallest_denomination>
          <subunit>Cent</subunit>
          <subunit_to_unit>100</subunit_to_unit>
          <symbol>$</symbol>
          <symbol_first>0</symbol_first>
          <thousands_separator>,</thousands_separator>
        </currency>
        <flag>🇳🇦</flag>
        <geohash>k7fqfx6h5jbq5tn8tnpn</geohash>
        <qibla>31.02</qibla>
        <roadinfo>
          <drive_on>left</drive_on>
          <road>Woermann Street</road>
          <speed_in>km/h</speed_in>
        </roadinfo>
        <sun>
          <rise>
            <apparent>1673584200</apparent>
            <astronomical>1673579100</astronomical>
            <civil>1673582700</civil>
            <nautical>1673580900</nautical>
          </rise>
          <set>
            <apparent>1673632260</apparent>
            <astronomical>1673637360</astronomical>
            <civil>1673633760</civil>
            <nautical>1673635500</nautical>
          </set>
        </sun>
        <timezone>
          <name>Africa/Windhoek</name>
          <now_in_dst>0</now_in_dst>
          <offset_sec>7200</offset_sec>
          <offset_string>+0200</offset_string>
          <short_name>CAT</short_name>
        </timezone>
        <what3words>
          <words>integrate.laughter.teller</words>
        </what3words>
      </annotations>
      <bounds>
        <northeast>
          <lat>-22.6791326</lat>
          <lng>14.5268516</lng>
        </northeast>
        <southwest>
          <lat>-22.6792326</lat>
          <lng>14.5267516</lng>
        </southwest>
      </bounds>
      <components>
        <ISO_3166-1_alpha-2>NA</ISO_3166-1_alpha-2>
        <ISO_3166-1_alpha-3>NAM</ISO_3166-1_alpha-3>
        <ISO_3166-2>NA-ER</ISO_3166-2>
        <_category>commerce</_category>
        <_type>restaurant</_type>
        <city>Swakopmund</city>
        <continent>Africa</continent>
        <country>Namibia</country>
        <country_code>na</country_code>
        <postcode>22001</postcode>
        <restaurant>Beryl's Restaurant</restaurant>
        <road>Woermann Street</road>
        <state>Erongo Region</state>
        <suburb>Central</suburb>
      </components>
      <confidence>9</confidence>
      <formatted>Beryl's Restaurant, Woermann Street, Swakopmund 22001, Namibia</formatted>
      <geometry>
        <lat>-22.6791826</lat>
        <lng>14.5268016</lng>
      </geometry>
    </result>
  </results>
  <status>
    <code>200</code>
    <message>OK</message>
  </status>
  <stay_informed>
    <blog>https://blog.opencagedata.com</blog>
    <mastodon>https://en.osm.town/@opencage</mastodon>
    <twitter>https://twitter.com/OpenCage</twitter>
  </stay_informed>
  <thanks>For using an OpenCage API</thanks>
  <timestamp>
    <created_http>Fri, 13 Jan 2023 12:37:24 GMT</created_http>
    <created_unix>1673613444</created_unix>
  </timestamp>
  <total_results>1</total_results>
</response>

Forward Geocoding Response Format

JSON format request for query Rua Cafelândia, Carapicuíba, Brasil.

https://api.opencagedata.com/geocode/v1/json?q=Rua+Cafel%C3%A2ndia%2C+Carapicu%C3%ADba%2C+Brasil&key=YOUR-API-KEY&pretty=1

The JSON response: 

{
   "documentation" : "https://opencagedata.com/api",
   "licenses" : [
      {
         "name" : "see attribution guide",
         "url" : "https://opencagedata.com/credits"
      }
   ],
   "rate" : {
      "limit" : 2500,
      "remaining" : 1563,
      "reset" : 1673654400
   },
   "results" : [
      {
         "annotations" : {
            "DMS" : {
               "lat" : "23\u00b0 32' 13.54632'' S",
               "lng" : "46\u00b0 50' 9.50460'' W"
            },
            "MGRS" : "23KLP1257795822",
            "Maidenhead" : "GG66nl91qc",
            "Mercator" : {
               "x" : -5213756.721,
               "y" : -2680044.786
            },
            "OSM" : {
               "edit_url" : "https://www.openstreetmap.org/edit?way=185327107#map=17/-23.53710/-46.83597",
               "note_url" : "https://www.openstreetmap.org/note/new#map=17/-23.53710/-46.83597&layers=N",
               "url" : "https://www.openstreetmap.org/?mlat=-23.53710&mlon=-46.83597#map=17/-23.53710/-46.83597"
            },
            "UN_M49" : {
               "regions" : {
                  "AMERICAS" : "019",
                  "BR" : "076",
                  "LATIN_AMERICA" : "419",
                  "SOUTH_AMERICA" : "005",
                  "WORLD" : "001"
               },
               "statistical_groupings" : [
                  "LEDC"
               ]
            },
            "callingcode" : 55,
            "currency" : {
               "decimal_mark" : ",",
               "html_entity" : "R$",
               "iso_code" : "BRL",
               "iso_numeric" : "986",
               "name" : "Brazilian Real",
               "smallest_denomination" : 5,
               "subunit" : "Centavo",
               "subunit_to_unit" : 100,
               "symbol" : "R$",
               "symbol_first" : 1,
               "thousands_separator" : "."
            },
            "flag" : "\ud83c\udde7\ud83c\uddf7",
            "geohash" : "6gydn5pn6xqbjyhsscm7",
            "qibla" : 69.01,
            "roadinfo" : {
               "drive_on" : "right",
               "road" : "Rua Cafel\u00e2ndia",
               "road_type" : "residential",
               "speed_in" : "km/h"
            },
            "sun" : {
               "rise" : {
                  "apparent" : 1673598840,
                  "astronomical" : 1673593680,
                  "civil" : 1673597340,
                  "nautical" : 1673595540
               },
               "set" : {
                  "apparent" : 1673647080,
                  "astronomical" : 1673652180,
                  "civil" : 1673648580,
                  "nautical" : 1673650380
               }
            },
            "timezone" : {
               "name" : "America/Sao_Paulo",
               "now_in_dst" : 0,
               "offset_sec" : -10800,
               "offset_string" : "-0300",
               "short_name" : "BRT"
            },
            "what3words" : {
               "words" : "reunion.risk.brothers"
            }
         },
         "bounds" : {
            "northeast" : {
               "lat" : -23.5370411,
               "lng" : -46.835665
            },
            "southwest" : {
               "lat" : -23.5373596,
               "lng" : -46.8374493
            }
         },
         "components" : {
            "ISO_3166-1_alpha-2" : "BR",
            "ISO_3166-1_alpha-3" : "BRA",
            "ISO_3166-2" : [
               "BR-SP"
            ],
            "_category" : "road",
            "_type" : "road",
            "city" : "Carapicu\u00edba",
            "city_district" : "Carapicu\u00edba",
            "continent" : "South America",
            "country" : "Brazil",
            "country_code" : "br",
            "county" : "Regi\u00e3o Metropolitana de S\u00e3o Paulo",
            "municipality" : "Regi\u00e3o Imediata de S\u00e3o Paulo",
            "postcode" : "06321-665",
            "region" : "Southeast Region",
            "road" : "Rua Cafel\u00e2ndia",
            "road_type" : "residential",
            "state" : "S\u00e3o Paulo",
            "state_code" : "SP",
            "state_district" : "Regi\u00e3o Geogr\u00e1fica Intermedi\u00e1ria de S\u00e3o Paulo",
            "suburb" : "Parque Jos\u00e9 Alexandre"
         },
         "confidence" : 9,
         "formatted" : "Rua Cafel\u00e2ndia, Parque Jos\u00e9 Alexandre, Carapicu\u00edba - SP, 06321-665, Brazil",
         "geometry" : {
            "lat" : -23.5370962,
            "lng" : -46.8359735
         }
      }
   ],
   "status" : {
      "code" : 200,
      "message" : "OK"
   },
   "stay_informed" : {
      "blog" : "https://blog.opencagedata.com",
      "mastodon" : "https://en.osm.town/@opencage",
      "twitter" : "https://twitter.com/OpenCage"
   },
   "thanks" : "For using an OpenCage API",
   "timestamp" : {
      "created_http" : "Fri, 13 Jan 2023 12:37:21 GMT",
      "created_unix" : 1673613441
   },
   "total_results" : 1
}

GeoJSON format request for query Rua Cafelândia, Carapicuíba, Brasil.

https://api.opencagedata.com/geocode/v1/geojson?q=Rua+Cafel%C3%A2ndia%2C+Carapicu%C3%ADba%2C+Brasil&key=YOUR-API-KEY&pretty=1

The GeoJSON response: 

{
   "documentation" : "https://opencagedata.com/api",
   "features" : [
      {
         "geometry" : {
            "coordinates" : [
               -46.8359735,
               -23.5370962
            ],
            "type" : "Point"
         },
         "properties" : {
            "annotations" : {
               "DMS" : {
                  "lat" : "23\u00b0 32' 13.54632'' S",
                  "lng" : "46\u00b0 50' 9.50460'' W"
               },
               "MGRS" : "23KLP1257795822",
               "Maidenhead" : "GG66nl91qc",
               "Mercator" : {
                  "x" : -5213756.721,
                  "y" : -2680044.786
               },
               "OSM" : {
                  "edit_url" : "https://www.openstreetmap.org/edit?way=185327107#map=17/-23.53710/-46.83597",
                  "note_url" : "https://www.openstreetmap.org/note/new#map=17/-23.53710/-46.83597&layers=N",
                  "url" : "https://www.openstreetmap.org/?mlat=-23.53710&mlon=-46.83597#map=17/-23.53710/-46.83597"
               },
               "UN_M49" : {
                  "regions" : {
                     "AMERICAS" : "019",
                     "BR" : "076",
                     "LATIN_AMERICA" : "419",
                     "SOUTH_AMERICA" : "005",
                     "WORLD" : "001"
                  },
                  "statistical_groupings" : [
                     "LEDC"
                  ]
               },
               "callingcode" : 55,
               "currency" : {
                  "decimal_mark" : ",",
                  "html_entity" : "R$",
                  "iso_code" : "BRL",
                  "iso_numeric" : "986",
                  "name" : "Brazilian Real",
                  "smallest_denomination" : 5,
                  "subunit" : "Centavo",
                  "subunit_to_unit" : 100,
                  "symbol" : "R$",
                  "symbol_first" : 1,
                  "thousands_separator" : "."
               },
               "flag" : "\ud83c\udde7\ud83c\uddf7",
               "geohash" : "6gydn5pn6xqbjyhsscm7",
               "qibla" : 69.01,
               "roadinfo" : {
                  "drive_on" : "right",
                  "road" : "Rua Cafel\u00e2ndia",
                  "road_type" : "residential",
                  "speed_in" : "km/h"
               },
               "sun" : {
                  "rise" : {
                     "apparent" : 1673598840,
                     "astronomical" : 1673593680,
                     "civil" : 1673597340,
                     "nautical" : 1673595540
                  },
                  "set" : {
                     "apparent" : 1673647080,
                     "astronomical" : 1673652180,
                     "civil" : 1673648580,
                     "nautical" : 1673650380
                  }
               },
               "timezone" : {
                  "name" : "America/Sao_Paulo",
                  "now_in_dst" : 0,
                  "offset_sec" : -10800,
                  "offset_string" : "-0300",
                  "short_name" : "BRT"
               },
               "what3words" : {
                  "words" : "reunion.risk.brothers"
               }
            },
            "bounds" : {
               "northeast" : {
                  "lat" : -23.5370411,
                  "lng" : -46.835665
               },
               "southwest" : {
                  "lat" : -23.5373596,
                  "lng" : -46.8374493
               }
            },
            "components" : {
               "ISO_3166-1_alpha-2" : "BR",
               "ISO_3166-1_alpha-3" : "BRA",
               "ISO_3166-2" : [
                  "BR-SP"
               ],
               "_category" : "road",
               "_type" : "road",
               "city" : "Carapicu\u00edba",
               "city_district" : "Carapicu\u00edba",
               "continent" : "South America",
               "country" : "Brazil",
               "country_code" : "br",
               "county" : "Regi\u00e3o Metropolitana de S\u00e3o Paulo",
               "municipality" : "Regi\u00e3o Imediata de S\u00e3o Paulo",
               "postcode" : "06321-665",
               "region" : "Southeast Region",
               "road" : "Rua Cafel\u00e2ndia",
               "road_type" : "residential",
               "state" : "S\u00e3o Paulo",
               "state_code" : "SP",
               "state_district" : "Regi\u00e3o Geogr\u00e1fica Intermedi\u00e1ria de S\u00e3o Paulo",
               "suburb" : "Parque Jos\u00e9 Alexandre"
            },
            "confidence" : 9,
            "formatted" : "Rua Cafel\u00e2ndia, Parque Jos\u00e9 Alexandre, Carapicu\u00edba - SP, 06321-665, Brazil"
         },
         "type" : "Feature"
      }
   ],
   "licenses" : [
      {
         "name" : "see attribution guide",
         "url" : "https://opencagedata.com/credits"
      }
   ],
   "rate" : {
      "limit" : 2500,
      "remaining" : 1560,
      "reset" : 1673654400
   },
   "status" : {
      "code" : 200,
      "message" : "OK"
   },
   "stay_informed" : {
      "blog" : "https://blog.opencagedata.com",
      "mastodon" : "https://en.osm.town/@opencage",
      "twitter" : "https://twitter.com/OpenCage"
   },
   "thanks" : "For using an OpenCage API",
   "timestamp" : {
      "created_http" : "Fri, 13 Jan 2023 12:37:23 GMT",
      "created_unix" : 1673613443
   },
   "total_results" : 1,
   "type" : "FeatureCollection"
}

XML format request for query Rua Cafelândia, Carapicuíba, Brasil.

https://api.opencagedata.com/geocode/v1/xml?q=Rua+Cafel%C3%A2ndia%2C+Carapicu%C3%ADba%2C+Brasil&key=YOUR-API-KEY&pretty=1

The XML response: 

<response>
  <documentation>https://opencagedata.com/api</documentation>
  <licenses>
    <license>
      <name>see attribution guide</name>
      <url>https://opencagedata.com/credits</url>
    </license>
  </licenses>
  <rate>
    <limit>2500</limit>
    <remaining>1562</remaining>
    <reset>1673654400</reset>
  </rate>
  <results>
    <result>
      <annotations>
        <DMS>
          <lat>23° 32' 13.54632'' S</lat>
          <lng>46° 50' 9.50460'' W</lng>
        </DMS>
        <MGRS>23KLP1257795822</MGRS>
        <Maidenhead>GG66nl91qc</Maidenhead>
        <Mercator>
          <x>-5213756.721</x>
          <y>-2680044.786</y>
        </Mercator>
        <OSM>
          <edit_url>https://www.openstreetmap.org/edit?way=185327107#map=17/-23.53710/-46.83597</edit_url>
          <note_url>https://www.openstreetmap.org/note/new#map=17/-23.53710/-46.83597&amp;layers=N</note_url>
          <url>https://www.openstreetmap.org/?mlat=-23.53710&amp;mlon=-46.83597#map=17/-23.53710/-46.83597</url>
        </OSM>
        <UN_M49>
          <regions>
            <AMERICAS>019</AMERICAS>
            <BR>076</BR>
            <LATIN_AMERICA>419</LATIN_AMERICA>
            <SOUTH_AMERICA>005</SOUTH_AMERICA>
            <WORLD>001</WORLD>
          </regions>
          <statistical_groupings>LEDC</statistical_groupings>
        </UN_M49>
        <callingcode>55</callingcode>
        <currency>
          <decimal_mark>,</decimal_mark>
          <html_entity>R$</html_entity>
          <iso_code>BRL</iso_code>
          <iso_numeric>986</iso_numeric>
          <name>Brazilian Real</name>
          <smallest_denomination>5</smallest_denomination>
          <subunit>Centavo</subunit>
          <subunit_to_unit>100</subunit_to_unit>
          <symbol>R$</symbol>
          <symbol_first>1</symbol_first>
          <thousands_separator>.</thousands_separator>
        </currency>
        <flag>🇧🇷</flag>
        <geohash>6gydn5pn6xqbjyhsscm7</geohash>
        <qibla>69.01</qibla>
        <roadinfo>
          <drive_on>right</drive_on>
          <road>Rua Cafelândia</road>
          <road_type>residential</road_type>
          <speed_in>km/h</speed_in>
        </roadinfo>
        <sun>
          <rise>
            <apparent>1673598840</apparent>
            <astronomical>1673593680</astronomical>
            <civil>1673597340</civil>
            <nautical>1673595540</nautical>
          </rise>
          <set>
            <apparent>1673647080</apparent>
            <astronomical>1673652180</astronomical>
            <civil>1673648580</civil>
            <nautical>1673650380</nautical>
          </set>
        </sun>
        <timezone>
          <name>America/Sao_Paulo</name>
          <now_in_dst>0</now_in_dst>
          <offset_sec>-10800</offset_sec>
          <offset_string>-0300</offset_string>
          <short_name>BRT</short_name>
        </timezone>
        <what3words>
          <words>reunion.risk.brothers</words>
        </what3words>
      </annotations>
      <bounds>
        <northeast>
          <lat>-23.5370411</lat>
          <lng>-46.835665</lng>
        </northeast>
        <southwest>
          <lat>-23.5373596</lat>
          <lng>-46.8374493</lng>
        </southwest>
      </bounds>
      <components>
        <ISO_3166-1_alpha-2>BR</ISO_3166-1_alpha-2>
        <ISO_3166-1_alpha-3>BRA</ISO_3166-1_alpha-3>
        <ISO_3166-2>BR-SP</ISO_3166-2>
        <_category>road</_category>
        <_type>road</_type>
        <city>Carapicuíba</city>
        <city_district>Carapicuíba</city_district>
        <continent>South America</continent>
        <country>Brazil</country>
        <country_code>br</country_code>
        <county>Região Metropolitana de São Paulo</county>
        <municipality>Região Imediata de São Paulo</municipality>
        <postcode>06321-665</postcode>
        <region>Southeast Region</region>
        <road>Rua Cafelândia</road>
        <road_type>residential</road_type>
        <state>São Paulo</state>
        <state_code>SP</state_code>
        <state_district>Região Geográfica Intermediária de São Paulo</state_district>
        <suburb>Parque José Alexandre</suburb>
      </components>
      <confidence>9</confidence>
      <formatted>Rua Cafelândia, Parque José Alexandre, Carapicuíba - SP, 06321-665, Brazil</formatted>
      <geometry>
        <lat>-23.5370962</lat>
        <lng>-46.8359735</lng>
      </geometry>
    </result>
  </results>
  <status>
    <code>200</code>
    <message>OK</message>
  </status>
  <stay_informed>
    <blog>https://blog.opencagedata.com</blog>
    <mastodon>https://en.osm.town/@opencage</mastodon>
    <twitter>https://twitter.com/OpenCage</twitter>
  </stay_informed>
  <thanks>For using an OpenCage API</thanks>
  <timestamp>
    <created_http>Fri, 13 Jan 2023 12:37:21 GMT</created_http>
    <created_unix>1673613441</created_unix>
  </timestamp>
  <total_results>1</total_results>
</response>

Ranking of Results

We may return multiple results for a forward geocoding query. Results are returned in order of most relevant to least. Results are NOT ordered by confidence score (see definition of confidence score).

Reverse geocoding requests return at most one result.

Geocoding Confidence

The OpenCage geocoding API will always attempt to find a match for as many parts of a query as it can, but this isn't always possible. Where a partial match is made, for example a street name can be matched but not the specific house number, the we will still return a result.

The precision of a match is returned in the confidence field. Please note, confidence is NOT used for ranking of the results. It does not tell you which result is more "correct", nor what type of thing the result is - for that please check the components portion of the result.

The confidence score is an integer value between 0 and 10 , where 0 reflects inability to determine a confidence (due to lack of a bounding box), 1 indicates low precision, and 10 indicates high precision.

Confidence is calculated by measuring the distance between the southwest and northeast corners of each result's bounding box. Then an adjustment may be made to reflect the ambiguity of the underlying geocoder. Confidence is not the way to determine the type of place that was matched, for that please use the _type field of the components portion of the response.

The best way to think of our confidence score is as a measure of how confident we are that centre point coordinates returned for the result precisely reflect the result. For example, if you search for Berlin, Germany we know exactly where that is, but it has a confidence of only 4, as Berlin is a large city ( and Bundesland, but that's another story). The coordinates we return are in the centre of the bounding box, but it would be valid to consider anywhere in that box to be "Berlin", hence the relatively low confidence score.

confidence meaning / distance (in km)
10 < 0.25
9 < 0.5 0
8 < 1 .00
7 < 5 .00
6 < 7.5 0
5 < 10 .00
4 < 15 .00
3 < 20 .00
2 < 25 .00
1 > 25 .00
0 unable to determine a bounding box,
thus unable to determine a confidence

Ambiguous Results

When forward geocoding we may find multiple valid matches for a query. Many places have the same or similar names. In this case we return multiple results ranked by relevance. See our comments on how results are ranked.

Please see our detailed guide to understanding geocoding accuracy which outlines some strategies to determine whether a result from an ambiguous query is sufficiently correct to warrant using or not.

Note: Reverse geocoding requests return at most one result.

No Results

In cases where the geocoder cannot find any match for a request, we will return a successful status (a response code of 200) but the number of results in the response will be zero. You can test this situation by sending a request with the query NOWHERE-INTERESTING which will return a valid response with 0 results.

Formatted Placename and Components

Background

Across the world there are many different ways to format addresses and place names.

For each result we supply a formatted string which contains a well formatted version of the place name.

  • We attempt to display the name of the location in the local format.
  • The formatted string is created from the various terms in the components. This is the raw data we have to work with.
  • There are several optional parameters you can specify to influence the content of the formatted string:
    • We will attempt to shorten or abbreviate the string if abbrv is specified. See details.
    • We will attempt to exclude POI names from the formatted string if address_only is specified. See details.
    • You can specify your prefered output language by using the optional language parameter. See details.
  • For more background on the need for, and challenge of, good formatting please read our guide to address formatting.
_type and _category

We are often asked if there is a definitive list of all possible components keys. Unfortunately not - read why not.

  • For convenience we add the key _type with the value set to what we believe the matched location to be.
  • In the rare case where, for whatever reason, we can't determine a _type we set the value unknown.
  • Common possible values of _type include building, road, hamlet, village, neighbourhood, city, county, postcode, partial_postcode, terminated_postcode, postal_city, state_district, state, region, island, body_of_water, country, continent, fictitious, unknown.
  • Just because a result has a certain _type does NOT mean there is a key of that type in the components list. Various types get mapped together. As an example town gets mapped to _type : city. See . the list of mappings
  • We set a _category value, based on mapping the value of _type. See the list of possible values.
road and road_type

If the result is a road - ie if _type has value road - then if possible we also return a road_type key with values like those generally used in OpenStreetMap. If the road does not have a name we set the name unnamed road. If you are interested in road information, please read details on getting more road / driving information.

ISO codes / country_code

When possible we set the components keys country_code, ISO_3166-1_alpha-2, ISO_3166-1_alpha-3, and ISO_3166-2.

  • country_code is a lower-case two-letter code, for example de for Germany, and mx for Mexico.
  • For historical reasons many territories have their own ISO 3116-1 codes, despite being part of another country, and for this reason the value of country_code can differ from the value of ISO_3166-1_alpha-2. As an example Puerto Rico (part of the United States) has an ISO_3166-1_alpha-2 value of PR, and a country_code value of us.
  • The value for the key ISO_3166-2 is a list as some countries (for example France, Spain, and the United Kingdom) have multiple ISO 3166-2 values for a given location. As an example the coordinates 51.52445, -0.09975 have an ISO_3166-2 value of [ GB-ENG, GB-ISL ]. The codes are ordered from least to most specific.
  • For more background on ISO codes please read our guide to determining the ISO codes for a location.
continent

Possible values for the components key continent are Africa, Antarctica, Asia, Europe, Oceania, North America, and South America.

Annotations

By defaults each result contains an annotations section which supplies additional information about the result location. We believe this is one of the easiest ways to make life simpler for geo-developers, which is of course the whole point of our service.

Annotations can be turned off by setting the optional no_annotations parameter (with the exception of roadinfo, please see below for details), and we recommend you do so if you don't need them as it means we can respond to your query a tiny bit faster.

Please note:
  • The annotations reflect information derived based on the coordinates of the result.
    These may differ from the coordinates of the request.
  • 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. These annotations are marked below.
  • Some annotations, for example currency, depend on the coordinates being in a country.
    These annotations will not be supplied for results that do not lie inside the boundaries of any country, for example in the middle of an ocean.
  • The information in the annotations may come from different sources of variable coverage. We do the best we can, but please don't assume we will always be able to provide the same level of information everywhere.

We provide the following annotations:
callingcode The international telephone calling code for the country of the result.
Example: 49
currency Information about the local currency
Example: 
"currency": {
  "alternate_symbols": [
  ],
  "decimal_mark": ",",
  "html_entity": "€",
  "iso_code": "EUR",
  "iso_numeric": "978",
  "name": "Euro",
  "smallest_denomination": 1,
  "subunit": "Cent",
  "subunit_to_unit": 100,
  "symbol": "€",
  "symbol_first": 0,
  "thousands_separator": "."
}
DMS Contains the latitude and longitude of the center point of the result in degree minute decimal second format.
Example: { "lat": "52° 23' 16.01880'' N", "lng": "9° 44' 0.38184'' E" }
FIPS Contains the US Federal Information Processing Standards (FIPS) code for the state (two digit) and county (five digit) of the center point of the result, if we can determine it.
Example: { "county": "08101", "state": "08" }

Note:
  • Only for locations in the United States and associated territories.
  • The values are strings - not numbers - and can have leading zeros.
flag Emoji flag of the country of the result.
Example: 🇩🇪
geohash Contains a geohash for the center point of the result.
Example: u1qfj2zsvwd6ntczum3r
H3
Note: this annotation is only available to paying customers and by request.

Contains an H3 reference for the center point of the result.
Example: 861f11587ffffff

H3 is an open source hexagonal hierarchical geospatial indexing system originally invented at Uber. Read more about H3.
ITM Contains the Irish Transverse Mercator easting and northing of the center point of the result.
Example: { "easting": "465792.658", "northing": "750564.188" }

This annotation is applied only for locations in Ireland. Learn more about ITM.
Maidenhead contains a Maidenhead location reference for the center point of the result.
Example: JO42uj83ab
Mercator contains the Mercator projection (EPSG:41001, sometimes also referred to as "Simple Mercator") x and y unit meter values of the center point of the result.
Example: { "x": 1083521.518, "y": 6836676.75 }

Note: use of Mercator projection on latitudes above/below +70/-70 degrees is strongly discouraged, due to the gross distortions of the projection.
MGRS The Military Grid Reference System code for the center point of the result. WGS84 datum.
Example: 32UND4991404423
NUTS contains the relevant European Union Nomenclature of Territorial Units for Statistics (NUTS) codes for the location.

Note:
  • This annotation is applied only for locations within EU member states, we do not (yet) support EU candidate countries, potential candidates, EFTA countries, or former EU countries. We may add these in the future.
  • We do not support Local Administrative Units (LAUs), the level below NUTS 3. We may add these in the future.
  • Our codes are based on the 2016 defintions, which became effective from 1 Jan 2018.
  • We use maritime borders, not land borders.
    • Example: 
    "NUTS": {
  "NUTS0" : {
    "code" : "ES"
  },
  "NUTS1" : {
    "code" : "ES5"
  },
  "NUTS2" : {
    "code" : "ES51"
  },
  "NUTS3" : {
    "code" : "ES511"
  }
},

    Learn more about NUTS classifications on the official Eurostat site.
OSM Contains:
url URL for viewing the location on openstreetmap.org
note_url URL for adding a "note" about the location on openstreetmap.org

May also contain:

edit_url URL for editing the result on openstreetmap.org.

Note: you may need to zoom in or out to edit and in doing so focus may shift to a different element.
Example: 
"OSM": {
  "edit_url": "https://www.openstreetmap.org/edit?node=9041448608#map=16/52.38778/9.73344",
  "note_url": "https://www.openstreetmap.org/note/new#map=16/52.38778/9.73344&layers=N",
  "url": "https://www.openstreetmap.org/?mlat=52.38778&mlon=9.73344#map=16/52.38778/9.73344"
}

Our tutorial on how to add an address to OpenStreetMap may be helpful.
qibla Decimal degrees clockwise from true north to turn to point to the Kaaba (21.4225, 39.8262).
Example: 131.65

Calculated using the great circle method. More background on Qibla.
roadinfo Contains information relevant to driving in this region, potentially also about the specific road of the result

Information relevant to driving in the country/region:
drive_on possible values are left or right
speed_in possible values are km/h (kilometers per hour) or mph (miles per hour)

Possible information relevant to the road of the specific result
road name of the road
road_type with values like those generally used in OpenStreetMap
road_reference road identifier, example: A 38, AP-7, 3356
road_reference_intl international road identifier, example: E 15

If the optional roadinfo parameter was specified we will also attempt to set the following values about the road:
lanes number of lanes
maxspeed (speed limit). An integer value like 30 or none if there is no speed limit. Please bear in mind this is crowd-sourced data and not official governmental data. See note below.
oneway value of yes or no
toll value of yes if we know this is a toll road, otherwise this key is not set
surface physical surface of road, values like those generally in OpenStreetMap
width in meters, for example: 7.5

If you are using this information it is important that you read and understand the various caveats about this road/driving information.
Example (without roadinfo set) 
"roadinfo": {
  "drive_on": "right",
  "road": "A 38",
  "road_reference": "A 38",
  "road_type": "motorway",
  "speed_in": "km/h"
},
Example (with roadinfo set) 
"roadinfo" : {
  "drive_on" : "right",
  "lanes" : 2,
  "maxspeed" : "none",
  "oneway" : "yes",
  "road" : "A 38",
  "road_reference" : "A 38",
  "road_type" : "motorway",
  "speed_in" : "km/h",
  "surface" : "concrete",
  "width" : "7.5"
},
sun Contains two keys: rise and set, each of which in turn contains four keys:
apparent what is typically reported as sunrise/set
astronomical sky is completely dark/light
civil a person can read / no longer read
nautical navigation using a sea horizon possible/no longer possible

with Unix timestamps as values corresponding to the four different types of sunrise/set.
Example: 
"sun": {
  "rise": {
    "apparent": 1667802480,
    "astronomical": 1667795520,
    "civil": 1667800320,
    "nautical": 1667797860
  },
  "set": {
    "apparent": 1667835600,
    "astronomical": 1667842620,
    "civil": 1667837820,
    "nautical": 1667840280
  }
}
A value of 0 means the sun never rises/sets on that day (equivalent to 00:00-23:59), e.g. during midsummer.
timezone Information about the time zone of the location.

Consists of the following keys name, now_in_dst, offset_sec, offset_string, short_name.
Example: 
"timezone" : {
  "name": "Europe/Berlin",
  "now_in_dst": 0,
  "offset_sec": 3600,
  "offset_string": "+0100",
  "short_name": "CET"
},

When the result is in a country the value of name will be of the form Continent/City, the format used by tz database on *nix systems, for example Europe/Lisbon. When the coordinates are not in a country (for example in an ocean) the format will be an offset to/from GMT, for example GMT+2.

Learn more about timezones and how they are typically represented on *nix based systems over on Wikipedia.
UN_M49

Contains the relevant United Nations M49 codes for the location.

Consists of two keys: regions and statistical_groupings.

Example (for a location in Haiti) 
"UN_M49": {
  "regions": {
    "AMERICAS": "019",
    "CARIBBEAN": "029",
    "HT": "332",
    "LATIN_AMERICA": "419",
    "WORLD": "001"
  },
  "statistical_groupings": [
    "LDC",
    "LEDC",
    "SIDS"
  ]
},

Learn more about the UN M49 standard on Wikipedia.
what3words Contains a key words whose value is a 3 words address (3wa).
Example: { "words": "monopoly.tables.cats" }

By default the words returned are in English, but if the query contained the optional language parameter specifying one of the following languages:

af,am,ar,bg,bn,cs,cy,da,de,el
en,es,fa,fi,fr,gu,he,hi,hu,id
it,ja,kn,ko,ml,mn,mr,ms,ne,nl
no,or,pa,pl,pt,ro,ru,sk,sv,sw
ta,te,th,tr,uk,ur,vi,xh,zh,zu

the 3wa will be in that language.

Learn more about what3words and their location naming scheme.

wikidata Wikidata item for the location.
Example: Q1534213

A Wikidata item is a unique identifier used by the Wikimedia Foundation and others. Learn more about Wikidata.

Operational Status

You can always check status.opencagedata.com to see our current operational status as measured by independent, third-party monitoring. In the event of network or other operational issues we will keep you informed via the @OpenCage Twitter account.

Screenshot of the OpenCage status page
The OpenCage status page

At the start of each year we publish a blog post reporting the uptime of the prior year.

Best Practices

General advice:

  • Save yourself a lot of time by not reinventing the wheel.
    Use one of the many libraries that already exist for accessing our API.
  • If you do not need the information provided in the annotations please set no_annotations=1.
    This enables us to do less work and significantly reduces the response size and thus reply more quickly.
    In our guide to geocoding more quickly we outline a few more strategies for speed.
  • If you are geocoding non-English locations, please don't forget to set the optional language parameter - see details.
  • Program defensively. We are aggregating data from many rapidly-changing data sources. While we make every effort to clean things up, your code should be as forgiving as possible.
  • If you are geocoding any significant volume, please read our guide to geocoding large datasets.
  • Changes to the API are very rare, but if you are depending on our service please "watch" our public Changelog on Github, so you are notified when we announce and changes.

When forward geocoding:

  • It helps us greatly is you can format your query well.
    Please see our detailed guide on how to format your forward geocoding query.
  • We are much more likely to give you a correct answer if you are able to use the bounds and/or countrycode parameters as this lets us route the search better and narrow the results considerably.

  • We may return multiple relevant results. Please see our guide to understanding geocoding accuracy to learn strategies for deciding which result is the one you want.

    If you plan to only look at the first result and disregard the others then please set limit=1 as this enables us to only return a single result. We thus do less work and the response size is smaller.

  • If the request comes from a mobile device whose location you know or a user viewing a map please consider using the optional proximity parameter to bias results to the user's location or the location the user is viewing.

Troubleshooting / Common Issues

If things aren't working as you hope, here's some advice:

Privacy

In using the OpenCage geocoding API you are sending us your location data. While we have no ability or desire to link locations with individuals, any time you are transferring data it makes sense to consider the privacy implications.

  • We are a European (German) legal entity, and thus fully bound by the EU's General Data Protection Regulation (GDPR). Please find all details of our compliance with GDPR in our privacy policy.
  • As a reassurance for any users of the API with privacy concerns, we provide the optional no_record parameter. See details. When this parameter is set we keep no record of your query.

  • Our geocoding API attempts to geocode to the most precise level possible. There are use cases where exposing a full address or precise location may pose a privacy risk. This will necessarily depend on how exactly you are using location data in your application. Nevertheless, we provide the following guide to how to create an imprecise location description to preserve privacy.

    Please be responsible in your use of location data.

  • Free trial accounts are deleted after six months of inactivity, afterwhich we have no record of the account. You can also delete your account sooner anytime you like in your account dashboard.

If you have any questions about our approach to privacy or data protection, please don't hesitate to get in touch.

Fuzzy matching / Autosuggest

Our geocoding API is designed for geocoding, and does NOT perform "fuzzy" matching. As an example, a request with query par will NOT return Paris, France as a result.

Geosearch

If you want location "autosuggest", "autocomplete" or "type ahead", what you want is our geosearch service.

Many people confuse forward geocoding with geosearch. Forward geocoding expects an address or placename as an input, and returns location information (coordinates, etc). Geosearch takes any string of text as input and tries to expand the string, and return a list of possible placename matches.

For more background please see our guide explaining the differences between geocoding and geosearch .

Caching

Feel free to cache, or store, results as long as you like, you know your use case and whether or not it makes sense.

That said, the world is a constantly changing place and the underlying datasets, like OpenStreetMap, that we're querying are always evolving, so it may make sense to refresh your cache regularly. For ease of caching every response has a timestamp section with both a human readable HTTP timestamp - in the created_http key, and a Unix timestamp - in the created_unix key.

Customers often ask us when it makes sense to cache. In the case of forward geocoding you can look at a normalized version of the request. In the case of reverse though it is not so clear cut. If two coordinates are the same to X places past the decimal, should you not bother with a request? This depends of course on what level of granularity you need in a response. There is almost no reason to go beyond six or seven places past the decimal as that then gets down to the precision of a centimeter. See Wikipedia about decimal degree precision.

Whether or not caching makes sense largely depends on your use case. You'll have to test and see what works for you.

Our experience is that caching makes sense at the device level. For example if you are doing fleet tracking and the vehicle is parked, there is no reason to continually request the identical coordinates. So it makes sense to keep a record of the last 20 or 50 or whatever positions and then only request if the coordinates have changed. Beyond that caching for reverse requests is not particularly useful as the number of potential requests is so massive that direct hits are rare.

Caching is only one of several ways to speed things up. Please see our guide to geocoding more quickly where we outline strategies to optimze for speed.

Language

Many places have different names in different languages. To tell us you favour results in a specific language use the optional language parameter, otherwise we will default to the language of your browser or, if no browser language is specified, English. Please see the language parameter documentation for a detailed explanation of how we determine which language to favour.

We rely on many different datasets. Some, like OpenStreetMap, tend to have results in many languages. Others tend to have results only in English. Specifying language does not mean we will return results purely in that language, only that we will do our best to favour such results if we have them.

If you specify language=native we will attempt to return results in the local language. As an example, instead of Munich you will receive München.

Please be aware that the geocoders we build upon typically use the "official" language of the country, which may not actually be the language spoken locally. Also, many countries have multiple "official" languages. As an example, instead of returning Belgium as we would for a request with language=en we would return België / Belgique / Belgien for a request with language=native.

Nearest Road / Speed Limit Information

Many of our clients use our service for vehicle or fleet tracking, and are interested in information about the roads the vehicles are travelling on. To simplify this use case we offer the optional parameter roadinfo. Setting this optional parameter (adding roadinfo=1 to your request) has a few implications:

  • The behaviour of the geocoder changes to try to match the nearest road rather than the nearest address. This behaviour is often known as "snap to road". You will likely get different results if this parameter is set.

  • We will add the roadinfo annotation to the response, regardless of whether the optional parameter no_annotations is set or not. Please see the roadinfo annotation documentation for the exact list of fields we attempt to return.

Please note:

  • Many roads in rural areas don't (yet) have names, or they may not yet be named in the data sources we have available. In this case we set the name of the road to be unnamed road.
  • The information we return comes from crowdsourced databases like OpenStreetMap. It should NOT be taken as official governmental data. It may be out of date or simply wrong, and especially the speed limit in the maxspeed key may have many caveats, for example different speed limits depending on time of day, time of year, weather conditions, type of vehicle, etc.

The results are provided for informational purposes only and common sense should always be used. Always drive safely.

Libraries/SDKs, Tutorials, and Recipies

Don't waste your time reinventing the wheel.

There are open-source SDKs for accessing the OpenCage geocoding API for over 30 different programming languages and frameworks, including java, nodejs, PHP, python, ruby, and many more.

Some developers prefer to use API examination tools. We have step by step guides for accessing our API in Postman and Insomnia. You can of course also use the API directly from the command line.

We also have a list of recipies for common use cases, for example:

Batch or Bulk Geocoding

We are sometimes asked if the geocoding API supports sending more than one location per request, sometimes referred to as "batch" or "bulk" geocoding. The answer is no.

We intentionally don’t support more than one location per request as our experience is that 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 almost all of our customers.

Our entire goal is simplicity.

If you need to geocode many locations quickly the way to do so is by sending requests in parallel. We have customers geocoding millions of locations per day, it works.

Please read our guide to geocoding large datasets where we explain various strategies and points to consider.

IP restriction

Subscription customers can define a list of IP addresses that are allowed to use their API key. All requests with that API key that come from non-allowed IP numbers will receive a 403 - IP address rejected response.

Customers can add or delete IP addresses in their account dashboard (in the "Geocoding API" tab in your account dashboard click on the "settings" button next to the API key). Changes to API key settings take approximately 10 minutes to take effect as they are distributed out to all of our servers.

CORS / JSONP

If you are accessing the geocoding API from client side javascript in a browser please be aware that by default the OpenCage Geocoding API allows all origins for Cross-Origin Resource Sharing (CORS).

Geosearch

Please note, if you want location "autosuggest", "autocomplete" or "type ahead", what you probably want is our geosearch service, not our geocoding API.

By default the geocoding API response includes the HTTP header access-control-allow-origin: * which thus allows all cross-origin requests.

If you are a subscription customer, you can change this by defining a domain per API key in your account dashboard (in the "Geocoding API" tab in your account dashboard click on the "settings" button next to the API key). Changes to API key settings take approximately 10 minutes to take effect as they are distributed out to all of our servers.

Once set, we will then return: access-control-allow-origin: https://some-customer-defined-domain.com which will thus restrict AJAX requests to the specified domain. It is important to note this does nothing to prevent someone from making an API request with your key, it just makes AJAX requests from within a browser stop working. Please see our detailed advice on protecting your API key(s) .

The value you specify should be of the form second level domain . top level domain
For example: opencagedata.com

There is no need to specify protocol (https or http), subdomains, or ports, we will return the correct access-control-allow-origin header. We also automatically support all requests with an origin of localhost.

An example: if you add opencagedata.com as your domain, requests with the following origin values will all work correctly:

  • http://www.opencagedata.com
  • https://blog.opencagedata.com
  • http://localhost:3000
  • http://dev.opencagedata.com:8080

Additional resources:

Change Log

We keep a record of all changes to the API on GitHub. We also recommend you follow us on Mastodon and/or read our blog where all changes are announced.

Migrating from other geocoding services

You may find our guide to switching from Google Maps or switching from Nominatim to be helpful.

Google Compatibility

As a convenience we provide a Google compatible response format for forward geocoding.
X  Please note, support for the google-v3-json format may be discontinued in the future as it is not used much. We strongly recommend migrating to our JSON response format. Please see our overview of how our service differs from Google's.

Required Parameters

  • address - the query string to be geocoded; this must be URL encoded
  • key - your OpenCage geocoding API key, a 32 character long, alphanumeric string

Optional Parameters

  • bounds - a viewport, 2 coordinate pairs, e.g. 34.172684,-118.604794|34.236144,-118.500938
  • region - a country code, e.g. es for Spain
  • sensor - required by Google as an indicator of whether the request comes from a device with a location sensor; this parameter is ignored by the OpenCage geocoding API.

Google JSON Output

In the following example, a response in Google's JSON format is requested to get the coordinates of the old OpenCage office in central London at 82 Clerkenwell Road, London EC1M 5RF, United Kingdom.

https://api.opencagedata.com/geocode/v1/google-v3-json?address=82+Clerkenwell+Road%2C+London+EC1M+5RF%2C+United+Kingdom&pretty=1&key=YOUR-API-KEY

A JSON geocoding response contains 3 elements:

  • total_results - the number of elements in the results array
  • results - an array of result responses
  • status - the overall status of the request

The JSON returned by the geocoder will look like: 

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Europe",
               "short_name" : "Europe",
               "types" : [
                  "continent"
               ]
            },
            {
               "long_name" : "London",
               "short_name" : "London",
               "types" : [
                  "locality",
                  "political"
               ]
            },
            {
               "long_name" : "England",
               "short_name" : "England",
               "types" : [
                  "administrative_area_level_1",
                  "political"
               ]
            },
            {
               "long_name" : "Greater London",
               "short_name" : "Greater London",
               "types" : [
                  "administrative_area_level_2",
                  "political"
               ]
            },
            {
               "long_name" : "European Union",
               "short_name" : "European Union",
               "types" : [
                  "political_union"
               ]
            },
            {
               "long_name" : "SW1A 2DX",
               "short_name" : "SW1A 2DX",
               "types" : [
                  "postal_code"
               ]
            },
            {
               "long_name" : "United Kingdom",
               "short_name" : "United Kingdom",
               "types" : [
                  "country",
                  "political"
               ]
            }
         ],
         "formatted_address" : "London SW1A 2DX, United Kingdom",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : "51.6673219",
                  "lng" : "0.0323526"
               },
               "southwest" : {
                  "lat" : "51.3473219",
                  "lng" : "-0.2876474"
               }
            },
            "location" : {
               "lat" : "51.5073219",
               "lng" : "-0.1276474"
            }
         }
      },
      {
         "address_components" : [
            {
               "long_name" : "London",
               "short_name" : "London",
               "types" : [
                  "administrative_area_level_2",
                  "political"
               ]
            },
            {
               "long_name" : "Europe",
               "short_name" : "Europe",
               "types" : [
                  "continent"
               ]
            },
            {
               "long_name" : "England",
               "short_name" : "England",
               "types" : [
                  "administrative_area_level_1",
                  "political"
               ]
            },
            {
               "long_name" : "Greater London",
               "short_name" : "Greater London",
               "types" : [
                  "administrative_area_level_2",
                  "political"
               ]
            },
            {
               "long_name" : "European Union",
               "short_name" : "European Union",
               "types" : [
                  "political_union"
               ]
            },
            {
               "long_name" : "United Kingdom",
               "short_name" : "United Kingdom",
               "types" : [
                  "country",
                  "political"
               ]
            }
         ],
         "formatted_address" : "London, United Kingdom",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : "51.6918741",
                  "lng" : "0.3340155"
               },
               "southwest" : {
                  "lat" : "51.2867601",
                  "lng" : "-0.5103751"
               }
            },
            "location" : {
               "lat" : "51.4893335",
               "lng" : "-0.144055084527687"
            }
         }
      },
      {
         "address_components" : [
            {
               "long_name" : "City of London",
               "short_name" : "City of London",
               "types" : [
                  "administrative_area_level_2",
                  "political"
               ]
            },
            {
               "long_name" : "Europe",
               "short_name" : "Europe",
               "types" : [
                  "continent"
               ]
            },
            {
               "long_name" : "England",
               "short_name" : "England",
               "types" : [
                  "administrative_area_level_1",
                  "political"
               ]
            },
            {
               "long_name" : "Greater London",
               "short_name" : "Greater London",
               "types" : [
                  "administrative_area_level_2",
                  "political"
               ]
            },
            {
               "long_name" : "European Union",
               "short_name" : "European Union",
               "types" : [
                  "political_union"
               ]
            },
            {
               "long_name" : "United Kingdom",
               "short_name" : "United Kingdom",
               "types" : [
                  "country",
                  "political"
               ]
            }
         ],
         "formatted_address" : "City of London, United Kingdom",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : "51.5233213",
                  "lng" : "-0.0727261"
               },
               "southwest" : {
                  "lat" : "51.5068696",
                  "lng" : "-0.1138211"
               }
            },
            "location" : {
               "lat" : "51.514947",
               "lng" : "-0.0930460965094679"
            }
         }
      },
      {
         "address_components" : [
            {
               "long_name" : "North America",
               "short_name" : "North America",
               "types" : [
                  "continent"
               ]
            },
            {
               "long_name" : "London",
               "short_name" : "London",
               "types" : [
                  "locality",
                  "political"
               ]
            },
            {
               "long_name" : "Ontario",
               "short_name" : "Ontario",
               "types" : [
                  "administrative_area_level_1",
                  "political"
               ]
            },
            {
               "long_name" : "Southwestern Ontario",
               "short_name" : "Southwestern Ontario",
               "types" : [
                  "administrative_area_level_2",
                  "political"
               ]
            },
            {
               "long_name" : "N6B 2P8",
               "short_name" : "N6B 2P8",
               "types" : [
                  "postal_code"
               ]
            },
            {
               "long_name" : "Canada",
               "short_name" : "Canada",
               "types" : [
                  "country",
                  "political"
               ]
            }
         ],
         "formatted_address" : "London, ON N6B 2P8, Canada",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : "43.148576",
                  "lng" : "-81.086643"
               },
               "southwest" : {
                  "lat" : "42.828576",
                  "lng" : "-81.406643"
               }
            },
            "location" : {
               "lat" : "42.988576",
               "lng" : "-81.246643"
            }
         }
      },
      {
         "address_components" : [
            {
               "long_name" : "London",
               "short_name" : "London",
               "types" : [
                  "administrative_area_level_2",
                  "political"
               ]
            },
            {
               "long_name" : "North America",
               "short_name" : "North America",
               "types" : [
                  "continent"
               ]
            },
            {
               "long_name" : "Ontario",
               "short_name" : "Ontario",
               "types" : [
                  "administrative_area_level_1",
                  "political"
               ]
            },
            {
               "long_name" : "Southwestern Ontario",
               "short_name" : "Southwestern Ontario",
               "types" : [
                  "administrative_area_level_2",
                  "political"
               ]
            },
            {
               "long_name" : "Canada",
               "short_name" : "Canada",
               "types" : [
                  "country",
                  "political"
               ]
            }
         ],
         "formatted_address" : "Southwestern Ontario, ON, Canada",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : "43.0730461",
                  "lng" : "-81.1070784"
               },
               "southwest" : {
                  "lat" : "42.824599",
                  "lng" : "-81.3906556"
               }
            },
            "location" : {
               "lat" : "42.9537654",
               "lng" : "-81.2291529"
            }
         }
      },
      {
         "address_components" : [
            {
               "long_name" : "Laurel County",
               "short_name" : "Laurel County",
               "types" : [
                  "administrative_area_level_2",
                  "political"
               ]
            },
            {
               "long_name" : "North America",
               "short_name" : "North America",
               "types" : [
                  "continent"
               ]
            },
            {
               "long_name" : "London",
               "short_name" : "London",
               "types" : [
                  "locality",
                  "political"
               ]
            },
            {
               "long_name" : "Kentucky",
               "short_name" : "Kentucky",
               "types" : [
                  "administrative_area_level_1",
                  "political"
               ]
            },
            {
               "long_name" : "40741",
               "short_name" : "40741",
               "types" : [
                  "postal_code"
               ]
            },
            {
               "long_name" : "United States of America",
               "short_name" : "United States of America",
               "types" : [
                  "country",
                  "political"
               ]
            }
         ],
         "formatted_address" : "London, KY 40741, United States of America",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : "37.15226",
                  "lng" : "-84.035957"
               },
               "southwest" : {
                  "lat" : "37.079759",
                  "lng" : "-84.126262"
               }
            },
            "location" : {
               "lat" : "37.1289771",
               "lng" : "-84.0832646"
            }
         }
      },
      {
         "address_components" : [
            {
               "long_name" : "Madison County",
               "short_name" : "Madison County",
               "types" : [
                  "administrative_area_level_2",
                  "political"
               ]
            },
            {
               "long_name" : "North America",
               "short_name" : "North America",
               "types" : [
                  "continent"
               ]
            },
            {
               "long_name" : "London",
               "short_name" : "London",
               "types" : [
                  "locality",
                  "political"
               ]
            },
            {
               "long_name" : "Ohio",
               "short_name" : "Ohio",
               "types" : [
                  "administrative_area_level_1",
                  "political"
               ]
            },
            {
               "long_name" : "43140",
               "short_name" : "43140",
               "types" : [
                  "postal_code"
               ]
            },
            {
               "long_name" : "United States of America",
               "short_name" : "United States of America",
               "types" : [
                  "country",
                  "political"
               ]
            }
         ],
         "formatted_address" : "London, OH 43140, United States of America",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : "39.921786",
                  "lng" : "-83.389997"
               },
               "southwest" : {
                  "lat" : "39.85928",
                  "lng" : "-83.478923"
               }
            },
            "location" : {
               "lat" : "39.8864493",
               "lng" : "-83.448253"
            }
         }
      },
      {
         "address_components" : [
            {
               "long_name" : "Pope County",
               "short_name" : "Pope County",
               "types" : [
                  "administrative_area_level_2",
                  "political"
               ]
            },
            {
               "long_name" : "North America",
               "short_name" : "North America",
               "types" : [
                  "continent"
               ]
            },
            {
               "long_name" : "London",
               "short_name" : "London",
               "types" : [
                  "locality",
                  "political"
               ]
            },
            {
               "long_name" : "Arkansas",
               "short_name" : "Arkansas",
               "types" : [
                  "administrative_area_level_1",
                  "political"
               ]
            },
            {
               "long_name" : "United States of America",
               "short_name" : "United States of America",
               "types" : [
                  "country",
                  "political"
               ]
            }
         ],
         "formatted_address" : "London, AR, United States of America",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : "35.3389327",
                  "lng" : "-93.1874567"
               },
               "southwest" : {
                  "lat" : "35.3169503",
                  "lng" : "-93.2716305"
               }
            },
            "location" : {
               "lat" : "35.328973",
               "lng" : "-93.2529553"
            }
         }
      },
      {
         "address_components" : [
            {
               "long_name" : "Tulare County",
               "short_name" : "Tulare County",
               "types" : [
                  "administrative_area_level_2",
                  "political"
               ]
            },
            {
               "long_name" : "North America",
               "short_name" : "North America",
               "types" : [
                  "continent"
               ]
            },
            {
               "long_name" : "California",
               "short_name" : "California",
               "types" : [
                  "administrative_area_level_1",
                  "political"
               ]
            },
            {
               "long_name" : "London",
               "short_name" : "London",
               "types" : [
                  "locality",
                  "political"
               ]
            },
            {
               "long_name" : "United States of America",
               "short_name" : "United States of America",
               "types" : [
                  "country",
                  "political"
               ]
            }
         ],
         "formatted_address" : "London, CA, United States of America",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : "36.4884367",
                  "lng" : "-119.4385395"
               },
               "southwest" : {
                  "lat" : "36.4734452",
                  "lng" : "-119.4497699"
               }
            },
            "location" : {
               "lat" : "36.4760619",
               "lng" : "-119.4431785"
            }
         }
      }
   ],
   "status" : "OK"
}

Open API / Swagger specification

As a convenience we provide an Open API / Swagger specification for the OpenCage Geocoding API.

Other geolocation technologies

There are many different geolocation technologies, and geocoding is often confused or conflated with them.

You may find our guides useful where we explain the attributes of each technology:

Finally, we are sometimes asked if we can locate a mobile phone simply via the phone number. No, we can't, and neither can anyone else. Please read the details on our blog.

Help Us Improve

If anything in this documentation is unclear, or you have questions about the geocoding API please get in touch with us.

Geocoding the world is a tough challenge, we would love your help. Much of our code is open source, feedback or pull requests are always appreciated.

Bugs

Unfortunately, humanity has not always chosen to name places in a way that is simple for computers to decipher. The task a geocoder faces is a difficult one.

A geocoder consists of two things, software and the underlying data. So there are two types of problems that can occur: a software problem, or data problems (erroneous or missing data). In both cases we want to solve it, but what needs to be done depends on the type of problem we're facing. Regardless, we appreciate your feedback and will work with you to get better.

Security Issues

We make every effort to keep user data secure, please see our security policy for details. If you find a security vulnerability please report it to security @ opencagedata.com, we will follow up with you promptly. Please see the details of our security bounty program. If you wish to encrypt your report you can find our public key on our security.txt. Thank you.

Thanks

Thank you for using the OpenCage geocoding API. Thanks also to everyone who has contributed data and software to OpenStreetMap and the other open geo datasources we rely on. Learn more about how we give back to the open geospatial community.

Start your free trial

2,500 geocoding API requests per day.

No credit card required.

This image shows the node density of OpenStreetMap data in summer 2015.
It's one of many data sources we use.

Data © OpenStreetMap contributors, Imagery © Martin Raifer, cc-by
Open as larger interactive map
OpenStreetMap node coverage