OpenCage Geocoding API Documentation

Reverse and Forward Geocoding

The OpenCage Geocoder provides reverse (lat/long to text) and forward (text to lat/long) geocoding via a RESTful API.

Behind the scenes we query multiple geocoders from various open datasources - see the full list - to answer your request.

Quick Start

1. Sign up for your free API key

2. 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=PLACENAME&key=YOUR-API-KEY

For all the details of alternate output formats, optional parameters, rate limiting, response codes, best practices, migrating from Google's geocoder, annotations, etc. please see below.

You may also find our demo page or the various code libraries and tutorials helpful.

Authentication

Using the OpenCage Geocoder requires a valid API key that you must pass with each call to the API as the value of the the key parameter.

Sign up for your free API key

Rate Limiting

The OpenCage Geocoder uses a rate limiting mechanism to ensure that the service stays available to all users. Quota information for free trial users is returned by the API in the HTTP response headers as well as in the rate element of the response body.

Free trial usage is limited to 2,500 requests per day. Our day is based on the UTC timezone. Counts reset at midnight (24:00 UTC). See the current UTC time.

If you need more requests, or if you are using our service in a production environment, please see the pricing page. We would love to have you as a customer. If you are not a customer and continually request beyond the free trial usage limit (ie you ignore the 402 status) you will eventually be blocked and see a 403 - Forbidden response. So don't do that. Thanks.

For the avoidance of doubt - if you are regularly depending on our service - you should become a customer.

If a geocoding request is issued that either exhausts your available transactions for the day or your available transactions are already used, a status of 402 - Payment Required will be returned in both the HTTP headers and in the response status field.

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

Responses to paying customers do NOT contain the X-Ratelimit headers or the rate element of the response body, as paying customers do not face 'hard' limits. For details please see the Q&A section of Pricing & Billing FAQ.

Rate Limit Headers

X-RateLimit-Limit the total number of transactions that your account is limited to over a 24 hour period
X-RateLimit-Remaining the number of transactions remaining in the current 24 hour period
X-RateLimit-Reset the date and time, in UNIX format, at which your transaction count will reset

Requests per second

Free trial users are limited to 1 request per second and if you exceed that rate you may be blocked. Paying customers can use our service at a much faster rate, ranging from 10-15 requests per second depending on pricing tier. Please see the exact levels on our pricing page. If you need more than 15 requests per second please get in touch to discuss your exact needs.

If you request too quickly you will eventually see a 429 - Too many requests response.

Request Format

A geocoder API request is in the following form:

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

All requests should use the HTTP GET method. Requests that use another method will receive a response with status 405 - Method not allowed.

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 the geocoder response will be returned as JSON.
geojson the geocoder response will be returned as GeoJSON.
xml the geocoder response will be returned as XML.
map the geocoder will return HTML that, when viewed in a browser, displays a map showing the position of each result in the API response.
google-v3-json the geocoder request supports a subset of the Google v3 Geocoding API and returns a JSON response that it compatible with Google's. Please note we provide this format as a general convenience and do not actively maintain it. It is not widely used and may be discontinued. We encourage you to use the json or xml format. Please see details of our Google compatibility .
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.

You will find your key in your account dashboard.

Sign up for your free key

Free trial accounts are limited to one key per account, paid accounts can have multiple keys.
q the query string to be geocoded

a latitude, longitude or a placename/address

The query should be URL encoded, so spaces should be a +, comma should be %2C, 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. For example: 51.952659, 7.632473. There is no reason to send more than six or seven digits past the decimal as that then gets down to the precision of a centimeter. See Wikipedia about decimal degree precision. If impossible coordinates are supplied you will receive a 400 invalid coordinates as the response code in the status section of the response.

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 see the optional parameters below, and the best practices - especially our detailed guide on how to format your forward geocoding query.

Optional Parameters

abbrv When set to 1 we attempt to abbreviate and shorten the formatted string we return. Learn more about formatted placenames.
add_request When set to 1 the various request parameters are added to the response for ease of debugging.
bounds Used only for forward geocoding. This value will restrict the possible results to a defined bounding box.

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. For example: bounds=-0.563160,51.280430,0.278970,51.683979 (min lon, min lat, max lon, max lat).

Values that are not valid coordinates are ignored.

We have built a small, map-based tool to easily see bounds values. We hope it helps.
countrycode Used only for forward geocoding. Restricts results to the specified country/territory or countries.

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

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.
min_confidence An integer from 1-10. Only results with at least this confidence will be returned. Learn more about our confidence score.
no_annotations When set to 1 results will not contain annotations.

The only exception is if the optional roadinfo parameter is set (see below).
no_dedupe When set to 1 results will not be deduplicated.
no_record When set to 1 the query contents are not logged. Please use if you have concerns about privacy and want us to have no record of your query.
pretty When set to 1 results are 'pretty' printed for easier reading. Useful for debugging.
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 though, this is just one of many factors in the internal scoring we use for ranking results. The value is a point with latitude, longitude coordinates in decimal format. For example: 51.952659, 7.632473

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). If possible we also fill additional information in the roadinfo annotation. Please see details below.

Response Format

Reverse Geocoding Response Format

The response from the reverse geocoder is formatted according to the contents of the format component of the request URL.

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

JSON Output

In the following example, a response in JSON format is requested to get the nearest address 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 returned by the reverse geocoder will look like:

{
   "documentation" : "https://opencagedata.com/api",
   "licenses" : [
      {
         "name" : "see attribution guide",
         "url" : "https://opencagedata.com/credits"
      }
   ],
   "rate" : {
      "limit" : 15000,
      "remaining" : 14694,
      "reset" : 1563235200
   },
   "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=17/-22.67918/14.52680",
               "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$",
               "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 St",
               "speed_in" : "km/h"
            },
            "sun" : {
               "rise" : {
                  "apparent" : 1563169320,
                  "astronomical" : 1563164580,
                  "civil" : 1563167880,
                  "nautical" : 1563166200
               },
               "set" : {
                  "apparent" : 1563208440,
                  "astronomical" : 1563213180,
                  "civil" : 1563209880,
                  "nautical" : 1563211560
               }
            },
            "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.6790826,
               "lng" : 14.5269016
            },
            "southwest" : {
               "lat" : -22.6792826,
               "lng" : 14.5267016
            }
         },
         "components" : {
            "ISO_3166-1_alpha-2" : "NA",
            "ISO_3166-1_alpha-3" : "NAM",
            "_type" : "restaurant",
            "city" : "Swakopmund",
            "continent" : "Africa",
            "country" : "Namibia",
            "country_code" : "na",
            "restaurant" : "Beryl's Restaurant",
            "road" : "Woermann St",
            "state" : "Erongo Region",
            "suburb" : "Central"
         },
         "confidence" : 9,
         "formatted" : "Beryl's Restaurant, Woermann St, Swakopmund, Namibia",
         "geometry" : {
            "lat" : -22.6791826,
            "lng" : 14.5268016
         }
      }
   ],
   "status" : {
      "code" : 200,
      "message" : "OK"
   },
   "stay_informed" : {
      "blog" : "https://blog.opencagedata.com",
      "twitter" : "https://twitter.com/opencagedata"
   },
   "thanks" : "For using an OpenCage API",
   "timestamp" : {
      "created_http" : "Mon, 15 Jul 2019 14:58:08 GMT",
      "created_unix" : 1563202688
   },
   "total_results" : 1
}

GeoJSON Output

In the following example, a response in GeoJSON format is requested 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

Learn more about the GeoJSON format .

{
   "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",
                  "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$",
                  "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 St",
                  "speed_in" : "km/h"
               },
               "sun" : {
                  "rise" : {
                     "apparent" : 1563169320,
                     "astronomical" : 1563164580,
                     "civil" : 1563167880,
                     "nautical" : 1563166200
                  },
                  "set" : {
                     "apparent" : 1563208440,
                     "astronomical" : 1563213180,
                     "civil" : 1563209880,
                     "nautical" : 1563211560
                  }
               },
               "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.6790826,
                  "lng" : 14.5269016
               },
               "southwest" : {
                  "lat" : -22.6792826,
                  "lng" : 14.5267016
               }
            },
            "components" : {
               "ISO_3166-1_alpha-2" : "NA",
               "ISO_3166-1_alpha-3" : "NAM",
               "_type" : "restaurant",
               "city" : "Swakopmund",
               "continent" : "Africa",
               "country" : "Namibia",
               "country_code" : "na",
               "restaurant" : "Beryl's Restaurant",
               "road" : "Woermann St",
               "state" : "Erongo Region",
               "suburb" : "Central"
            },
            "confidence" : 9,
            "formatted" : "Beryl's Restaurant, Woermann St, Swakopmund, Namibia"
         },
         "type" : "Feature"
      }
   ],
   "licenses" : [
      {
         "name" : "see attribution guide",
         "url" : "https://opencagedata.com/credits"
      }
   ],
   "rate" : {
      "limit" : 15000,
      "remaining" : 14692,
      "reset" : 1563235200
   },
   "status" : {
      "code" : 200,
      "message" : "OK"
   },
   "stay_informed" : {
      "blog" : "https://blog.opencagedata.com",
      "twitter" : "https://twitter.com/opencagedata"
   },
   "thanks" : "For using an OpenCage API",
   "timestamp" : {
      "created_http" : "Mon, 15 Jul 2019 14:58:08 GMT",
      "created_unix" : 1563202688
   },
   "total_results" : 1,
   "type" : "FeatureCollection"
}

XML Output

In the following example, a response in XML format is requested 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 returned by the reverse geocoder will look like:

<response>
  <documentation>https://opencagedata.com/api</documentation>
  <licenses>
    <license>
      <name>see attribution guide</name>
      <url>https://opencagedata.com/credits</url>
    </license>
  </licenses>
  <rate>
    <limit>15000</limit>
    <remaining>14693</remaining>
    <reset>1563235200</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>
          <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>
          <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 St</road>
          <speed_in>km/h</speed_in>
        </roadinfo>
        <sun>
          <rise>
            <apparent>1563169320</apparent>
            <astronomical>1563164580</astronomical>
            <civil>1563167880</civil>
            <nautical>1563166200</nautical>
          </rise>
          <set>
            <apparent>1563208440</apparent>
            <astronomical>1563213180</astronomical>
            <civil>1563209880</civil>
            <nautical>1563211560</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.6790826</lat>
          <lng>14.5269016</lng>
        </northeast>
        <southwest>
          <lat>-22.6792826</lat>
          <lng>14.5267016</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>
        <_type>restaurant</_type>
        <city>Swakopmund</city>
        <continent>Africa</continent>
        <country>Namibia</country>
        <country_code>na</country_code>
        <restaurant>Beryl's Restaurant</restaurant>
        <road>Woermann St</road>
        <state>Erongo Region</state>
        <suburb>Central</suburb>
      </components>
      <confidence>9</confidence>
      <formatted>Beryl's Restaurant, Woermann St, Swakopmund, 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>
    <twitter>https://twitter.com/opencagedata</twitter>
  </stay_informed>
  <thanks>For using an OpenCage API</thanks>
  <timestamp>
    <created_http>Mon, 15 Jul 2019 14:58:08 GMT</created_http>
    <created_unix>1563202688</created_unix>
  </timestamp>
  <total_results>1</total_results>
</response>

Forward Geocoding Response Format

The response from the geocoder is returned according to the contents of the format component of the request URL.

JSON Output

In the following example, a response in JSON format is requested to get the coordinates of 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 returned by the geocoder will look like:

{
   "documentation" : "https://opencagedata.com/api",
   "licenses" : [
      {
         "name" : "see attribution guide",
         "url" : "https://opencagedata.com/credits"
      }
   ],
   "rate" : {
      "limit" : 15000,
      "remaining" : 14698,
      "reset" : 1563235200
   },
   "results" : [
      {
         "annotations" : {
            "DMS" : {
               "lat" : "23\u00b0 32' 13.34076'' S",
               "lng" : "46\u00b0 50' 8.35980'' W"
            },
            "MGRS" : "23KLP1260995829",
            "Maidenhead" : "GG66nl91rc",
            "Mercator" : {
               "x" : -5213721.321,
               "y" : -2680037.892
            },
            "OSM" : {
               "edit_url" : "https://www.openstreetmap.org/edit?way=185327107#map=16/-23.53704/-46.83566",
               "url" : "https://www.openstreetmap.org/?mlat=-23.53704&mlon=-46.83566#map=16/-23.53704/-46.83566"
            },
            "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" : "6gydn5pqf1uhc9v6p44f",
            "qibla" : 69.01,
            "roadinfo" : {
               "drive_on" : "right",
               "road" : "Rua Cafel\u00e2ndia",
               "road_type" : "residential",
               "speed_in" : "km/h"
            },
            "sun" : {
               "rise" : {
                  "apparent" : 1563184080,
                  "astronomical" : 1563179340,
                  "civil" : 1563182640,
                  "nautical" : 1563180960
               },
               "set" : {
                  "apparent" : 1563223080,
                  "astronomical" : 1563227820,
                  "civil" : 1563224520,
                  "nautical" : 1563226200
               }
            },
            "timezone" : {
               "name" : "America/Sao_Paulo",
               "now_in_dst" : 0,
               "offset_sec" : -10800,
               "offset_string" : "-0300",
               "short_name" : "BRT"
            },
            "what3words" : {
               "words" : "gosh.copiers.stops"
            }
         },
         "bounds" : {
            "northeast" : {
               "lat" : -23.5370391,
               "lng" : -46.8356555
            },
            "southwest" : {
               "lat" : -23.5373733,
               "lng" : -46.8374629
            }
         },
         "components" : {
            "ISO_3166-1_alpha-2" : "BR",
            "ISO_3166-1_alpha-3" : "BRA",
            "_type" : "road",
            "city" : "Carapicu\u00edba",
            "city_district" : "Carapicu\u00edba",
            "continent" : "South America",
            "country" : "Brazil",
            "country_code" : "br",
            "county" : "Regi\u00e3o Imediata de S\u00e3o Paulo",
            "postcode" : "06321-665",
            "road" : "Rua Cafel\u00e2ndia",
            "road_type" : "residential",
            "state" : "S\u00e3o Paulo",
            "state_code" : "SP",
            "state_district" : "Regi\u00e3o Intermedi\u00e1ria de S\u00e3o Paulo",
            "suburb" : "Parque Jos\u00e9 Alexandre"
         },
         "confidence" : 9,
         "formatted" : "Rua Cafel\u00e2ndia, Carapicu\u00edba - SP, 06321-665, Brazil",
         "geometry" : {
            "lat" : -23.5370391,
            "lng" : -46.8356555
         }
      }
   ],
   "status" : {
      "code" : 200,
      "message" : "OK"
   },
   "stay_informed" : {
      "blog" : "https://blog.opencagedata.com",
      "twitter" : "https://twitter.com/opencagedata"
   },
   "thanks" : "For using an OpenCage API",
   "timestamp" : {
      "created_http" : "Mon, 15 Jul 2019 14:58:06 GMT",
      "created_unix" : 1563202686
   },
   "total_results" : 1
}

GeoJSON Output

In the following example, a response in GeoJSON format is requested for 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

Learn more about the GeoJSON format .

{
   "documentation" : "https://opencagedata.com/api",
   "features" : [
      {
         "geometry" : {
            "coordinates" : [
               -46.8356555,
               -23.5370391
            ],
            "type" : "Point"
         },
         "properties" : {
            "annotations" : {
               "DMS" : {
                  "lat" : "23\u00b0 32' 13.34076'' S",
                  "lng" : "46\u00b0 50' 8.35980'' W"
               },
               "MGRS" : "23KLP1260995829",
               "Maidenhead" : "GG66nl91rc",
               "Mercator" : {
                  "x" : -5213721.321,
                  "y" : -2680037.892
               },
               "OSM" : {
                  "edit_url" : "https://www.openstreetmap.org/edit?way=185327107#map=17/-23.53704/-46.83566",
                  "url" : "https://www.openstreetmap.org/?mlat=-23.53704&mlon=-46.83566#map=17/-23.53704/-46.83566"
               },
               "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" : "6gydn5pqf1uhc9v6p44f",
               "qibla" : 69.01,
               "roadinfo" : {
                  "drive_on" : "right",
                  "road" : "Rua Cafel\u00e2ndia",
                  "road_type" : "residential",
                  "speed_in" : "km/h"
               },
               "sun" : {
                  "rise" : {
                     "apparent" : 1563184080,
                     "astronomical" : 1563179340,
                     "civil" : 1563182640,
                     "nautical" : 1563180960
                  },
                  "set" : {
                     "apparent" : 1563223080,
                     "astronomical" : 1563227820,
                     "civil" : 1563224520,
                     "nautical" : 1563226200
                  }
               },
               "timezone" : {
                  "name" : "America/Sao_Paulo",
                  "now_in_dst" : 0,
                  "offset_sec" : -10800,
                  "offset_string" : "-0300",
                  "short_name" : "BRT"
               },
               "what3words" : {
                  "words" : "gosh.copiers.stops"
               }
            },
            "bounds" : {
               "northeast" : {
                  "lat" : -23.5370391,
                  "lng" : -46.8356555
               },
               "southwest" : {
                  "lat" : -23.5373733,
                  "lng" : -46.8374629
               }
            },
            "components" : {
               "ISO_3166-1_alpha-2" : "BR",
               "ISO_3166-1_alpha-3" : "BRA",
               "_type" : "road",
               "city" : "Carapicu\u00edba",
               "city_district" : "Carapicu\u00edba",
               "continent" : "South America",
               "country" : "Brazil",
               "country_code" : "br",
               "county" : "Regi\u00e3o Imediata de S\u00e3o Paulo",
               "postcode" : "06321-665",
               "road" : "Rua Cafel\u00e2ndia",
               "road_type" : "residential",
               "state" : "S\u00e3o Paulo",
               "state_code" : "SP",
               "state_district" : "Regi\u00e3o Intermedi\u00e1ria de S\u00e3o Paulo",
               "suburb" : "Parque Jos\u00e9 Alexandre"
            },
            "confidence" : 9,
            "formatted" : "Rua Cafel\u00e2ndia, Carapicu\u00edba - SP, 06321-665, Brazil"
         },
         "type" : "Feature"
      }
   ],
   "licenses" : [
      {
         "name" : "see attribution guide",
         "url" : "https://opencagedata.com/credits"
      }
   ],
   "rate" : {
      "limit" : 15000,
      "remaining" : 14695,
      "reset" : 1563235200
   },
   "status" : {
      "code" : 200,
      "message" : "OK"
   },
   "stay_informed" : {
      "blog" : "https://blog.opencagedata.com",
      "twitter" : "https://twitter.com/opencagedata"
   },
   "thanks" : "For using an OpenCage API",
   "timestamp" : {
      "created_http" : "Mon, 15 Jul 2019 14:58:07 GMT",
      "created_unix" : 1563202687
   },
   "total_results" : 1,
   "type" : "FeatureCollection"
}

XML Output

In the following example, a response in XML format is requested for 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 returned by the geocoder looks like:

<response>
  <documentation>https://opencagedata.com/api</documentation>
  <licenses>
    <license>
      <name>see attribution guide</name>
      <url>https://opencagedata.com/credits</url>
    </license>
  </licenses>
  <rate>
    <limit>15000</limit>
    <remaining>14697</remaining>
    <reset>1563235200</reset>
  </rate>
  <results>
    <result>
      <annotations>
        <DMS>
          <lat>23° 32' 13.34076'' S</lat>
          <lng>46° 50' 8.35980'' W</lng>
        </DMS>
        <MGRS>23KLP1260995829</MGRS>
        <Maidenhead>GG66nl91rc</Maidenhead>
        <Mercator>
          <x>-5213721.321</x>
          <y>-2680037.892</y>
        </Mercator>
        <OSM>
          <edit_url>https://www.openstreetmap.org/edit?way=185327107#map=16/-23.53704/-46.83566</edit_url>
          <url>https://www.openstreetmap.org/?mlat=-23.53704&amp;mlon=-46.83566#map=16/-23.53704/-46.83566</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>6gydn5pqf1uhc9v6p44f</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>1563184080</apparent>
            <astronomical>1563179340</astronomical>
            <civil>1563182640</civil>
            <nautical>1563180960</nautical>
          </rise>
          <set>
            <apparent>1563223080</apparent>
            <astronomical>1563227820</astronomical>
            <civil>1563224520</civil>
            <nautical>1563226200</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>gosh.copiers.stops</words>
        </what3words>
      </annotations>
      <bounds>
        <northeast>
          <lat>-23.5370391</lat>
          <lng>-46.8356555</lng>
        </northeast>
        <southwest>
          <lat>-23.5373733</lat>
          <lng>-46.8374629</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>
        <_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 Imediata de São Paulo</county>
        <postcode>06321-665</postcode>
        <road>Rua Cafelândia</road>
        <road_type>residential</road_type>
        <state>São Paulo</state>
        <state_code>SP</state_code>
        <state_district>Região Intermediária de São Paulo</state_district>
        <suburb>Parque José Alexandre</suburb>
      </components>
      <confidence>9</confidence>
      <formatted>Rua Cafelândia, Carapicuíba - SP, 06321-665, Brazil</formatted>
      <geometry>
        <lat>-23.5370391</lat>
        <lng>-46.8356555</lng>
      </geometry>
    </result>
  </results>
  <status>
    <code>200</code>
    <message>OK</message>
  </status>
  <stay_informed>
    <blog>https://blog.opencagedata.com</blog>
    <twitter>https://twitter.com/opencagedata</twitter>
  </stay_informed>
  <thanks>For using an OpenCage API</thanks>
  <timestamp>
    <created_http>Mon, 15 Jul 2019 14:58:06 GMT</created_http>
    <created_unix>1563202686</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).

Geocoding Confidence

The OpenCage Geocoder 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. Please note, 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. So 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.

You can supply the optional min_confidence parameter (see optional parameter details).

10 < 0.25 km distance
9 < 0.5 km
8 < 1 km
7 < 5 km
6 < 7.5 km
5 < 10 km
4 < 15 km
3 < 20 km
2 < 25 km
1 25 km or greater distance
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.

The confidence, coordinates, or _type key in the components list for each result should be examined to determine whether each result from an ambiguous query is sufficiently correct to warrant using a result or not. A good strategy to reduce ambiguity is to use the optional bounds, countrycode, and/or proximity parameters.

Note: Reverse geocoding always returns 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.

Response Codes

The status element of the response contains the following:

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

The following status 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 blocked)
404 Invalid API endpoint
405 Method not allowed (non-GET request)
408 Timeout; you can try again
410 Request too long
429 Too many requests (too quickly, rate limiting)
503 Internal server error

For testing you can use the following API keys:

Formatted Placename and Components

For each result we supply a formatted field which contains a well formatted version of the place name. We attempt to display the name of the location in a way that would make sense to humans. This is difficult in that across the world there are many different ways to format an address.

For more background please read our blog post on the topic. We welcome your contributions to the open-source templates we use to tackle the address formatting problem .

If screenspace is limited - for example on a mobile device - we will attempt to shorten or abbreviate the formatted string if the optional parameter abbrv is supplied. The various abbreviations are all open-sourced in the code repo mentioned above. We welcome your contributions.

The formatted placename is created from the various terms in the components hash. This is the raw data we have to work with. We are often asked if there is a definitive list of all possible component keys. Unfortunately not. For convenience we add the key _type with the value set to what we believe the matched location to be. In the case where we can't determine a type we set the value unknown.

Possible values of _type include (but are not limited to): building, road, village, neighbourhood, city, county, postcode, state_district, state, region, island, body_of_water, country, continent, ficticious, unknown.

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

When possible we set the keys ISO_3166-1_alpha-2, ISO_3166-1_alpha-3, continent. Possible values for continent are Africa, Antarctica, Asia, Europe, Oceania, North America, South America.

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.

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

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.

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

Caching is only one of several ways to speed things up. Please see our FAQ section where we outline a strategies to optimze for speed .

Language

Many places have different names in different languages. To tell us you favour results in a specific language please use the optional language parameter, otherwise we will default to the language of your browser or, if no browser language is specified, English. See the section on optional parameters 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, so 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.

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 has a few implications:

  • The behaviour of the geocoder changes to try to match roads rather than addresses. You will likely get different results than if this parameter is not set.

  • We will add the roadinfo annotation, regardless of whether no_annotations is set or not.

Please see the roadinfo annotation documentation for the exact list of fields we attempt to return.

Note: the information in 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.

Annotations

By defaults each result contains an annotations field 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, 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.
currency information about the local currency
DMS the latitude and longitude of the center point of the result in degree minute decimal second format
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. This annotation is applied only for locations in the United States and associated territories. The values are strings - not numbers - and can have leading zeros.

Learn more about FIPS county codes.
flag emoji flag of the country of the result
geohash contains a geohash for the center point of the result.
ITM contains the Irish Transverse Mercator easting and northing of the center point of the result.

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

Note: use of Mercator projection on latitudes above/below +70/-70 degrees is strongly discouraged, due to the gross distortions of the projection.
MGRS contains a Military Grid Reference System code for the center point of the result. WGS84 datum.
OSM contains a key url with an HTTPS url for looking at the center point of the result on openstreetmap.org.
May also contain a key edit_url with an HTTPS 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.
qibla decimal degrees clockwise from true north to turn to point to the Kaaba (21.4225,39.8262).

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 number)
  • road_reference_intl (international road number)

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 govermental 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.
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) and
  • nautical (navigation using a sea horizon possible/no longer possible)
with Unix timestamps as values corresponding to the four different types of sunrise/set.

A value of 0 means the sun never rises/sets on that day (equivalent to 00:00-23:59), e.g. during midsummer.
timezone contains the keys name , now_in_dst , offset_sec , offset_string , short_name.

When the coordinates are in a country the 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 relevant United Nations M49 codes.

The annotation consists of two keys: regions and statistical_groupings.

The regions key contains key which are human-readable names of the regions in English and values which are 3 digit UN M49 codes. Note: The codes are strings and not numbers, they can have leading zeros.

For example: "WORLD": "001", "AFRICA": "002", "SUB-SAHARAN AFRICA": "202"

You can see a full list of all possible regions and the corresponsing codes.

The value of the statistical_groupings key is a list of abbreviations of names of various country groupings commonly used in statistical analysis.

Possible values are

Learn more about the UN M49 standard on Wikipedia.
what3words contains a key words whose value is a 3 words address (3wa).

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

af,ar,cs,da,de,el,en,es,fi,fr,id,it,ja,ko,mn,nb,nl,pl,pt,ru,sv,sw,th,tr,xh,zu

the 3wa will be in that language.

Learn more about what3words and their location naming scheme.
wikidata Wikidata item for the location.

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

Annotations can be turned off via the optional no_annotations parameter. Over time we will add more and more annotations, and are working towards a way to opensource their creation. We welcome all suggestions as to relevant annotations you would like to see.

Best Practices

  • You can probably save yourself a lot of time by not reinventing the wheel. Use one of the many libraries that already exist for accessing our API.

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

  • If you do not need the information provided in the annotations please set no_annotations=1 as this enables us to do less work and significantly reduces the response size and thus reply faster.

  • For forward geocoding requests we may return multiple results. 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. Reverse geocoding requests return at most a single result.

  • If you are geocoding non-English locations, please don't forget to set the optional language parameter.

  • When forward geocoding it helps us greatly is you can format your query well. Please use commas between logical chunks of the query, and remove non-address information like names.

    For example: 1859 Gallo Drive, Powell, Ohio, 43065, United States is more likely to yield a correct response than Mr. Smith 1859 Gallo Dr Powell Ohio 43065 United States

    Please see our detailed guide on how to format your forward geocoding query.

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

  • We are often asked how to make responses faster. Please see our FAQ section where we outline a few strategies .

Operational Status

In the event of network or other operational issues we will keep you informed via the @OpenCageData twitter account. We also have a third-party dashboard of past operational performance.

In the last 30 days our independently monitored uptime has been:

Forward geocoding
Reverse geocoding

Google Compatibility

As a convenience we provide a Google compatible response format for forward geocoding. Please note this may be discontinued in the future as it is not used much.

We strongly recommend migrating to our 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 - you API key, a 30 character long, alphanumeric string

Optional Parameters

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

Google JSON Output

In the following example, a response in Google's JSON format is requested to get the coordinates of 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" : "United Kingdom",
               "short_name" : "United Kingdom",
               "types" : [
                  "country",
                  "political"
               ]
            },
            {
               "long_name" : "EC1M 5RF",
               "short_name" : "EC1M 5RF",
               "types" : [
                  "postal_code"
               ]
            },
            {
               "long_name" : "GB",
               "short_name" : "GB",
               "types" : [
                  "ISO_3166-1_alpha-2"
               ]
            },
            {
               "long_name" : "England",
               "short_name" : "England",
               "types" : [
                  "administrative_area_level_1",
                  "political"
               ]
            },
            {
               "long_name" : "GBR",
               "short_name" : "GBR",
               "types" : [
                  "ISO_3166-1_alpha-3"
               ]
            },
            {
               "long_name" : "European Union",
               "short_name" : "European Union",
               "types" : [
                  "political_union"
               ]
            },
            {
               "long_name" : "Islington",
               "short_name" : "Islington",
               "types" : [
                  "locality",
                  "political"
               ]
            },
            {
               "long_name" : "ENG",
               "short_name" : "ENG",
               "types" : [
                  "state_code"
               ]
            },
            {
               "long_name" : "Europe",
               "short_name" : "Europe",
               "types" : [
                  "continent"
               ]
            },
            {
               "long_name" : "Clerkenwell",
               "short_name" : "Clerkenwell",
               "types" : [
                  "sublocality"
               ]
            },
            {
               "long_name" : "London",
               "short_name" : "London",
               "types" : [
                  "region"
               ]
            }
         ],
         "formatted_address" : "Islington EC1M 5RF, United Kingdom",
         "geometry" : {
            "location" : {
               "lat" : 51.522676,
               "lng" : -0.102549
            }
         }
      }
   ],
   "status" : "OK"
}

Open API / Swagger specification

Want an Open API / Swagger specification for our API? Look no further, here it is.

We also have tutorials for accessing our API in Postman and Insomnia REST client.

Change Log

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

Help Us Improve

We welcome your feedback.

If any thing in this documentation is unclear, please let us know.

You can see (and comment on) a high level overview of our roadmap on github.

Lots of our code is open source. Geocoding the world is a tough challenge, we would love your help.

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. If you find a vulnerability please report it to security @ opencagedata.com, we will follow up with you immediately. You can find our public key on our security.txt. Thank you.

Thanks

Many thanks for using the OpenCage Geocoder.

Thanks also to everyone who has contributed data and software to OpenStreetMap and the other open geo datasources we rely on. Here is the full list of sources we rely on.

Start your free trial

2,500 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