The OpenCage Geocoder API

Quick Start

1. Sign up for your free key

2. Start geocoding by requesting a URL:

Reverse geocoding http://api.opencagedata.com/geocode/v1/json?q=LAT+LNG&key=YOUR-API-KEY
Forward geocoding http://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, annotations, etc. please see below:

Reverse and Forward Geocoding

The OpenCage Geocoder provides simple and easy to use 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 sources to find the most correct answer to your query. The good folks at Wikipedia provide a great general background on geocoding.

Caveats

The OpenCage Geocoder API is currently v1; features may change in a future version. Please follow us on twitter and/or read our blog to stay up to date.

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. Please see the Help Us Improve section below. We appreciate your feedback and will work with you to get better.

Operational Status

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

Authentication

Using the OpenCage Geocoder needs a valid API key that you must pass to the geocoder with each call to the API by using the key parameter. Sign up for your free key

Rate Limiting

The OpenCage Geocoder uses a rate limiting mechanism to ensure that the service stays available to all users. Information on this is returned by the API in the response headers as well as in the rate element of the response body.

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

Free usage is limited to 2,500 queries per day. If you need more, please see the pricing page. We would love to have you as a customer. If you are not a customer and continually request far beyond the free 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.

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

Queries per second

Free trial users are limited to 1 query 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 queries per second depending on pricing tier. Please see the exact levels on our pricing page. If you need more than 15 queries per second please get in touch to discuss your exact needs.

Caching

Feel free to cache results as long as you like, you know your use case and whether or not it makes sense. That said, the world is a constanly 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 result has both human readable and unix timestamps.

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 query. In the case of reverse though it is not so clear cut. If two coordiantes 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. Our experience is that caching makes sense at the device level. For example if you're 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 queries is not particularly useful as the numebr of potential queries 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.

Request Format

A geocoder API request is in the following form:

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

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 displays a map showing the positions of each location that matches the query when viewed in a browser.
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. Have fun with that.
Requests with any other format will recieve a response with status 400 - not a valid format.

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 below for a full list of all optional parameters, and a detailed explanation of how we determine which language to favor.

We rely on many different datasets. Some, like OpenStreetMap, tend to have results in local 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.

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 to do. Where a partial match is made, for example a street name can be matched but a specific house number on that street cannot be matched, the geocoder will still return a result but the granularity of the match will not be as high as if the house number was matched.

The precision of a match returned in the confidence field. This contains a value between 0 and 10 , where 0 reflects inability to determine a confidence (due to there being no bounding box) 1 reflects low precision and 10 reflects high precision.

Confidence is calculated by measuring the distance in kilometres between the South West and North East corners of each results bounding box; a smaller distance represents a high confidence while a large distance represents a lower confidence.

Please note, you can supply the optional min_confidence parameter ( see below ).

10 less than 0.25 km distance
9 less than 0.5 km distance
8 less than 1 km distance
7 less than 5 km distance
6 less than 7.5 km distance
5 less than 10 km distance
4 less than 15 km distance
3 less than 20 km distance
2 less than 25 km distance
1 25 km or greater distance
0 unable to determine a bounding box

Geocoding Queries with Ambiguous Results

In cases where the geocoder is able to find multiple matches, the geocoder will return multiple results. The confidence or coordinates for each result should be examined to determine whether each result from an ambiguous query is sufficiently high to warrant using a result or not. A good strategy to reduce ambiguity is to use the optional bounds parameter described below to limit the area searched.

Geocoding Queries with No Results

In cases where the geocoder cannot find any match for a query, the geocoder will return a successful status but the number of results in the response will be zero.

Response Codes

The status element of the geocoder's response contains the following:

code the HTTP status code
message a human readable form of the HTTP status code

The following status codes will be returned

200 OK (zero or more results will be returned)
400 Invalid request (bad request; a required parameter is missing)
402 Valid request but quota exceeded (payment required)
403 Invalid or missing api key (forbidden)
404 Invalid API endpoint
408 Timeout; you can try again
410 Request too long
503 Internal server error

Geocoding a Query

Required Parameters

key a pre-authorised application key

Sign up for your free key
q the query string to be geocoded; a placename or lat,long.

This must be URL encoded, ie spaces should be a +, and comma should be %2C.

If forward geocoding please use commas to seperate parts of the address. This helps us improve the chance of finding the correct answer and answer more quickly. For example, if possible, rather than sending us 'Triererstr 15 99423 Weimar Deutschland' please send us 'Triererstr 15, 99423 Weimar, Deutschland' , which should be URL encoded as Triererstr+15%2C+99423+Weimar%2C+Deutschland

Optional Parameters

add_request Adds the various request parameters to the response for ease of debugging.
bounds Provides the geocoder with a hint to the region that the query resides in. This value will restrict the possible results to the supplied region. The bounds parameter should be specified as 4 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 long, min lat, max long, max lat).
countrycode Used only for forward geocoding. Restricts the results to the specified country 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. Please note, many non-country territories have their own code, for example 'pr' for Puerto Rico.

You can specify multiple codes by supplying a comma seperated list. For example countrycode=fr,bl,gf,gp,mf,mq,nc,pf,pm,re,tf,wf,yt would be all French territories.

Non-two letter countrycodes are ignored.

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). If no language is explicitly specified, we will look for an HTTP Accept-Language header like those sent by a browser and use the first language specified. If none are thus specified 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.
limit How many results should be returned. Default is 10. Maximum is 100.
min_confidence An integer from 1-10. Only results with at least this confidence will be returned.
no_annotations When set to 1 results will not contain annotations.
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.

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: Coordinates should always be specified in latitude, longitude order.

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,+14.5272&pretty=1&key=YOUR-API-KEY

The JSON returned by the reverse geocoder will look like:

{
   "documentation" : "https://geocoder.opencagedata.com/api",
   "licenses" : [
      {
         "name" : "CC-BY-SA",
         "url" : "http://creativecommons.org/licenses/by-sa/3.0/"
      },
      {
         "name" : "ODbL",
         "url" : "http://opendatacommons.org/licenses/odbl/summary/"
      }
   ],
   "rate" : {
      "limit" : 2500,
      "remaining" : 2495,
      "reset" : 1461628800
   },
   "results" : [
      {
         "annotations" : {
            "DMS" : {
               "lat" : "22\u00b0 40' 46.34148'' S",
               "lng" : "14\u00b0 31' 39.36216'' E"
            },
            "MGRS" : "33KVQ5147391877",
            "Maidenhead" : "JG77gh36hv",
            "Mercator" : {
               "x" : 1617205.101,
               "y" : -2576841.379
            },
            "OSM" : {
               "edit_url" : "https://www.openstreetmap.org/edit?node=2234312397#map=17/-22.67954/14.52760",
               "url" : "https://www.openstreetmap.org/?mlat=-22.67954&mlon=14.52760#map=17/-22.67954/14.52760"
            },
            "callingcode" : 264,
            "geohash" : "k7fqfx6djeknke6zjhb6",
            "sun" : {
               "rise" : {
                  "apparent" : 1461561540,
                  "astronomical" : 1461556980,
                  "civil" : 1461560160,
                  "nautical" : 1461558600
               },
               "set" : {
                  "apparent" : 1461602400,
                  "astronomical" : 1461606960,
                  "civil" : 1461603780,
                  "nautical" : 1461605400
               }
            },
            "timezone" : {
               "name" : "Africa/Windhoek",
               "now_in_dst" : 0,
               "offset_sec" : 3600,
               "offset_string" : 100,
               "short_name" : "WAT"
            },
            "what3words" : {
               "words" : "matriarchs.nano.rotates"
            }
         },
         "components" : {
            "_type" : "clothes",
            "city" : "Swakopmund",
            "clothes" : "Jet",
            "country" : "Namibia",
            "country_code" : "na",
            "road" : "Nathaniel Maxuilili St (Breite St)",
            "state" : "Erongo Region",
            "suburb" : "Central"
         },
         "confidence" : 10,
         "formatted" : "Jet, Nathaniel Maxuilili St (Breite St), Swakopmund, Namibia",
         "geometry" : {
            "lat" : -22.6795393,
            "lng" : 14.5276006
         }
      }
   ],
   "status" : {
      "code" : 200,
      "message" : "OK"
   },
   "stay_informed" : {
      "blog" : "http://blog.opencagedata.com",
      "twitter" : "https://twitter.com/opencagedata"
   },
   "thanks" : "For using an OpenCage Data API",
   "timestamp" : {
      "created_http" : "Mon, 25 Apr 2016 21:17:31 GMT",
      "created_unix" : 1461619051
   },
   "total_results" : 1
}

XML Output

In the following example, a response in XML format is requested for the same JSON response query above, to get the address for coordinates --22.6792, 14.5272.

https://api.opencagedata.com/geocode/v1/xml?q=-22.6792,+14.5272&key=YOUR-API-KEY

The XML returned by the reverse geocoder will look like:

<response>
  <documentation>https://geocoder.opencagedata.com/api</documentation>
  <licenses>
    <license>
      <name>CC-BY-SA</name>
      <url>http://creativecommons.org/licenses/by-sa/3.0/</url>
    </license>
    <license>
      <name>ODbL</name>
      <url>http://opendatacommons.org/licenses/odbl/summary/</url>
    </license>
  </licenses>
  <rate>
    <limit>2500</limit>
    <remaining>2494</remaining>
    <reset>1461628800</reset>
  </rate>
  <results>
    <result>
      <annotations>
        <DMS>
          <lat>22° 40' 46.34148'' S</lat>
          <lng>14° 31' 39.36216'' E</lng>
        </DMS>
        <MGRS>33KVQ5147391877</MGRS>
        <Maidenhead>JG77gh36hv</Maidenhead>
        <Mercator>
          <x>1617205.101</x>
          <y>-2576841.379</y>
        </Mercator>
        <OSM>
          <edit_url>https://www.openstreetmap.org/edit?node=2234312397#map=17/-22.67954/14.52760</edit_url>
          <url>https://www.openstreetmap.org/?mlat=-22.67954&amp;mlon=14.52760#map=17/-22.67954/14.52760</url>
        </OSM>
        <callingcode>264</callingcode>
        <geohash>k7fqfx6djeknke6zjhb6</geohash>
        <sun>
          <rise>
            <apparent>1461561540</apparent>
            <astronomical>1461556980</astronomical>
            <civil>1461560160</civil>
            <nautical>1461558600</nautical>
          </rise>
          <set>
            <apparent>1461602400</apparent>
            <astronomical>1461606960</astronomical>
            <civil>1461603780</civil>
            <nautical>1461605400</nautical>
          </set>
        </sun>
        <timezone>
          <name>Africa/Windhoek</name>
          <now_in_dst>0</now_in_dst>
          <offset_sec>3600</offset_sec>
          <offset_string>+0100</offset_string>
          <short_name>WAT</short_name>
        </timezone>
        <what3words>
          <words>matriarchs.nano.rotates</words>
        </what3words>
      </annotations>
      <components>
        <_type>clothes</_type>
        <city>Swakopmund</city>
        <clothes>Jet</clothes>
        <country>Namibia</country>
        <country_code>na</country_code>
        <road>Nathaniel Maxuilili St (Breite St)</road>
        <state>Erongo Region</state>
        <suburb>Central</suburb>
      </components>
      <confidence>10</confidence>
      <formatted>Jet, Nathaniel Maxuilili St (Breite St), Swakopmund, Namibia</formatted>
      <geometry>
        <lat>-22.6795393</lat>
        <lng>14.5276006</lng>
      </geometry>
    </result>
  </results>
  <status>
    <code>200</code>
    <message>OK</message>
  </status>
  <stay_informed>
    <blog>http://blog.opencagedata.com</blog>
    <twitter>https://twitter.com/opencagedata</twitter>
  </stay_informed>
  <thanks>For using an OpenCage Data API</thanks>
  <timestamp>
    <created_http>Mon, 25 Apr 2016 21:15:26 GMT</created_http>
    <created_unix>1461618926</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 Rua Cafelândia in Carapicuíba, Brasil.

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

The JSON returned by the geocoder will look like:

{
   "documentation" : "https://geocoder.opencagedata.com/api",
   "licenses" : [
      {
         "name" : "CC-BY-SA",
         "url" : "http://creativecommons.org/licenses/by-sa/3.0/"
      },
      {
         "name" : "ODbL",
         "url" : "http://opendatacommons.org/licenses/odbl/summary/"
      }
   ],
   "rate" : {
      "limit" : 2500,
      "remaining" : 2499,
      "reset" : 1461628800
   },
   "results" : [
      {
         "annotations" : {
            "DMS" : {
               "lat" : "23\u00b0 32' 14.54352'' S",
               "lng" : "46\u00b0 50' 14.86608'' W"
            },
            "MGRS" : "23KLP1242595789",
            "Maidenhead" : "GG66nl91ma",
            "Mercator" : {
               "x" : -5213922.509,
               "y" : -2680078.23
            },
            "OSM" : {
               "edit_url" : "https://www.openstreetmap.org/edit?way=185327107#map=17/-23.53737/-46.83746",
               "url" : "https://www.openstreetmap.org/?mlat=-23.53737&mlon=-46.83746#map=17/-23.53737/-46.83746"
            },
            "callingcode" : 55,
            "geohash" : "6gydn5nhb587vf642f07",
            "sun" : {
               "rise" : {
                  "apparent" : 1461576300,
                  "astronomical" : 1461571740,
                  "civil" : 1461574920,
                  "nautical" : 1461573300
               },
               "set" : {
                  "apparent" : 1461617040,
                  "astronomical" : 1461621600,
                  "civil" : 1461618420,
                  "nautical" : 1461620040
               }
            },
            "timezone" : {
               "name" : "America/Sao_Paulo",
               "now_in_dst" : 0,
               "offset_sec" : -10800,
               "offset_string" : -300,
               "short_name" : "BRT"
            },
            "what3words" : {
               "words" : "basket.hoping.asteroid"
            }
         },
         "bounds" : {
            "northeast" : {
               "lat" : -23.537007,
               "lng" : -46.8356769
            },
            "southwest" : {
               "lat" : -23.5373732,
               "lng" : -46.8374628
            }
         },
         "components" : {
            "_type" : "road",
            "city" : "Carapicu\u00edba",
            "city_district" : "Carapicu\u00edba",
            "country" : "Brazil",
            "country_code" : "br",
            "county" : "Microrregi\u00e3o de Osasco",
            "postcode" : "06455000",
            "road" : "Rua Cafel\u00e2ndia",
            "state" : "S\u00e3o Paulo",
            "state_district" : "Mesorregi\u00e3o Metropolitana de S\u00e3o Paulo"
         },
         "confidence" : 10,
         "formatted" : "Rua Cafel\u00e2ndia, Carapicu\u00edba - SP, 06455-000, Brazil",
         "geometry" : {
            "lat" : -23.5373732,
            "lng" : -46.8374628
         }
      }
   ],
   "status" : {
      "code" : 200,
      "message" : "OK"
   },
   "stay_informed" : {
      "blog" : "http://blog.opencagedata.com",
      "twitter" : "https://twitter.com/opencagedata"
   },
   "thanks" : "For using an OpenCage Data API",
   "timestamp" : {
      "created_http" : "Mon, 25 Apr 2016 21:15:23 GMT",
      "created_unix" : 1461618923
   },
   "total_results" : 1
}

GeoJSON Output

In the following example, a response in GeoJSON format is requested for Rua Cafelândia in Carapicuíba, Brasil.

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

Learn more about the GeoJSON format .

{
   "features" : [
      {
         "geometry" : {
            "coordinates" : [
               -46.8374628,
               -23.5373732
            ],
            "type" : "Point"
         },
         "properties" : {
            "annotations" : {
               "DMS" : {
                  "lat" : "23\u00b0 32' 14.54352'' S",
                  "lng" : "46\u00b0 50' 14.86608'' W"
               },
               "MGRS" : "23KLP1242595789",
               "Maidenhead" : "GG66nl91ma",
               "Mercator" : {
                  "x" : -5213922.509,
                  "y" : -2680078.23
               },
               "OSM" : {
                  "edit_url" : "https://www.openstreetmap.org/edit?way=185327107#map=17/-23.53737/-46.83746",
                  "url" : "https://www.openstreetmap.org/?mlat=-23.53737&mlon=-46.83746#map=17/-23.53737/-46.83746"
               },
               "callingcode" : 55,
               "geohash" : "6gydn5nhb587vf642f07",
               "sun" : {
                  "rise" : {
                     "apparent" : 1461576300,
                     "astronomical" : 1461571740,
                     "civil" : 1461574920,
                     "nautical" : 1461573300
                  },
                  "set" : {
                     "apparent" : 1461617040,
                     "astronomical" : 1461621600,
                     "civil" : 1461618420,
                     "nautical" : 1461620040
                  }
               },
               "timezone" : {
                  "name" : "America/Sao_Paulo",
                  "now_in_dst" : 0,
                  "offset_sec" : -10800,
                  "offset_string" : -300,
                  "short_name" : "BRT"
               },
               "what3words" : {
                  "words" : "basket.hoping.asteroid"
               }
            },
            "bounds" : {
               "northeast" : {
                  "lat" : -23.537007,
                  "lng" : -46.8356769
               },
               "southwest" : {
                  "lat" : -23.5373732,
                  "lng" : -46.8374628
               }
            },
            "components" : {
               "_type" : "road",
               "city" : "Carapicu\u00edba",
               "city_district" : "Carapicu\u00edba",
               "country" : "Brazil",
               "country_code" : "br",
               "county" : "Microrregi\u00e3o de Osasco",
               "postcode" : "06455000",
               "road" : "Rua Cafel\u00e2ndia",
               "state" : "S\u00e3o Paulo",
               "state_district" : "Mesorregi\u00e3o Metropolitana de S\u00e3o Paulo"
            },
            "confidence" : 10,
            "formatted" : "Rua Cafel\u00e2ndia, Carapicu\u00edba - SP, 06455-000, Brazil"
         },
         "type" : "Feature"
      }
   ],
   "type" : "FeatureCollection"
}

XML Output

In the following example, a response in XML format is requested for Rua Cafelândia in Carapicuíba, Brasil.

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

The XML returned by the geocoder looks like:

<response>
  <documentation>https://geocoder.opencagedata.com/api</documentation>
  <licenses>
    <license>
      <name>CC-BY-SA</name>
      <url>http://creativecommons.org/licenses/by-sa/3.0/</url>
    </license>
    <license>
      <name>ODbL</name>
      <url>http://opendatacommons.org/licenses/odbl/summary/</url>
    </license>
  </licenses>
  <rate>
    <limit>2500</limit>
    <remaining>2498</remaining>
    <reset>1461628800</reset>
  </rate>
  <results>
    <result>
      <annotations>
        <DMS>
          <lat>23° 32' 14.54352'' S</lat>
          <lng>46° 50' 14.86608'' W</lng>
        </DMS>
        <MGRS>23KLP1242595789</MGRS>
        <Maidenhead>GG66nl91ma</Maidenhead>
        <Mercator>
          <x>-5213922.509</x>
          <y>-2680078.230</y>
        </Mercator>
        <OSM>
          <edit_url>https://www.openstreetmap.org/edit?way=185327107#map=17/-23.53737/-46.83746</edit_url>
          <url>https://www.openstreetmap.org/?mlat=-23.53737&amp;mlon=-46.83746#map=17/-23.53737/-46.83746</url>
        </OSM>
        <callingcode>55</callingcode>
        <geohash>6gydn5nhb587vf642f07</geohash>
        <sun>
          <rise>
            <apparent>1461576300</apparent>
            <astronomical>1461571740</astronomical>
            <civil>1461574920</civil>
            <nautical>1461573300</nautical>
          </rise>
          <set>
            <apparent>1461617040</apparent>
            <astronomical>1461621600</astronomical>
            <civil>1461618420</civil>
            <nautical>1461620040</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>basket.hoping.asteroid</words>
        </what3words>
      </annotations>
      <bounds>
        <northeast>
          <lat>-23.537007</lat>
          <lng>-46.8356769</lng>
        </northeast>
        <southwest>
          <lat>-23.5373732</lat>
          <lng>-46.8374628</lng>
        </southwest>
      </bounds>
      <components>
        <_type>road</_type>
        <city>Carapicuíba</city>
        <city_district>Carapicuíba</city_district>
        <country>Brazil</country>
        <country_code>br</country_code>
        <county>Microrregião de Osasco</county>
        <postcode>06455000</postcode>
        <road>Rua Cafelândia</road>
        <state>São Paulo</state>
        <state_district>Mesorregião Metropolitana de São Paulo</state_district>
      </components>
      <confidence>10</confidence>
      <formatted>Rua Cafelândia, Carapicuíba - SP, 06455-000, Brazil</formatted>
      <geometry>
        <lat>-23.5373732</lat>
        <lng>-46.8374628</lng>
      </geometry>
    </result>
  </results>
  <status>
    <code>200</code>
    <message>OK</message>
  </status>
  <stay_informed>
    <blog>http://blog.opencagedata.com</blog>
    <twitter>https://twitter.com/opencagedata</twitter>
  </stay_informed>
  <thanks>For using an OpenCage Data API</thanks>
  <timestamp>
    <created_http>Mon, 25 Apr 2016 21:15:24 GMT</created_http>
    <created_unix>1461618924</created_unix>
  </timestamp>
  <total_results>1</total_results>
</response>

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.

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, country, continent, ficticious, unknown

Annotations

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

Currently we support the following annotations:

callingcode the telephone calling code for the country of the result.
DMS the latitude and longitude of the center point of the result in degree minute decimal second format.
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 3857, sometimes also referred to as "Spherical 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.
OSGB contains the Ordnance Survey National Grid easting , northing , and gridref of the center point of the result. This annotation is applied only for locations in Great Britain. Learn more about OSGB.
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 that you may need to zoom in or out to edit and in doing so focus may shift to a different element.
sun contains two keys rise and set , each of which in turn contains four keys: apparent (what is typically reports 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. Learn more about timezones and how they are typically represented on *nix based systems over on Wikipedia.
what3words contains a key words with a what3word location code. Learn more about what3words and their location naming scheme. By default the words returned are in English, but if the query contained the optional language and it is a language what3words supports, the words will be in that language.

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

  • 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 thus reply faster.
  • If you are geocoding non-English locations, please don't forget to set the optional language parameter.
  • When forward geocoding it helps to use commas between logical chunks of the query. For example 1859 Gallo Drive, Powell, Ohio, 43065, United States is more likely to yield a correct response than 1859 Gallo Drive Powell Ohio 43065 United States

Geocoding a Query to a Latitude and Longitude with Google Compatibility

Required Parameters

  • address - the query string to be geocoded; this must be URL encoded
  • key - a pre-authorised application key

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 Data office in Central London at 82 Clerkenwell Road, London EC1M 5RF .

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

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" : "Clerkenwell",
               "short_name" : "Clerkenwell",
               "types" : [
                  "sublocality"
               ]
            },
            {
               "long_name" : "Clerkenwell Road",
               "short_name" : "Clerkenwell Road",
               "types" : [
                  "route"
               ]
            },
            {
               "long_name" : "82",
               "short_name" : "82",
               "types" : [
                  "street_address"
               ]
            },
            {
               "long_name" : "England",
               "short_name" : "England",
               "types" : [
                  "administrative_area_level_1",
                  "political"
               ]
            },
            {
               "long_name" : "United Kingdom",
               "short_name" : "United Kingdom",
               "types" : [
                  "country",
                  "political"
               ]
            },
            {
               "long_name" : "London",
               "short_name" : "London",
               "types" : [
                  "locality",
                  "political"
               ]
            },
            {
               "long_name" : "Greater London",
               "short_name" : "Greater London",
               "types" : [
                  "administrative_area_level_2",
                  "political"
               ]
            },
            {
               "long_name" : "EC1M 5RF",
               "short_name" : "EC1M 5RF",
               "types" : [
                  "postal_code"
               ]
            }
         ],
         "formatted_address" : "82 Clerkenwell Road, London EC1M 5RF, United Kingdom",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : "51.5227563",
                  "lng" : "-0.1023801"
               },
               "southwest" : {
                  "lat" : "51.5226042",
                  "lng" : "-0.1025907"
               }
            },
            "location" : {
               "lat" : "51.52266915",
               "lng" : "-0.102486661883629"
            }
         }
      },
      {
         "address_components" : [
            {
               "long_name" : "Clerkenwell Road",
               "short_name" : "Clerkenwell Road",
               "types" : [
                  "route"
               ]
            },
            {
               "long_name" : "82",
               "short_name" : "82",
               "types" : [
                  "street_address"
               ]
            },
            {
               "long_name" : "Islington",
               "short_name" : "Islington",
               "types" : [
                  "administrative_area_level_1",
                  "political"
               ]
            },
            {
               "long_name" : "Clerkenwell",
               "short_name" : "Clerkenwell",
               "types" : [
                  "locality",
                  "political"
               ]
            },
            {
               "long_name" : "United Kingdom",
               "short_name" : "United Kingdom",
               "types" : [
                  "country",
                  "political"
               ]
            }
         ],
         "formatted_address" : "82 Clerkenwell Road, Clerkenwell, United Kingdom",
         "geometry" : {
            "location" : {
               "lat" : "51.5226749152876",
               "lng" : "-0.100965187713708"
            }
         }
      }
   ],
   "status" : "OK"
}

Open API / Swagger specification

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

Learn more about the Open API Initiative.

Help Us Improve

We welcome your feedback. You can see (and comment on) a high level overview of our roadmap on github. Our code for correctly formatting addresses is open source. It's a tough challenge, we would love your help.

Thanks

Many thanks for using the OpenCage Geocoder. Thanks also to everyone who has contributed data to OpenStreetMap, GeoNames, and other open geo data sources. Here is the full list of sources we rely on.

Get started with our free geocoding plan

No credit card required

Create your free account