# OpenCage API documentation ## Copy page - [Copy page Copy page as Markdown for LLMs](#) - [View as Markdown View this page as plain text](https://opencagedata.com/api.md) Quick Start 1. [Sign up for your geocoding API key](https://opencagedata.com/users/sign_up) or test the API [on our demo page](https://opencagedata.com/demo). 2. Once you have an API key, start geocoding by requesting a URL: **Reverse geocoding** (query is latitude, longitude) Example request for coordinates `52.5432379, 13.4142133` `https://api.opencagedata.com/geocode/v1/json?q=52.5432379%2C+13.4142133&key=YOUR-API-KEY` **Forward geocoding** (query is an address or placename) Example request for `Frauenplan 1, 99423 Weimar, Germany` `https://api.opencagedata.com/geocode/v1/json?q=Frauenplan+1%2C+99423+Weimar%2C+Germany&key=YOUR-API-KEY` Or use one of the many [SDKs](https://opencagedata.com/sdks) (40+ programming languages / frameworks). 3. See below for all the details of [optional parameters](#optional-params), [response format](#response), [caching](#caching), [free trial rate limiting](#rate-limiting), [best practices](#bestpractices), and much more. Working with AI? See [our Agent Skill](https://github.com/OpenCageData/opencage-skills/) to quickly train your AI on using our geocoding API. Wondering how we compare with others? See our [guide to comparing geocoding services](https://opencagedata.com/guides/how-to-compare-and-test-geocoding-services) for an overview of all the factors to consider. ## Authentication Using the OpenCage geocoding API requires a valid API key that you must pass with each HTTP request as the value of the `key` parameter - one of two [required parameters](#required-params). It is NOT necessary to set any HTTP headers for authentication. Read why not [in our FAQ](https://opencagedata.com/faq#header-auth). [Sign up for your geocoding API key](https://opencagedata.com/users/sign_up) If you become a paying customer you can continue to use the same API key you used during your free trial, or you can create a new API key. Subscription customers can have multiple active API keys. ## Request Format A geocoding API request is in the following form: `https://api.opencagedata.com/geocode/VERSION/FORMAT?parameters` Both the HTTP 1.1 and HTTP/2 protocols are supported. All requests should use the HTTP `GET ` method. Requests that use any other method will receive a response with status ` 405 - Method not allowed`. Both `http ` and ` https ` schemes are supported. We strongly recommend ` https ` as requests made using ` http ` are not encrypted. ` https ` requests must use TLS 1.2 or higher. ` https ` requests that use an older (insecure) TLS will fail. If you are stuck with ancient software that does not support TLS 1.2 or higher you should use ` http`, and find a way to upgrade as soon as possible. The `VERSION ` component of the URL should be replaced with a version of the format ` v + version number `. The current version is ` v1 `. Requests with an incorrect version number will receive a ` 400 - not a valid version` response. The `FORMAT` component of the URL should be replaced with one of the following: | value | description | | --- | --- | | `json` | response returned as JSON | | `geojson` | response returned as GeoJSON | | `xml` | response returned as XML | | `google-v3-json ` | the OpenCage geocoding API supports a subset of the [Google v3 Geocoding API](https://developers.google.com/maps/documentation/geocoding/) and returns a JSON response that is compatible with Google's. Please note, we provide this format as a convenience and do not actively maintain it. It is not widely used, and will likely eventually be discontinued. We encourage you to use the ` json` format. Please see [details of our Google compatibility](#google-compat). | API requests with any other format will receive a response with status `400 - not a valid format`. ## Request Parameters ### Required Parameters | parameter | description | | --- | --- | | `key` | a 32 character long, alphanumeric string unique to your account. **Example usage:** `key=YOUR-API-KEY` - If not provided the request will fail with status `401 missing API key`. - You will find your API key in the "Geocoding" tab of your account dashboard - By default accounts are limited to one active key. Subscription customers can have multiple active API keys. - [Replacing your geocoding API key](https://opencagedata.com/guides/how-to-create-a-new-api-key) - [Protecting your geocoding API key](https://opencagedata.com/guides/how-to-protect-your-api-key) Your geocoding API key is used only for our geocoding API and is NOT used to authenticate for [our geosearch/autosuggest service](https://opencagedata.com/geosearch). | | `q` | the query string to be geocoded. Either a latitude, longitude or a placename/address. **Example usage:** | reverse geocoding: | `q=52.5432379+13.4142133` | | forward geocoding: | `q=Berlin,+Germany` | - If not provided the request will fail with status `400 missing or bad query`. - Must be [URL encoded](https://en.wikipedia.org/wiki/Percent-encoding). Instead of, for example, non-ascii strings like `München ` you should send us ` M%C3%BCnchen`. Note that most [SDKs](https://opencagedata.com/sdks) will do the encoding for you, be careful to avoid double encoding your query. - Must be at least two characters long. Queries that are too short will fail with status `400 missing or bad query`. - Queries that are too long will fail with status `400 query too long`. - Queries that contain obvious erroneous data will fail with status `400 missing or bad query`. **Points to note when reverse geocoding** - Query should be in latitude, longitude order in decimal format. Use period (.) as the decimal separator, not comma. - There is no reason to send more than six or seven digits past the decimal, that is centimeter precision. [See Wikipedia about decimal degree precision](https://en.wikipedia.org/wiki/Decimal_degrees). - If impossible coordinates are supplied the API responds with with status `400 invalid coordinates`. - Reverse geocoding results contain the field `distance_from_q` which is the distance (in meters) to the coordinates in the request to the coordinates of the result. **Points to note when forward geocoding** - Please see our detailed guide to [formatting your forward geocoding query](https://opencagedata.com/guides/how-to-format-your-geocoding-query). - If possible make use of the [optional parameters](#optional-params), especially `bounds ` and ` countrycode`. - We [do NOT support fuzzy matching](#autosuggest). - You can lookup UN/LOCODEs by adding the prefix `LOCODE:` to your query, for example: `LOCODE:DEBRV`. Learn [the details of how we handle UN/LOCODEs](#unlocode). | ### Optional Parameters | parameter | description | | --- | --- | | `abbrv` | When set to 1 we attempt to abbreviate and shorten the `formatted` string we return. **Example usage:** `abbrv=1` Learn more about [formatted placenames](#formatted). Are we missing abbreviations in your language? If so please help us by [contributing improvements](https://github.com/OpenCageData/address-formatting/tree/master/conf/abbreviations). Thanks! | | `address_only` | When set to 1 we include only the address (excluding POI names) in the `formatted` string we return. **Example usage:** `address_only=1` As an example, by default a reverse geocoding request for the coordinates `50.976004, 11.336753 ` returns a ` formatted ` value of ` Goethes Gartenhaus, Corona-Schröter-Weg 1, 99425 Weimar, Germany `, but if ` address_only=1 ` is specified the value would be simply ` Corona-Schröter-Weg 1, 99425 Weimar, Germany`. This can be particularly useful when there are many stores/restaurants/whatever at a single location (for example a multi-story building). Note: in some parts of the world it is common for buildings to have names and not numbers. Or we may have only the name and not a house number. In this case we will include the name even if `address_only=1` is set. Learn more about [formatted placenames](#formatted). | | `add_request` | When set to 1 the various request parameters are added to the response for ease of debugging. **Example usage:** `add_request=1` Note that the value of `key` will be obfuscated. The first six characters will be shown, the rest replaced with `*` - so that the key is not mistakenly logged. | | `bounds` | Used only for forward geocoding. This value will restrict the possible results to a defined bounding box. **Example usage:** `bounds=-0.563160,51.280430,0.278970,51.683979` The value of the `bounds` parameter should be specified as two coordinate points forming the south-west and north-east corners of a bounding box (min longitude, min latitude, max longitude, max latitude). Values that are not valid coordinates are ignored. You may find our [small, map-based tool to easily see bounds values](https://opencagedata.com/tools/bounds-finder) to be useful. | | `countrycode` | Used only for forward geocoding. Restricts results to the specified country/territory or countries. **Example usage:** `countrycode=de` The country code is a two letter code as defined by the [ISO 3166-1 Alpha 2](https://en.wikipedia.org/wiki/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](#isocodes). 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](https://en.wikipedia.org/wiki/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](https://github.com/OpenCageData/opencagedata-misc-docs/blob/master/countrycode.md). | | `language` | An [IETF format language code](https://en.wikipedia.org/wiki/IETF_language_tag) (such as `es ` for Spanish or ` pt-BR ` for Brazilian Portuguese), or ` native` in which case we will attempt to return the response in the local language(s). **Example usage:** `language=de` If no language is explicitly specified, we will then look for an HTTP `Accept-Language ` header like those sent by a browser and use highest quality language specified (please see [RFC 4647](https://www.ietf.org/rfc/rfc4647.txt) 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](#language), particularly the caveats around specifying `language=native`. | | `limit` | Used only for forward geocoding. The maximum number of results we should return. Default is 10. Maximum allowable value is 100. **Example usage:** `limit=1` Please note: Reverse geocoding requests return **at most one single result**. Forward geocoding requests may return multiple results. | | `no_annotations` | When set to 1 results will not contain [annotations](#annotations). **Example usage:** `no_annotations=1` The only exception is if the optional `roadinfo` parameter is set (see below). | | `no_dedupe` | When set to 1 results will not be deduplicated. **Example usage:** `no_dedupe=1` | | `no_record` | When set to 1 the query contents are not logged. **Example usage:** `no_record=1` Please use this parameter if you have concerns about privacy, and want us to have no record of your query. Learn more about [our approach to privacy](#privacy). | | `pretty` | When set to 1 results are 'pretty' printed for easier reading/debugging. **Example usage:** `pretty=1` | | `proximity` | Used only for forward geocoding. Provides the geocoder with a hint to bias results in favour of those closer to the specified location. Please note, this is just one of many factors in the internal scoring we use for ranking results. **Example usage:** `proximity=52.5432379,13.4142133` The value is a point with latitude, longitude coordinates in decimal format. Values that are not valid coordinates are ignored. | | `roadinfo` | When set to 1 the behaviour of the geocoder is changed to attempt to match the nearest road (as opposed to address). **Example usage:** `roadinfo=1` If possible we also fill additional information in the `roadinfo` annotation. Please see [details below](#roadinfo). | ## Rate/Usage Limits The OpenCage geocoding API uses rate limits to ensure that the service stays available to all users. ### Free trial usage limits - Free trial accounts have a hard limit of **2,500** requests per day **for testing purposes**. Our definition of "day" is based on [the UTC timezone](https://en.wikipedia.org/wiki/Coordinated_Universal_Time). Daily counts reset at 24:00 UTC. [See current UTC time](https://opencagedata.com/tools/current-utc-time). - Free trial accounts are limited to one request per second. If you exceed that rate you may see a `429 - too many requests` response. - We offer a free TRIAL for testing, not a free tier for ongoing use. **If you are regularly depending on our service, you are not testing**. If you wish to use our geocoding API at higher volume or speed, or on an ongoing basis, become a customer. [See pricing](https://opencagedata.com/pricing). ### Paid usage limits Paying customers can use our service at higher volumes and much faster rate (requests per second). - We offer two different paid usage models: **subscriptions** (monthly and annual) and **one-time plans**. - Please see [our pricing page](https://opencagedata.com/pricing) for the exact details of the different tiers. ### Hard versus soft limits Free trial and one-time plan customers face hard limits. Subscription customers do not. **Hitting the usage limits** - If you send a request after you have reached your hard limit you will receive a `402 - quota exceeded` response - Free trial accounts that continually request beyond the hard limit (if you ignore the `402 ` response) will eventually be blocked and see a ` 403 - disabled` response. Please don't do that. Thanks. - If you exceed the request per second rate you may see a `429 - too many requests` response. - See below for [API keys](#testingkeys) you can use to generate a `402 ` or ` 403` response for testing. ### Seeing your real-time API use Real-time usage information for accounts with hard limits is returned by the API in both the `rate` element of the response and HTTP response headers. **Note:** Responses to subscription customers do **NOT** contain the `rate ` section of the response or ` X-Ratelimit` HTTP headers, because they do not face hard limits. | `rate` key | HTTP Header | meaning | | --- | --- | --- | | `limit ` | ` X-RateLimit-Limit` | total number of API requests your account is limited to over given time period (24 hours for free trials) | | `remaining ` | ` X-RateLimit-Remaining` | number of API requests remaining until hard limit is reached | | `reset ` | ` X-RateLimit-Reset` | [Unix time](https://en.wikipedia.org/wiki/Unix_time) at which count resets | Here is an example (in JSON format) of the information in the API response for accounts with hard limits. "rate" : { "limit" : 2500, "remaining" : 2498, "reset" : 1605312000 }, ### Seeing your past API use A graph of daily usage is shown in the "Geocoding API" tab of your account dashboard. There you will also find a link to a URL with a unique access token where you can download your daily usage as a CSV file. ![OpenCage account dashboard, geocoding API usage chart](https://assets.opencagedata.com/assets/usage-chart-screenshot-2e9d2dda19b6709a382b8e9d3a8915e3356e9f58a3cbd5b5d811248787dbb2af.png "OpenCage account dashboard, geocoding API usage chart") _Geocoding API usage chart in your account dashboard_ ## Response Codes The `status` element of the API response contains the following: | key | value | | --- | --- | | `code` | a three digit code | | `message` | a brief, human-readable explanation of the response code | The following response codes are possible: | `code` | meaning check `message` in API response for specific details | | --- | --- | | `200` | OK (zero or more results will be returned) | | `400` | Invalid request (bad request; a required parameter is missing; invalid coordinates; invalid version; invalid format) | | `401` | Unable to authenticate - missing, invalid, or unknown API key | | `402` | Valid request but quota exceeded (payment required) | | `403` | Forbidden (API key disabled or IP address rejected) | | `404` | Invalid API endpoint | | `405` | Method not allowed (non-GET request) | | `408` | Timeout; you can try again | | `410` | Request too long | | `426` | Upgrade required (unsupported TLS) | | `429` | Too many requests (too quickly, rate limiting) | | `503` | Internal server error | ### API keys for testing For testing purposes you can use the following API keys: | `key ` | ` response` | | --- | --- | | `6d0e711d72d74daeb2b0bfd2a5cdfdba `[](https://api.opencagedata.com/geocode/v1/json?key=6d0e711d72d74daeb2b0bfd2a5cdfdba&q=52.5432379%2C+13.4142133&pretty=1&no_annotations=1) | ` 200 - OK` \* | | `4372eff77b8343cebfc843eb4da4ddc4 `[](https://api.opencagedata.com/geocode/v1/json?key=4372eff77b8343cebfc843eb4da4ddc4&q=52.5432379%2C+13.4142133&pretty=1&no_annotations=1) | ` 402 - quota exceeded` | | `2e10e5e828262eb243ec0b54681d699a `[](https://api.opencagedata.com/geocode/v1/json?key=2e10e5e828262eb243ec0b54681d699a&q=52.5432379%2C+13.4142133&pretty=1&no_annotations=1) | ` 403 - disabled` | | `6c79ee8e1ca44ad58ad1fc493ba9542f `[](https://api.opencagedata.com/geocode/v1/json?key=6c79ee8e1ca44ad58ad1fc493ba9542f&q=52.5432379%2C+13.4142133&pretty=1&no_annotations=1) | ` 403 - IP address rejected` | | `d6d0f0065f4348a4bdfe4587ba02714b `[](https://api.opencagedata.com/geocode/v1/json?key=d6d0f0065f4348a4bdfe4587ba02714b&q=52.5432379%2C+13.4142133&pretty=1&no_annotations=1) | ` 429 - requesting too quickly` | To generate a successful API response with no results, send a request with `q=NOWHERE-INTERESTING `. We will reply with status ` 200` and 0 results. \* the `200 - OK ` key will behave as if the ` q` parameter of the request had been `51.952659,7.632473 ` regardless of what was actually specified (unless of course if ` q=NOWHERE-INTERESTING` was specified, as explained above). ## Response Format The API response is formatted according to the `format` specified in the request. All returned coordinates use [WGS 84](https://en.wikipedia.org/wiki/World_Geodetic_System) (sometimes also known as EPSG:4326) as reference coordinate system. Reverse geocoding requests return **at most one single result**. Forward geocoding requests may return multiple results. The response structure will vary slightly depending on: - The optional request parameters specified. - Whether or not you are a subscription customer. Because subscription customer do not face hard limits, their responses do NOT contain the `rate` element. [Details](#rate-body). - The location requested and the information we have available for that location. - Results may not have the `bounds` attribute. This happens when the only data we have available for the location / address is a single latitude, longiitude point. - Reverse geocoding results contain the field `distance_from_q` which is the distance (in meters) to the coordinates in the request to the coordinates of the result. - Read about [how results are ranked](#ranking) when there is more than one forward geocoding result. ### Reverse Geocoding Response Format - JSON - GeoJSON - XML JSON format request for coordinates `-22.6792, 14.5272`. `https://api.opencagedata.com/geocode/v1/json?q=-22.6792%2C+14.5272&key=YOUR-API-KEY&pretty=1` JSON reverse geocoding response: { "documentation" : "https://opencagedata.com/api", "licenses" : [ { "name" : "see attribution guide", "url" : "https://opencagedata.com/credits" } ], "rate" : { "limit" : 10000, "remaining" : 8976, "reset" : 1718841600 }, "results" : [ { "annotations" : { "DMS" : { "lat" : "22\u00b0 40' 45.26256'' S", "lng" : "14\u00b0 31' 37.93728'' E" }, "MGRS" : "33KVQ5143391910", "Maidenhead" : "JG77gh36gx", "Mercator" : { "x" : 1617161.042, "y" : -2576805.433 }, "OSM" : { "edit_url" : "https://www.openstreetmap.org/edit?way=184393212#map=16/-22.67924/14.52720", "note_url" : "https://www.openstreetmap.org/note/new#map=16/-22.67924/14.52720&layers=N", "url" : "https://www.openstreetmap.org/?mlat=-22.67924&mlon=14.52720#map=16/-22.67924/14.52720" }, "UN_M49" : { "regions" : { "AFRICA" : "002", "NA" : "516", "SOUTHERN_AFRICA" : "018", "SUB-SAHARAN_AFRICA" : "202", "WORLD" : "001" }, "statistical_groupings" : [ "LEDC" ] }, "callingcode" : 264, "currency" : { "alternate_symbols" : [ "N$" ], "decimal_mark" : ".", "disambiguate_symbol" : "N$", "format" : "%n %u", "html_entity" : "$", "iso_code" : "NAD", "iso_numeric" : "516", "name" : "Namibian Dollar", "smallest_denomination" : 5, "subunit" : "Cent", "subunit_to_unit" : 100, "symbol" : "$", "symbol_first" : 0, "thousands_separator" : "," }, "flag" : "\ud83c\uddf3\ud83c\udde6", "geohash" : "k7fqfx67u7m1bew3kzh3", "qibla" : 31.02, "roadinfo" : { "drive_on" : "left", "road" : "Woermann Street", "road_type" : "residential", "speed_in" : "km/h" }, "sun" : { "rise" : { "apparent" : 1718775720, "astronomical" : 1718770920, "civil" : 1718774220, "nautical" : 1718772600 }, "set" : { "apparent" : 1718814300, "astronomical" : 1718819100, "civil" : 1718815740, "nautical" : 1718817420 } }, "timezone" : { "name" : "Africa/Windhoek", "now_in_dst" : 0, "offset_sec" : 7200, "offset_string" : "+0200", "short_name" : "CAT" }, "what3words" : { "words" : "outsmarted.cheering.chemical" } }, "bounds" : { "northeast" : { "lat" : -22.6791681, "lng" : 14.5277944 }, "southwest" : { "lat" : -22.6793015, "lng" : 14.5266951 } }, "components" : { "ISO_3166-1_alpha-2" : "NA", "ISO_3166-1_alpha-3" : "NAM", "ISO_3166-2" : [ "NA-ER" ], "_category" : "road", "_normalized_city" : "Swakopmund", "_type" : "road", "city" : "Swakopmund", "continent" : "Africa", "country" : "Namibia", "country_code" : "na", "postcode" : "13001", "road" : "Woermann Street", "road_type" : "residential", "state" : "Erongo Region", "suburb" : "Central" }, "confidence" : 9, "distance_from_q" : { "meters" : 4 }, "formatted" : "Woermann Street, Swakopmund 13001, Namibia", "geometry" : { "lat" : -22.6792396, "lng" : 14.5272048 } } ], "status" : { "code" : 200, "message" : "OK" }, "stay_informed" : { "blog" : "https://blog.opencagedata.com", "mastodon" : "https://en.osm.town/@opencage" }, "thanks" : "For using an OpenCage API", "timestamp" : { "created_http" : "Wed, 19 Jun 2024 11:03:55 GMT", "created_unix" : 1718795035 }, "total_results" : 1 } GeoJSON format request for coordinates `-22.6792, 14.5272`. `https://api.opencagedata.com/geocode/v1/geojson?q=-22.6792%2C+14.5272&key=YOUR-API-KEY&pretty=1` GeoJSON reverse geocoding response: { "documentation" : "https://opencagedata.com/api", "features" : [ { "geometry" : { "coordinates" : [ 14.5272048111108, -22.6792396465822 ], "type" : "Point" }, "properties" : { "annotations" : { "DMS" : { "lat" : "22\u00b0 40' 45.26256'' S", "lng" : "14\u00b0 31' 37.93728'' E" }, "MGRS" : "33KVQ5143391910", "Maidenhead" : "JG77gh36gx", "Mercator" : { "x" : 1617161.042, "y" : -2576805.433 }, "OSM" : { "edit_url" : "https://www.openstreetmap.org/edit?way=184393212#map=17/-22.67924/14.52720", "note_url" : "https://www.openstreetmap.org/note/new#map=17/-22.67924/14.52720&layers=N", "url" : "https://www.openstreetmap.org/?mlat=-22.67924&mlon=14.52720#map=17/-22.67924/14.52720" }, "UN_M49" : { "regions" : { "AFRICA" : "002", "NA" : "516", "SOUTHERN_AFRICA" : "018", "SUB-SAHARAN_AFRICA" : "202", "WORLD" : "001" }, "statistical_groupings" : [ "LEDC" ] }, "callingcode" : 264, "currency" : { "alternate_symbols" : [ "N$" ], "decimal_mark" : ".", "disambiguate_symbol" : "N$", "format" : "%n %u", "html_entity" : "$", "iso_code" : "NAD", "iso_numeric" : "516", "name" : "Namibian Dollar", "smallest_denomination" : 5, "subunit" : "Cent", "subunit_to_unit" : 100, "symbol" : "$", "symbol_first" : 0, "thousands_separator" : "," }, "flag" : "\ud83c\uddf3\ud83c\udde6", "geohash" : "k7fqfx67u7m1bew3kzh3", "qibla" : 31.02, "roadinfo" : { "drive_on" : "left", "road" : "Woermann Street", "road_type" : "residential", "speed_in" : "km/h" }, "sun" : { "rise" : { "apparent" : 1718775720, "astronomical" : 1718770920, "civil" : 1718774220, "nautical" : 1718772600 }, "set" : { "apparent" : 1718814300, "astronomical" : 1718819100, "civil" : 1718815740, "nautical" : 1718817420 } }, "timezone" : { "name" : "Africa/Windhoek", "now_in_dst" : 0, "offset_sec" : 7200, "offset_string" : "+0200", "short_name" : "CAT" }, "what3words" : { "words" : "outsmarted.cheering.chemical" } }, "bounds" : { "northeast" : { "lat" : -22.6791681, "lng" : 14.5277944 }, "southwest" : { "lat" : -22.6793015, "lng" : 14.5266951 } }, "components" : { "ISO_3166-1_alpha-2" : "NA", "ISO_3166-1_alpha-3" : "NAM", "ISO_3166-2" : [ "NA-ER" ], "_category" : "road", "_normalized_city" : "Swakopmund", "_type" : "road", "city" : "Swakopmund", "continent" : "Africa", "country" : "Namibia", "country_code" : "na", "postcode" : "13001", "road" : "Woermann Street", "road_type" : "residential", "state" : "Erongo Region", "suburb" : "Central" }, "confidence" : 9, "formatted" : "Woermann Street, Swakopmund 13001, Namibia" }, "type" : "Feature" } ], "licenses" : [ { "name" : "see attribution guide", "url" : "https://opencagedata.com/credits" } ], "rate" : { "limit" : 10000, "remaining" : 8974, "reset" : 1718841600 }, "status" : { "code" : 200, "message" : "OK" }, "stay_informed" : { "blog" : "https://blog.opencagedata.com", "mastodon" : "https://en.osm.town/@opencage" }, "thanks" : "For using an OpenCage API", "timestamp" : { "created_http" : "Wed, 19 Jun 2024 11:03:56 GMT", "created_unix" : 1718795036 }, "total_results" : 1, "type" : "FeatureCollection" } XML format request for coordinates `-22.6792, 14.5272`. `https://api.opencagedata.com/geocode/v1/xml?q=-22.6792%2C+14.5272&key=YOUR-API-KEY&pretty=1` XML reverse geocoding response: https://opencagedata.com/api see attribution guide https://opencagedata.com/credits 10000 8975 1718841600 22° 40' 45.26256'' S 14° 31' 37.93728'' E 33KVQ5143391910 JG77gh36gx 1617161.042 -2576805.433 https://www.openstreetmap.org/edit?way=184393212#map=17/-22.67924/14.52720 https://www.openstreetmap.org/note/new#map=17/-22.67924/14.52720&layers=N https://www.openstreetmap.org/?mlat=-22.67924&mlon=14.52720#map=17/-22.67924/14.52720 002 516 018 202 001 LEDC 264 N$ . N$ %n %u $ NAD 516 Namibian Dollar 5 Cent 100 $ 0 , 🇳🇦 k7fqfx67u7m1bew3kzh3 31.02 left Woermann Street residential km/h 1718775720 1718770920 1718774220 1718772600 1718814300 1718819100 1718815740 1718817420 Africa/Windhoek 0 7200 +0200 CAT outsmarted.cheering.chemical -22.6791681 14.5277944 -22.6793015 14.5266951 NA NAM NA-ER <_category>road <_normalized_city>Swakopmund <_type>road Swakopmund Africa Namibia na 13001 Woermann Street residential Erongo Region Central 9 4 Woermann Street, Swakopmund 13001, Namibia -22.67923964658221 14.527204811110767 200 OK https://blog.opencagedata.com https://en.osm.town/@opencage For using an OpenCage API Wed, 19 Jun 2024 11:03:56 GMT 1718795036 1 ### Forward Geocoding Response Format - JSON - GeoJSON - XML JSON format request for query `Rua Cafelândia, Carapicuíba, Brasil`. `https://api.opencagedata.com/geocode/v1/json?q=Rua+Cafel%C3%A2ndia%2C+Carapicu%C3%ADba%2C+Brasil&key=YOUR-API-KEY&pretty=1` JSON forward geocoding response: { "documentation" : "https://opencagedata.com/api", "licenses" : [ { "name" : "see attribution guide", "url" : "https://opencagedata.com/credits" } ], "rate" : { "limit" : 10000, "remaining" : 8980, "reset" : 1718841600 }, "results" : [ { "annotations" : { "DMS" : { "lat" : "23\u00b0 32' 13.54632'' S", "lng" : "46\u00b0 50' 9.50460'' W" }, "MGRS" : "23KLP1257795822", "Maidenhead" : "GG66nl91qc", "Mercator" : { "x" : -5213756.721, "y" : -2680044.786 }, "OSM" : { "edit_url" : "https://www.openstreetmap.org/edit?way=185327107#map=17/-23.53710/-46.83597", "note_url" : "https://www.openstreetmap.org/note/new#map=17/-23.53710/-46.83597&layers=N", "url" : "https://www.openstreetmap.org/?mlat=-23.53710&mlon=-46.83597#map=17/-23.53710/-46.83597" }, "UN_M49" : { "regions" : { "AMERICAS" : "019", "BR" : "076", "LATIN_AMERICA" : "419", "SOUTH_AMERICA" : "005", "WORLD" : "001" }, "statistical_groupings" : [ "LEDC" ] }, "callingcode" : 55, "currency" : { "decimal_mark" : ",", "html_entity" : "R$", "iso_code" : "BRL", "iso_numeric" : "986", "name" : "Brazilian Real", "smallest_denomination" : 5, "subunit" : "Centavo", "subunit_to_unit" : 100, "symbol" : "R$", "symbol_first" : 1, "thousands_separator" : "." }, "flag" : "\ud83c\udde7\ud83c\uddf7", "geohash" : "6gydn5pn6xqbjyhsscm7", "qibla" : 69.01, "roadinfo" : { "drive_on" : "right", "road" : "Rua Cafel\u00e2ndia", "road_type" : "residential", "speed_in" : "km/h" }, "sun" : { "rise" : { "apparent" : 1718790540, "astronomical" : 1718785740, "civil" : 1718789100, "nautical" : 1718787360 }, "set" : { "apparent" : 1718828940, "astronomical" : 1718833740, "civil" : 1718830380, "nautical" : 1718832060 } }, "timezone" : { "name" : "America/Sao_Paulo", "now_in_dst" : 0, "offset_sec" : -10800, "offset_string" : "-0300", "short_name" : "BRT" }, "what3words" : { "words" : "reunion.risk.brothers" } }, "bounds" : { "northeast" : { "lat" : -23.5370411, "lng" : -46.835665 }, "southwest" : { "lat" : -23.5373596, "lng" : -46.8374493 } }, "components" : { "ISO_3166-1_alpha-2" : "BR", "ISO_3166-1_alpha-3" : "BRA", "ISO_3166-2" : [ "BR-SP" ], "_category" : "road", "_normalized_city" : "Carapicu\u00edba", "_type" : "road", "city" : "Carapicu\u00edba", "city_district" : "Carapicu\u00edba", "continent" : "South America", "country" : "Brazil", "country_code" : "br", "county" : "Regi\u00e3o Metropolitana de S\u00e3o Paulo", "municipality" : "Regi\u00e3o Imediata de S\u00e3o Paulo", "postcode" : "06386", "region" : "Southeast Region", "road" : "Rua Cafel\u00e2ndia", "road_type" : "residential", "state" : "S\u00e3o Paulo", "state_code" : "SP", "state_district" : "Regi\u00e3o Geogr\u00e1fica Intermedi\u00e1ria de S\u00e3o Paulo", "suburb" : "Parque Jos\u00e9 Alexandre" }, "confidence" : 9, "formatted" : "Rua Cafel\u00e2ndia, Parque Jos\u00e9 Alexandre, Carapicu\u00edba - SP, 06386, Brazil", "geometry" : { "lat" : -23.5370962, "lng" : -46.8359735 } } ], "status" : { "code" : 200, "message" : "OK" }, "stay_informed" : { "blog" : "https://blog.opencagedata.com", "mastodon" : "https://en.osm.town/@opencage" }, "thanks" : "For using an OpenCage API", "timestamp" : { "created_http" : "Wed, 19 Jun 2024 11:03:54 GMT", "created_unix" : 1718795034 }, "total_results" : 1 } GeoJSON format request for query `Rua Cafelândia, Carapicuíba, Brasil`. `https://api.opencagedata.com/geocode/v1/geojson?q=Rua+Cafel%C3%A2ndia%2C+Carapicu%C3%ADba%2C+Brasil&key=YOUR-API-KEY&pretty=1` GeoJSON forward geocoding response: { "documentation" : "https://opencagedata.com/api", "features" : [ { "geometry" : { "coordinates" : [ -46.8359735, -23.5370962 ], "type" : "Point" }, "properties" : { "annotations" : { "DMS" : { "lat" : "23\u00b0 32' 13.54632'' S", "lng" : "46\u00b0 50' 9.50460'' W" }, "MGRS" : "23KLP1257795822", "Maidenhead" : "GG66nl91qc", "Mercator" : { "x" : -5213756.721, "y" : -2680044.786 }, "OSM" : { "edit_url" : "https://www.openstreetmap.org/edit?way=185327107#map=17/-23.53710/-46.83597", "note_url" : "https://www.openstreetmap.org/note/new#map=17/-23.53710/-46.83597&layers=N", "url" : "https://www.openstreetmap.org/?mlat=-23.53710&mlon=-46.83597#map=17/-23.53710/-46.83597" }, "UN_M49" : { "regions" : { "AMERICAS" : "019", "BR" : "076", "LATIN_AMERICA" : "419", "SOUTH_AMERICA" : "005", "WORLD" : "001" }, "statistical_groupings" : [ "LEDC" ] }, "callingcode" : 55, "currency" : { "decimal_mark" : ",", "html_entity" : "R$", "iso_code" : "BRL", "iso_numeric" : "986", "name" : "Brazilian Real", "smallest_denomination" : 5, "subunit" : "Centavo", "subunit_to_unit" : 100, "symbol" : "R$", "symbol_first" : 1, "thousands_separator" : "." }, "flag" : "\ud83c\udde7\ud83c\uddf7", "geohash" : "6gydn5pn6xqbjyhsscm7", "qibla" : 69.01, "roadinfo" : { "drive_on" : "right", "road" : "Rua Cafel\u00e2ndia", "road_type" : "residential", "speed_in" : "km/h" }, "sun" : { "rise" : { "apparent" : 1718790540, "astronomical" : 1718785740, "civil" : 1718789100, "nautical" : 1718787360 }, "set" : { "apparent" : 1718828940, "astronomical" : 1718833740, "civil" : 1718830380, "nautical" : 1718832060 } }, "timezone" : { "name" : "America/Sao_Paulo", "now_in_dst" : 0, "offset_sec" : -10800, "offset_string" : "-0300", "short_name" : "BRT" }, "what3words" : { "words" : "reunion.risk.brothers" } }, "bounds" : { "northeast" : { "lat" : -23.5370411, "lng" : -46.835665 }, "southwest" : { "lat" : -23.5373596, "lng" : -46.8374493 } }, "components" : { "ISO_3166-1_alpha-2" : "BR", "ISO_3166-1_alpha-3" : "BRA", "ISO_3166-2" : [ "BR-SP" ], "_category" : "road", "_normalized_city" : "Carapicu\u00edba", "_type" : "road", "city" : "Carapicu\u00edba", "city_district" : "Carapicu\u00edba", "continent" : "South America", "country" : "Brazil", "country_code" : "br", "county" : "Regi\u00e3o Metropolitana de S\u00e3o Paulo", "municipality" : "Regi\u00e3o Imediata de S\u00e3o Paulo", "postcode" : "06386", "region" : "Southeast Region", "road" : "Rua Cafel\u00e2ndia", "road_type" : "residential", "state" : "S\u00e3o Paulo", "state_code" : "SP", "state_district" : "Regi\u00e3o Geogr\u00e1fica Intermedi\u00e1ria de S\u00e3o Paulo", "suburb" : "Parque Jos\u00e9 Alexandre" }, "confidence" : 9, "formatted" : "Rua Cafel\u00e2ndia, Parque Jos\u00e9 Alexandre, Carapicu\u00edba - SP, 06386, Brazil" }, "type" : "Feature" } ], "licenses" : [ { "name" : "see attribution guide", "url" : "https://opencagedata.com/credits" } ], "rate" : { "limit" : 10000, "remaining" : 8977, "reset" : 1718841600 }, "status" : { "code" : 200, "message" : "OK" }, "stay_informed" : { "blog" : "https://blog.opencagedata.com", "mastodon" : "https://en.osm.town/@opencage" }, "thanks" : "For using an OpenCage API", "timestamp" : { "created_http" : "Wed, 19 Jun 2024 11:03:55 GMT", "created_unix" : 1718795035 }, "total_results" : 1, "type" : "FeatureCollection" } XML format request for query `Rua Cafelândia, Carapicuíba, Brasil`. `https://api.opencagedata.com/geocode/v1/xml?q=Rua+Cafel%C3%A2ndia%2C+Carapicu%C3%ADba%2C+Brasil&key=YOUR-API-KEY&pretty=1` XML forward geocoding response: https://opencagedata.com/api see attribution guide https://opencagedata.com/credits 10000 8979 1718841600 23° 32' 13.54632'' S 46° 50' 9.50460'' W 23KLP1257795822 GG66nl91qc -5213756.721 -2680044.786 https://www.openstreetmap.org/edit?way=185327107#map=17/-23.53710/-46.83597 https://www.openstreetmap.org/note/new#map=17/-23.53710/-46.83597&layers=N https://www.openstreetmap.org/?mlat=-23.53710&mlon=-46.83597#map=17/-23.53710/-46.83597 019
076
419 005 001 LEDC 55 , R$ BRL 986 Brazilian Real 5 Centavo 100 R$ 1 . 🇧🇷 6gydn5pn6xqbjyhsscm7 69.01 right Rua Cafelândia residential km/h 1718790540 1718785740 1718789100 1718787360 1718828940 1718833740 1718830380 1718832060 America/Sao_Paulo 0 -10800 -0300 BRT reunion.risk.brothers -23.5370411 -46.8356650 -23.5373596 -46.8374493 BR BRA BR-SP <_category>road <_normalized_city>Carapicuíba <_type>road Carapicuíba Carapicuíba South America Brazil br Região Metropolitana de São Paulo Região Imediata de São Paulo 06386 Southeast Region Rua Cafelândia residential São Paulo SP Região Geográfica Intermediária de São Paulo Parque José Alexandre 9 Rua Cafelândia, Parque José Alexandre, Carapicuíba - SP, 06386, Brazil -23.5370962 -46.8359735 200 OK https://blog.opencagedata.com https://en.osm.town/@opencage For using an OpenCage API Wed, 19 Jun 2024 11:03:54 GMT 1718795034 1 ## Ranking of Results Reverse geocoding requests return **at most one single result**. Forward geocoding requests may return multiple results. - Results are ordered from most relevant to least. - Results are **NOT** ordered by `confidence` score (see [definition of confidence score](#confidence)). ## Geocoding Confidence The OpenCage geocoding API will always attempt to find a match for as many parts of a query as it can, but this isn't always possible. Where a partial match is made, for example a street name can be matched but not the specific house number, 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](#ranking). 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](#formatted). The confidence score is a value based on the size of the matched place. It is an integer value between `0 ` and ` 10 ` , where ` 0` means we are unable to determine a confidence (due to lack of a bounding box). `1 ` indicates low precision, and ` 10` indicates high precision. Confidence is calculated by measuring the distance between the southwest and northeast corners of each result's bounding box. Then an adjustment may be made to reflect the ambiguity of the underlying geocoder. Confidence is not the way to determine the type of place that was matched, for that please use the `_type` field of the [components portion of the response](#formatted). The best way to think of our confidence score is as a measure of how confident we are that center point coordinates returned for the result precisely reflect the result. For example, if you search for `Berlin, Germany` we know exactly where that is, but it has a confidence of only 2, as Berlin is a very large city ( _ [and Bundesland, but that's another story](https://opencagedata.com/guides/formatting-addresses))._ The coordinates we return are in the center of the bounding box, but it would be valid to consider anywhere in that box to be "Berlin", hence the relatively low confidence score. Geocoding confidence scores and their meaning| `confidence` | **meaning / distance** (in km) | | --- | --- | | `10` | \< 0.25 | | `9` | \< 0.5 0 | | `8` | \< 1 .00 | | `7` | \< 5 .00 | | `6` | \< 7.5 0 | | `5` | \< 10 .00 | | `4` | \< 15 .00 | | `3` | \< 20 .00 | | `2` | \< 25 .00 | | `1` | \> 25 .00 | | `0` | unable to determine a bounding box, thus unable to determine a confidence | ## Ambiguous Results Many places have the same or similar names. When forward geocoding we may find multiple valid matches for a query. In this case we return multiple results ranked by relevance. See [how results are ranked](#ranking). Please see our detailed [guide to understanding geocoding accuracy](https://opencagedata.com/guides/how-to-think-about-geocoding-accuracy) which outlines strategies to determine whether a result from an ambiguous query is sufficiently correct to warrant using or not. Reverse geocoding requests return at most one result. ## No Results In cases where the geocoder cannot find any match for a request, we will return a successful status (a response code of `200`), but the number of results in the response will be zero. You can test this situation by sending a request with the query parameter set to `NOWHERE-INTERESTING` which will return a valid response with 0 results. ## Formatted Placename Each geocoding result has a `formatted ` attribute which contains a version of the location address in the local format. The ` formatted ` string is created from the various values in the ` components` section of the result. [See details](#components). This is the raw data we have to work with. There are several [optional parameters](#optional-params) you can set to influence the content of the `formatted` string: | value | description | | --- | --- | | `abbrv ` | We will attempt to shorten or abbreviate the ` formatted` value. [See details](#abbrv-param). | | `address_only ` | We will attempt to exclude POI names from the ` formatted` value. [See details](#address_only-param). | | `language` | Specify your preferred output language. [See details](#language). | **Background:** Across the world there are _many_ different ways to format addresses and place names. For more on the need for, and challenge of, good formatting please read our [guide to address formatting](https://opencagedata.com/guides/formatting-addresses). ## Address Components We provide the individual pieces of the location hierarchy in the `components` portion of the result. ### Common questions / misunderstandings - We are often asked if there is a definitive list of all possible `components` keys. Unfortunately not - [read why not](https://opencagedata.com/faq#formatted). - Please do not assume every location will always have a `city` value (or any of the other values). The world is a very diverse place, different countries (or regions within countries) do things very differently. Code defensively. ### Details of specific key/values | key | description | | --- | --- | | `continent` | Possible values are: `Africa, Antarctica, Asia, Europe, Oceania, North America, South America` | | `_type ` | We provide the key ` _type` with the value set to what we believe the matched location to be. Note: - In the rare case where, for whatever reason, we can't determine a `_type ` we set the value ` unknown`. - Common possible values of `_type` include: `building, road, place, hamlet, village, neighbourhood, city, county, postcode, partial_postcode, terminated_postcode, postal_city, state_district, state, region, island, body_of_water, country, continent, fictitious, unknown` - Just because a result has a certain `_type ` does NOT mean there is a key of that value in the ` components ` list. Various types get mapped together. As an example ` town ` gets mapped to ` _type : city`. See [the list of mappings](https://github.com/OpenCageData/address-formatting/blob/master/conf/components.yaml). - It is not a good idea to use the `_type ` as a proxy for the geographic size of the result. Different places can have the same ` _type ` (for example ` village ` or ` city ` or ` postcode `), but vary in size. Instead use the [` confidence`](#confidence) score, which is a measure of size. | | `_normalized_city ` | The definition of what is a ` city ` or ` town` or other type of settlement can vary widely between and even within countries. To address this issue we try to provide the key `_normalized_city `. The value is set by looking through the values of ` city, town, township, village, municipality, neighbourhood, suburb, city_district, ...` in descending order. | | `_category ` | We set a ` _category ` based on mapping the value of ` _type`. See the list of [possible values](https://github.com/OpenCageData/opencagedata-misc-docs/blob/master/category_values.md). | | `road `, ` road_type` | - If the result is a road - ie if `_type ` has value ` road ` - then if possible we also return a ` road_type` key with values like those [generally used in OpenStreetMap](https://wiki.openstreetmap.org/wiki/Key:highway). - If the road does not have a name we set the value to `unnamed road`. Read our blog post about [why a road may not have a name](https://blog.opencagedata.com/post/where-the-streets-have-no-name). Please read the details of [getting more road / driving information](#roadinfo). For example speed limits, etc. | | ISO 3166 codes, `country_code`, `county_code`, `state_code` | When possible we set values for the following key/values: `country_code, county_code, ISO_3166-1_alpha-2, ISO_3166-1_alpha-3, ISO_3166-2, state_code` Note: - `country_code ` is a lower-case two-letter code. Examples: ` de ` for Germany, ` mx` for Mexico. - For historical reasons many territories have their own ISO 3116-1 codes, despite being part of another country, and for this reason the value of `country_code ` can differ from the value of ` ISO_3166-1_alpha-2`. Example: Puerto Rico (part of the United States) has an `ISO_3166-1_alpha-2 ` value of ` PR `, and a ` country_code ` value of ` us`. - Some territories do not have official ISO 3166-1 codes. In this case we set only `country_code`. Specifically, we set: - `xc` for the Sovereign Base Areas of Akrotiri and Dhekelia - `xk` for Kosovo - The value for the key `ISO_3166-2` is a list as some countries (examples: France, Italy, Spain, and the United Kingdom) have multiple ISO 3166-2 values for a given location. The codes are ordered from least to most specific. Example: the coordinates `51.5244, -0.0997 ` have an ` ISO_3166-2` value of `[GB-ENG, GB-ISL]`. Note: many smaller countries do not have ISO 3166-2 codes, as they do not have second-level administrative divisions. - In some countries commonly used state abbreviations differ from `ISO_3166-2` values. This is especially the case when the ISO codes are numeric. Example: Umbria is a region (state) in central Italy. It has an `ISO_3166-1_alpha-2 ` value of ` IT-55 `, but is commonly abbreviated as ` UMB `, which is what we return as the value of ` state_code`. - Some countries, for example the Republic of Ireland and Norway, use "county" as their second-level administrative division, not state (or province, etc). In this case there will not be a `state ` field. We will attempt to set a ` county_code` value, if such values are commonly used (they are in the Republic of Ireland, they are not in Norway). - For more background on ISO codes please read our [guide to determining the ISO codes for a location](https://opencagedata.com/guides/how-to-determine-the-iso-codes-for-a-location). | ## Polygons / Geometries / Boundaries Occasionally we are asked if the API can return the exact polygon (often called the geometry or boundary) for an area. When possible we return a bounding box in the in the `bounds` portion of the result. We use this bounding box to calculate the result's [confidence score](https://opencagedata.com/api#confidence). But we do not return exact polygons, for a few reasons. First of all, it is just not something many customers need. Secondly, we aggregate many different geocoders, and while some have some polygons in their underlying data, some do not, or have only partial coverage. Finally, polygons can be absolutely massive in terms of data size. Returning such a large amount of data would present some meaningful operational challenges for a high-volume API. We recommend looking at [Boundaries-API](https://boundaries-api.io) if you need administrative boundaries. ## Permanent Identifiers The API does NOT return a unique permanent identifier for each result. Please read [our guide to the topic of permanent location ids](https://opencagedata.com/guides/permanent-location-ids) to understand why not. Nevertheless, depending on the location, in the `annotations` portion of the each result we may return various commonly used codes or location reference schemes that refer to different levels of granularity. ## Annotations / Data Enrichment By default each result contains an `annotations` section which supplies additional information about the result location. Annotations can be turned off by setting the optional `no_annotations ` parameter (with the exception of ` roadinfo ` and ` UN/LOCODE`, please see below for details), and we recommend you do so if you don't need this information as it means we can respond to your query a tiny bit more quickly. Please note: - The annotations reflect information derived based on **the coordinates of the result**. These may differ from the coordinates of the request. Reverse geocoding results include the field `distance_from_q` which is the distance (in meters) to the coordinates in the request to the coordinates of the result. - Some annotations are resource intensive, it isn't viable to have them on by default for everyone, instead they are only available to paying customers and need to be specifically enabled for the customer account. These annotations are marked below. - Some annotations, for example `currency`, depend on the coordinates being in a country. These annotations will not be supplied for results that do not lie inside the boundaries of any country, for example in the middle of an ocean. - The information in the annotations may come from different sources of variable coverage. We do the best we can, but please don't assume we will always be able to provide the same level of information everywhere. We provide the following annotations: | key | description | | --- | --- | | `callingcode` | The international [telephone calling code](https://en.wikipedia.org/wiki/List_of_country_calling_codes) for the country of the result. Example: `49` | | `currency` | Information about the local currency Example: "currency": { "alternate_symbols": [ ], "decimal_mark": ",", "html_entity": "€", "iso_code": "EUR", "iso_numeric": "978", "name": "Euro", "smallest_denomination": 1, "subunit": "Cent", "subunit_to_unit": 100, "symbol": "€", "symbol_first": 0, "thousands_separator": "." } | | `DIGIPIN` | If the location is in the bounding box of India (as defined by India Post, [see bounding box](https://opencagedata.com/tools/bounds-finder#63.50000,2.50000,99.50000,38.50000)) contains the DIGIPIN - a unique 10-character alphanumeric code (12 chars when the two dashes are included) based on the 4m x 4m grid that the location falls into. [Learn more about DIGPIN](https://www.indiapost.gov.in/vas/Pages/digipin.aspx). Example: `32C-849-5CJM` | | `DMS` | Contains the latitude and longitude of the center point of the result in degree minute decimal second format. Example: `{ "lat": "52° 32' 35.65644'' N", "lng": "13° 24' 51.16788'' E" }` | | `FIPS ` | Contains the [US Federal Information Processing Standards (FIPS) code](https://en.wikipedia.org/wiki/FIPS_county_code) for the ` state ` (two digit) and ` county` (five digit) of the center point of the result, if we can determine it. Example: `{ "county": "08101", "state": "08" }` Note: - Only for locations in the United States and associated territories. - The values are strings - not numbers - and can have leading zeros. | | `flag` | Emoji flag of the country of the result. Example: `🇩🇪` | | `geohash` | Contains a [geohash](https://en.wikipedia.org/wiki/Geohash) for the center point of the result. Example: `u33dcjpytc6quc1v978v` | | `H3` | Contains an [H3 reference](https://h3geo.org) for the center point of the result. **Note:** This annotation is only available to paying customers and by request. Example: `861f11587ffffff` H3 is an open source hexagonal hierarchical geospatial indexing system originally invented at Uber. [Read more about H3](https://eng.uber.com/h3/). | | `ITM` | Contains the Irish Transverse Mercator `easting ` and ` northing` of the center point of the result. Example: `{ "easting": "465792.658", "northing": "750564.188" }` This annotation is applied only for locations in Ireland. Learn more about [ITM](https://en.wikipedia.org/wiki/Irish_Transverse_Mercator). | | `Maidenhead` | contains a [Maidenhead location reference](https://en.wikipedia.org/wiki/Maidenhead_Locator_System) for the center point of the result. Example: `JO62qn90qj` | | `Mercator ` | contains the [Mercator projection](https://en.wikipedia.org/wiki/Mercator_projection) (EPSG:41001, sometimes also referred to as "Simple Mercator") ` x` and `y` unit meter values of the center point of the result. Example: `{ "x": 1493263.394, "y": 6865010.468 }` Note: use of Mercator projection on latitudes above/below +70/-70 degrees is strongly discouraged, due to the gross distortions of the projection. | | `MGRS` | The [Military Grid Reference System](https://en.wikipedia.org/wiki/Military_grid_reference_system) code for the center point of the result. WGS84 datum. Example: `33UUU9246122642` | | `NUTS` | contains the relevant European Union [Nomenclature of Territorial Units for Statistics (NUTS)](https://en.wikipedia.org/wiki/Nomenclature_of_Territorial_Units_for_Statistics) codes for the location. Note: - - We do not support Local Administrative Units (LAUs), the level below NUTS 3. We may add those in the future. - Our codes are based on the 2024 definitions, with the exception of GB which continues to use the old definitions from when GB was part of the EU. - We use maritime borders, not land borders. - Please see our [guide to finding the NUTS code for a location](https://opencagedata.com/guides/how-to-find-the-nuts-codes-for-an-address-or-coordinates). Example: "NUTS": { "NUTS0" : { "code" : "ES" }, "NUTS1" : { "code" : "ES5" }, "NUTS2" : { "code" : "ES51" }, "NUTS3" : { "code" : "ES511" } }, | | `OSM` | Contains: | key | description | | --- | --- | | `url` | URL for viewing the location on openstreetmap.org | | `note_url` | URL for adding a "note" about the location on openstreetmap.org | May also contain: | key | description | | --- | --- | | `edit_url` | URL for editing the result on openstreetmap.org. | Note: you may need to zoom in or out to edit and in doing so focus may shift to a different element. Our tutorial on [how to add an address to OpenStreetMap](https://opencagedata.com/tutorials/adding-an-address-to-openstreetmap) may be helpful. | | `qibla` | Decimal degrees clockwise from true north to turn to point to the Kaaba (21.4225, 39.8262). Example: `136.72` Calculated using the great circle method. [More background on Qibla](https://en.wikipedia.org/wiki/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: | key | description | | --- | --- | | `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 | key | description | | --- | --- | | `road` | name of the road | | `road_type` | with values like those [generally used in OpenStreetMap](https://wiki.openstreetmap.org/wiki/Key:highway) | | `road_reference ` | road identifier, example: ` A 38 `, ` AP-7 `, ` 3356` | | `road_reference_intl ` | international road identifier, example: ` E 15` | If the optional `roadinfo` parameter was specified we will also attempt to set the following values about the road: | key | description | | --- | --- | | `lanes` | number of lanes | | `maxheight ` | either ` default `, ` below default `, or a number representing the height in meters, for example: ` 3.5` | | `maxspeed ` | (speed limit). An integer value like ` 30 `, or ` none` if there is no speed limit. Please bear in mind this is crowd-sourced data and not official governmental data. See note below. | | `maxweight ` | in metric tons, for example: ` 3.5` | | `maxwidth ` | in meters, for example: ` 7.5` | | `oneway ` | value of ` yes ` or ` no` | | `surface` | physical surface of road, values like those [generally in OpenStreetMap](https://wiki.openstreetmap.org/wiki/Key:surface) | | `toll ` | value of ` yes` if we know this is a toll road, otherwise this key is not set | | `toll_details` | additional information about the toll, if available. Potentially contains the following fields: - `excluded` a list of vehicle/transport types excluded from the toll - `included` a list of vehicle/transport types included in the toll - for the case where a road is free for most vehicles but some types pay a toll - `operator` the name of the toll operator Potential vehicle/transport types are: `bicycle, bus, disabled, foot, hgv, hov, motor_vehicle, motorcycle, N2, N3` | | `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](#roadinfo). Example (without `roadinfo` set) "roadinfo": { "drive_on": "right", "road" : "Autostrada Wolno\u015bci", "road_reference" : "A2", "road_reference_intl" : "E 30", "road_type" : "motorway", "speed_in": "km/h" } Example (with `roadinfo` set) "roadinfo" : { "drive_on" : "right", "lanes" : 2, "maxspeed" : 140, "oneway" : "yes", "road" : "Autostrada Wolno\u015bci", "road_reference" : "A2", "road_reference_intl" : "E 30", "road_type" : "motorway", "speed_in" : "km/h", "surface" : "asphalt", "toll" : "yes", "toll_details" : { "included" : [ "bus", "hgv" ], "operator": "Krajowa Administracja Skarbowa" }, "width" : "7.5" } | | `sun ` | Contains two keys: ` rise ` and ` set`, each of which in turn contains four keys: | key | description | | --- | --- | | `apparent` | what is typically reported as sunrise/set | | `astronomical` | sky is completely dark/light | | `civil` | a person can read / no longer read | | `nautical` | navigation using a sea horizon possible/no longer possible | with Unix timestamps as values corresponding to the four different types of sunrise/set. Example: "sun": { "rise" : { "apparent" : 1739773140, "astronomical" : 1739766300, "civil" : 1739771040, "nautical" : 1739768640 }, "set" : { "apparent" : 1739809320, "astronomical" : 1739816220, "civil" : 1739811420, "nautical" : 1739813820 } } A value of 0 means the sun never rises/sets on that day (equivalent to 00:00-23:59), e.g. during midsummer. | | `timezone` | Information about the time zone of the location. Consists of the following keys `name `, ` now_in_dst `, ` offset_sec `, ` offset_string `, ` short_name`. Example: "timezone" : { "name": "Europe/Berlin", "now_in_dst": 0, "offset_sec": 3600, "offset_string": "+0100", "short_name": "CET" }, When the result is in a country the value of `name ` will be of the form ` Continent/City `, the format used by [tz database](https://en.wikipedia.org/wiki/Tz_database) on \*nix-based 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](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). | | `UN/LOCODE` | Contains UN/LOCODE information. Please read the [detailed background, including caveats](#unlocode). **Note:** This annotation is set for specific UN/LOCODE forward geocoding queries (even if `no_annotations=1` is set), and as a general annotation for all geocoding results near a UN/LOCODE location. The general annotation case is however only available to paying customers and by request, with one exception: it is turned on for all locations in Luxembourg so that you can see it before purchasing. If you are a customer, and would like the annotation turned on please [contact us](https://opencagedata.com/contact). Example (for code `DEBRV`) "UN/LOCODE" : { "code" : "DEBRV", "date" : "9501", "function" : { "meaning" : [ "port", "rail terminal", "road terminal", "airport" ], "raw" : "1234----" }, "lat" : 53.5505392, "lng" : 8.5851945, "name" : "Bremerhaven", "name_wo_diacritics" : "Bremerhaven" }, | | `UN_M49` | Contains the relevant [United Nations M49 codes](https://unstats.un.org/unsd/methodology/m49/) for the location. Consists of two keys: `regions ` and ` statistical_groupings`. - `regions` contains keys 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. See [a list of all possible regions and the corresponding codes](https://github.com/OpenCageData/opencagedata-misc-docs/blob/master/UN-M49-regions.md). - `statistical_groupings` contains a list of abbreviations of various country groupings commonly used in statistical analysis. Example (for a location in Haiti) "UN_M49": { "regions": { "AMERICAS": "019", "CARIBBEAN": "029", "HT": "332", "LATIN_AMERICA": "419", "WORLD": "001" }, "statistical_groupings": [ "LDC", "LEDC", "SIDS" ] }, Learn more about [the UN M49 standard on Wikipedia](https://en.wikipedia.org/wiki/UN_M49). | | `what3words` | Contains a key `words` whose value is a 3 words address (3wa). Example: `{ "words": "cookies.appeal.liberty" }` By default the words returned are in English, but if the query contained the optional `language` parameter specifying one of the following languages: `af,am,ar,bg,bn,cs,cy,da,de,el` `en,es,fa,fi,fr,gu,he,hi,hu,id` `it,ja,kn,ko,ml,mn,mr,ms,ne,nl` `no,or,pa,pl,pt,ro,ru,sk,sv,sw` `ta,te,th,tr,uk,ur,vi,xh,zh,zu` the 3wa will be in that language. Learn more about [what3words](https://what3words.com) and their location naming scheme. | | `wikidata` | Wikidata item for the location. Example: `Q1534213` A Wikidata item is a unique identifier used by the Wikimedia Foundation and others. [Learn more about Wikidata](https://en.wikipedia.org/wiki/Wikidata). | ## Operational Status You can always check [`status.opencagedata.com`](https://status.opencagedata.com) to see our current operational status as measured by independent, third-party monitoring. In the event of network or other operational issues we will keep you informed via [the OpenCage Mastodon account](https://en.osm.town/@opencage). [![Screenshot of the OpenCage status page](https://assets.opencagedata.com/assets/statuspage-screenshot-1bc72782682606fe46655aed90f304e17e981c5211ba9c0a34da938e738592e2.png "OpenCage status page") ](https://status.opencagedata.com) _The OpenCage status page_ At the start of each year we publish a [blog post reporting the uptime of the prior year](https://blog.opencagedata.com/tagged/uptime). ## Best Practices **General advice:** - Save yourself a lot of time by not reinventing the wheel. Use one of [the many libraries](https://opencagedata.com/sdks) that already exist for accessing our API. - If you do not need the information provided in the annotations please set `no_annotations=1`. This enables us to do less work and significantly reduces the response size and thus reply more quickly. In our [guide to geocoding more quickly](https://opencagedata.com/guides/how-to-geocode-more-quickly) we outline a few more strategies for speed. - If you are geocoding non-English locations, please don't forget to set the optional `language` parameter - [see details](#language). - Program defensively. We are aggregating data from many rapidly-changing data sources. While we make every effort to clean things up, your code should be as forgiving as possible. - If you are geocoding any significant volume, please read our [guide to geocoding large datasets](https://opencagedata.com/guides/how-to-geocode-large-datasets). - Changes to the API are very rare, but if you are depending on our service please "watch" [our public Change Log on GitHub](https://github.com/OpenCageData/opencagedata-misc-docs/blob/master/CHANGES.md), so you are notified when we announce any changes. **When forward geocoding:** - It helps us greatly is you can format your query well. Please see our detailed guide on [how to format your forward geocoding query](https://opencagedata.com/guides/how-to-format-your-geocoding-query). - We are much more likely to give you a correct answer if you are able to use the `bounds ` and/or ` countrycode` parameters as this lets us route the search better and narrow the results considerably. - We may return multiple relevant results. Please see our [guide to understanding geocoding accuracy](https://opencagedata.com/guides/how-to-think-about-geocoding-accuracy) to learn strategies for deciding which result is the one you want. - If the request comes from a mobile device whose location you know or a user viewing a map please consider using the optional `proximity` parameter to bias results to the user's location or the location the user is viewing. ## Working with AI / LLMs Many developers use generative AI tools like Claude, Copilot, Gemini, ChatGPT, etc to speed up their coding. To help enable this way of integrating our geocoding API: - We offer an [Agent Skill](https://github.com/OpenCageData/opencage-skills/) to make it easy for AI to quickly learn about our geocoding API. - You can [access this documentation as Markdown](https://opencagedata.com/api.md) so your AI tools can more easily consume it. - Likewise you may find it helpful to feed the AI a Markdown formatted version of [our tutorials](https://opencagedata.com/tutorials) for a specific programming language. On each page at the top you will find a dropdown with the options to view or copy the page as markdown for easy pasting into an LLM. ![Screenshot of the "View as markdown" option](https://assets.opencagedata.com/assets/view-as-markdown-c9acb8ad52ab8fa62c45e228b5a585eaf981684ecb6fce9a4d29b2b15aca0677.png "Screenshot of the "View as markdown" option") _The "view as markdown" option at the top of a tutorial._ Or you can simply append `.md` to the URL of any tutorial page to get the Markdown version. For example: [`https://opencagedata.com/tutorials/geocode-in-python.md`](https://opencagedata.com/tutorials/geocode-in-python.md) is the URL of our python tutorial in Markdown format - We offer an MCP (Model Context Protocol) server for geocoding within an LLM. [Read our MCP tutorial](https://opencagedata.com/tutorials/geocode-in-mcp). You may wonder why you need a geocoding API at all, why not just have AI do the geocoding? We cover [this exact question in our guide to comparing geocoding services](https://opencagedata.com/guides/how-to-compare-and-test-geocoding-services#whataboutai). ## Troubleshooting / Common Issues - Make sure you have connectivity and can connect to our API. As a test, you can try making a request to the `/ping` endpoint, for example using curl: curl https://api.opencagedata.com/ping You should get the response "pong", as you [can see here.](https://api.opencagedata.com/ping) If not, there is a problem with your connection. - If you aren't getting the response you expected from an API request please look at the `status ` field of the response. It contains two fields: ` code ` and ` message`. Please look at [what the various response codes mean](#codes). We do our best to tell you what the problem is. Sometimes developers assume the problem is X when really it is Y. - - Please follow [the best practices](#bestpractices), especially our advice on [formatting your query](https://opencagedata.com/guides/how-to-format-your-geocoding-query). - Unless you use case is truly exotic, we recommend you use one of [the many SDKs](https://opencagedata.com/sdks) to help avoid basic errors (and save your time). - Nevertheless, sometimes an SDK can obscure what is actually happening. [Our demo page](https://opencagedata.com/demo) is a good tool for quickly playing with the API and seeing actual requests and responses. - We have detailed [guides to common geocoding questions](https://opencagedata.com/guides) like [how to geocode more quickly](https://opencagedata.com/guides/how-to-geocode-more-quickly) or [how to show geocoding results on a map](https://opencagedata.com/guides/how-to-display-geocoding-results-on-a-map). Please have a look. - Please don't hesitate to [get in touch](https://opencagedata.com/contact#technicalgc) with questions. ## Privacy In using the OpenCage geocoding API you are sending us location data. We have no ability or desire to link locations with individuals. Nevertheless, any time you are transferring data it makes sense to consider the privacy implications. - We are a European (German) legal entity, and thus fully bound by the EU's General Data Protection Regulation (GDPR). Please find all details of our compliance with GDPR in [our privacy policy](https://opencagedata.com/gdpr). Likewise, we also have a page [discussing our HIPAA compliance](https://opencagedata.com/hipaa). - As a reassurance for any users of the API with privacy concerns, we provide the optional `no_record` parameter. [See details](#no_record-param). When this parameter is set we keep no record of your query. - Our geocoding API attempts to geocode to the most precise level possible. There are use cases where exposing a full address or precise location may pose a privacy risk. This will necessarily depend on how exactly you are using location data in your application. Nevertheless, we provide the following guide to [how to create an imprecise location description to preserve privacy](https://opencagedata.com/guides/how-to-preserve-privacy-by-showing-only-an-imprecise-location). Please be responsible in your use of location data. - Free trial accounts are deleted after three months of inactivity, after which we have no record of the account. You can also delete your account sooner anytime you like in your account dashboard. If you have any questions about our approach to privacy or data protection, please don't hesitate to [get in touch](https://opencagedata.com/contact). ## Fuzzy matching / Autosuggest Our geocoding API is designed for geocoding, and does NOT perform "fuzzy" matching. As an example, a request with query `par ` will NOT return ` Paris, France` as a result. If you want location "autosuggest", "autocomplete" or "type ahead", what you want is our [geosearch](https://opencagedata.com/geosearch) service. Many people confuse forward geocoding with geosearch. Forward geocoding expects an address or placename as an input, and returns location information (coordinates, etc). Geosearch takes any string of text as input and tries to expand the string, and return a list of possible placename matches. For more background please see our guide explaining [the differences between geocoding and geosearch](https://opencagedata.com/guides/the-difference-between-geocoding-and-geosearch). ## Caching Feel free to cache, or store, results as long as you like, you know your use case and whether or not it makes sense. This applies whether you are on our free-trial, or you have become a paying customer, and even after you stop being a customer. Unlike many geocoding services we do not have different pricing tiers for "temporary" and "permanent" data storage. All data returns by the API can be stored permanently. That said, the world is a constantly changing place and the underlying datasets, like OpenStreetMap, that we're querying are always evolving, so it may make sense to refresh your cache regularly. For ease of caching every response has a `timestamp ` section with both a human readable HTTP timestamp - in the ` created_http ` key, and a Unix timestamp - in the ` created_unix` key. Customers often ask us when it makes sense to cache, and what to use as the cache key. For forward geocoding you can use a normalized version of the query. 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. Our experience is that caching can make 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 is useful for you largely depends on your specific 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 [guide to geocoding more quickly](https://opencagedata.com/guides/how-to-geocode-more-quickly) where we outline strategies to optimize for speed. ## Language Many places have different names in different languages. To tell us you favour results in a specific language use the optional `language ` parameter, otherwise we will default to the language of your browser or, if no browser language is specified, English. [Please see the ` language` parameter documentation](#language-param) for a detailed explanation of how we determine which language to favour. We rely on many different datasets. Some, like OpenStreetMap, tend to have results in many languages. Others tend to have results only in English. Specifying `language` does not mean we will return results purely in that language, only that we will do our best to favour such results if we have them. If you specify `language=native ` we will attempt to return results in the local language. As an example, instead of ` Munich ` you will receive ` München`. Please be aware that the geocoders we build upon typically use the "official" language of the country, which may not actually be the language spoken locally. Also, many countries have multiple "official" languages. As an example, instead of returning `Belgium ` as we would for a request with ` language=en ` we would return ` België / Belgique / Belgien ` for a request with ` language=native`. ## Nearest Road / Speed Limit Information Many of our clients use our service for vehicle or fleet tracking, and are interested in information about the roads the vehicles are travelling on. To simplify this use case we offer the optional parameter `roadinfo `. Setting this optional parameter (adding ` roadinfo=1` to your request) has a few implications: - - We will add the `roadinfo ` annotation to the response, regardless of whether the optional parameter ` no_annotations` is set or not. Please see [the roadinfo annotation](#roadinfoann) documentation for the exact list of fields we attempt to return. Please note: - Many roads in rural areas don't (yet) have names, or they may not yet be named in the data sources we have available. In this case we set the name of the road to be `unnamed road`. Read our blog post about [why a road may not have a name](https://blog.opencagedata.com/post/where-the-streets-have-no-name). - The information we return comes from crowdsourced databases like OpenStreetMap. It should NOT be taken as official governmental data. It may be out of date or simply wrong, and especially the speed limit in the `maxspeed` key may have many caveats, for example different speed limits depending on time of day, time of year, weather conditions, type of vehicle, etc. The results are provided for informational purposes only and common sense should always be used. **Always drive safely**. ## UN/LOCODE UN/LOCODE (officially the _United Nations Code for Trade and Transport Locations_) is a system of codes developed and maintained by the United Nations. The codes are commonly used in logistics. The codes are five characters in length with the first two characters corresponding to the ISO 3166-1 alpha-2 code of the country of the location. For example the code `DEBRV` represents the German port of Bremerhaven. There are currently over 116,000 UN/LOCODEs (the list is updated twice a year), and they provide an unambiguous and simple way for all parties in the supply chain to refer to locations. Learn more about [UN/LOCODE on Wikipedia](https://en.wikipedia.org/wiki/UN/LOCODE). We provide information about UN/LOCODEs in two ways: - You can search for a specific UN/LOCODE by specifying the code as a geocoding query, prefixed by "LOCODE:" For example if you make the request `q=LOCODE:DEBRV`. Please see our [guide to searching for UN/LOCODEs](https://opencagedata.com/guides/lookup-a-unlocode). We return the information we have about the requested code in the `UN/LOCODE ` annotation, regardless of whether the optional parameter ` no_annotations` is set or not. - For geocoding API results that are near a UN/LOCODE location we return UN/LOCODE information as an annotation. **Note:** this annotation is only available to paying customers and by request. So that you can see it before becoming a customer we have turned it on for everyone for all locations in the country of Luxembourg. You can test by doing a request for the coordinates `49.4716, 6.3659 ` which will return information about the code ` LUSCH`. If you are a customer, and would like the annotation turned on please [contact us](https://opencagedata.com/contact). See [the UN/LOCODE annotation](#unlocodeann) documentation for an example of the exact structure of the information we return. Please note one critical caveat: the official UN/LOCODE data is minimal and the quality of that data is highly variable. In the best case the codes have only a single coordinate point. About 2% of codes do not have coordinates at all, and we can not determine a location for them, and thus we are unable to work with them. A few codes have obviously wrong coordinates such as `0,0` and thus are also discarded. As always we do the best we can with the data available to us. ## Libraries/SDKs, Tutorials, and Recipes Don't waste your time reinventing the wheel. There are open-source [SDKs for accessing the OpenCage geocoding API](https://opencagedata.com/sdks) for over 40 different programming languages and frameworks, including [java](https://opencagedata.com/tutorials/geocode-in-java), [nodejs](https://opencagedata.com/tutorials/geocode-in-nodejs), [PHP](https://opencagedata.com/tutorials/geocode-in-php), [python](https://opencagedata.com/tutorials/geocode-in-python), [ruby](https://opencagedata.com/tutorials/geocode-in-ruby), and [many more](https://opencagedata.com/sdks). If you prefer to learn by watching a video we have those as well [over on YouTube](https://www.youtube.com/@OpenCageGeocoding), demonstrating how to access the API using our Python module, but the concepts are the same in all languages. [![Screenshot of an OpenCage tutorial video on YouTube](https://assets.opencagedata.com/assets/video-tutorial-reverse-a2ef0900c8a8cecadf8189fbf5c5ddfc5f0016fd1c40206af68a545ef48a2448.png "OpenCage reverse geocoding tutorial video") ](https://www.youtube.com/watch?v=u-kkE4yA-z0) _Screenshot of an OpenCage tutorial video on YouTube_ Some developers prefer to use API examination tools. We have step by step guides for [accessing our API in Bruno](https://opencagedata.com/tutorials/geocode-in-bruno), [Postman](https://opencagedata.com/tutorials/geocode-in-postman), and [Insomnia](https://opencagedata.com/tutorials/geocode-in-insomnia). You can of course also use the API directly [from the command line](https://opencagedata.com/tutorials/geocode-commandline). We also have a list of [recipes for common use cases](https://opencagedata.com/guides#recipes), for example: - [Displaying geocoding results on a map](https://opencagedata.com/guides/how-to-display-geocoding-results-on-a-map) - [Geocoding image coordinates](https://opencagedata.com/guides/how-to-geocode-images) - [Determining the ISO codes for a location](https://opencagedata.com/guides/how-to-determine-the-iso-codes-for-a-location) ## Batch or Bulk Geocoding We are sometimes asked if the geocoding API supports sending more than one location per request, sometimes referred to as "batch" or "bulk" geocoding. We allow manual [uploading of a spreadsheet](#uploads) which we geocode row by row, but the API itself does not allow multiple locations per request. If you need to geocode many locations quickly the way to do so is by sending requests in parallel. We have customers making many millions of API requests per day, it works well. We intentionally don’t support more than one location per API request as our experience is that the conceptually much simpler **"one location, one request"** model is much less likely to lead to misunderstandings or errors of implementation, thus saving engineering time, which is the most valuable resource for almost all of our customers. Our entire goal is simplicity and ease of use. **Requesting in parallel:** - Please read our [guide to geocoding large datasets where we explain various strategies and points to consider.](https://opencagedata.com/guides/how-to-geocode-large-datasets) - We have a [command line tool for geocoding large CSV files](https://opencagedata.com/tutorials/geocode-in-cli) - Don't re-invent the wheel. Our [Node.js](https://opencagedata.com/tutorials/geocode-in-nodejs#parallel), [PHP](https://opencagedata.com/tutorials/geocode-in-php#parallel), [Python](https://opencagedata.com/tutorials/geocode-in-python#parallel), and [Ruby](https://opencagedata.com/tutorials/geocode-in-ruby#parallel) tutorials all have sections with example scripts showing how to make many requests in parallel. ## Spreadsheet Uploads In [your account dashboard](https://opencagedata.com/dashboard#uploads) you can upload a spreadsheet which we will geocode row by row. ![Spreadsheet geocoding example](https://assets.opencagedata.com/assets/uploads_ex1a-c05a50f01315631c9c05450dc959a82d81d39bb9b52daebcfe246be7ff6d6305.png "Spreadsheet geocoding example") _Example of a spreadsheet prepared for geocoding_ Learn more in [our detailed spreadsheet geocoding tutorial](https://opencagedata.com/tutorials/geocode-in-uploads). **Technical details:** - We support the following file types: .csv, .ods, .tsv, .txt, .xls, .xlsx - Please see our guide to [formatting your spreadsheet](https://opencagedata.com/guides/how-to-prepare-your-spreadsheet-for-geocoding). - Free trial users are limited to spreadsheets with 100 rows. - Paying customers can upload much larger files. Each row to be geocoded is counted as one geocoding API request. - Uploaded spreadsheets or CSV files are automatically deleted after: - 3 days for free trial users - 30 days for paying customers ## IP restriction Subscription customers can define a list of IP addresses that are allowed to use their API key. All requests with that API key that come from non-allowed IP numbers will receive a `403 - IP address rejected` response. Customers can add or delete IP addresses in their account dashboard (in the "Geocoding API" tab in your account dashboard click on the "settings" button next to the API key). **Changes to API key settings take approximately 10 minutes to take effect as they are distributed out to all of our servers.** ## CORS If you are accessing the geocoding API from client side javascript in a browser please be aware that by default the OpenCage Geocoding API allows all origins for Cross-Origin Resource Sharing (CORS). Geosearch Please note, if you want location "autosuggest", "autocomplete" or "type ahead", what you want is our [geosearch](https://opencagedata.com/geosearch) service, not our geocoding API. By default the geocoding API response includes the HTTP header `access-control-allow-origin: *` which thus allows all cross-origin requests. If you are a subscription customer, you can change this by defining a domain per API key in your account dashboard (in the "Geocoding API" tab in your account dashboard click on the "settings" button next to the API key). **Changes to API key settings take approximately 10 minutes to take effect as they are distributed out to all of our servers.** Once set, we will then return: `access-control-allow-origin: https://some-customer-defined-domain.com` which will thus restrict AJAX requests to the specified domain. It is important to note this does nothing to prevent someone from making an API request with your key, it just makes AJAX requests from within a browser stop working. Please see our detailed [advice on protecting your API key(s)](https://opencagedata.com/guides/how-to-protect-your-api-key). The value you specify should be of the form `second level domain . top level domain` For example: `opencagedata.com` There is no need to specify protocol (https or http), subdomains, or ports, we will return the correct access-control-allow-origin header. We also automatically support all requests with an origin of `localhost`. An example: if you add `opencagedata.com` as your domain, requests with the following origin values will all work correctly: - `http://www.opencagedata.com` - `https://blog.opencagedata.com` - `http://localhost:3000` - `http://dev.opencagedata.com:8080` Additional resources: - If you are sending requests to our API via AJAX you may find [our jQuery tutorial](https://opencagedata.com/tutorials/geocode-in-jquery) helpful. - Learn more about [CORS on Wikipedia](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing). ## Change Log We keep a record of [all changes to the API on GitHub](https://github.com/OpenCageData/opencagedata-misc-docs/blob/master/CHANGES.md). We also recommend you [follow us on Mastodon](https://en.osm.town/@opencage) and/or [read our blog](https://blog.opencagedata.com) where all changes are announced. [![Screenshot of the OpenCage geocoding API Change log](https://assets.opencagedata.com/assets/changelog-screenshot-b4b50de17e0e30357da26d9b8614d87e457de89261b112b84fcca7d96a787644.png "OpenCage geocoding API change log") ](https://github.com/OpenCageData/opencagedata-misc-docs/blob/master/CHANGES.md) _Screenshot of the OpenCage geocoding API change log_ ## Migrating from other geocoding services You may find our guide to [switching from Google Maps](https://opencagedata.com/guides/how-to-switch-from-google-maps-geocoding) or [switching from Nominatim](https://opencagedata.com/guides/how-to-switch-from-nominatim) to be helpful. ## Google Compatibility As a convenience we provide a Google compatible response format for forward geocoding. **Please note:** Support for the `google-v3-json` format may be discontinued in the future as it is not used much. We strongly recommend migrating to our JSON response format. Please see [our overview of how our service differs from Google's](https://opencagedata.com/guides/how-to-switch-from-google-maps-geocoding). ### Required Parameters - `address` - the query string to be geocoded; this must be URL encoded - `key` - your OpenCage geocoding API key, a 32 character long, alphanumeric string ### Optional Parameters - `bounds ` - a viewport, 2 coordinate pairs, e.g. ` 34.172684,-118.604794|34.236144,-118.500938` - `region ` - a country code, e.g. ` es` for Spain - `sensor` - required by Google as an indicator of whether the request comes from a device with a location sensor; this parameter is ignored by the OpenCage geocoding API. ### Google JSON Output In the following example, a response in Google's JSON format is requested to get the coordinates of the old OpenCage office in central London at _82 Clerkenwell Road, London EC1M 5RF, United Kingdom_. `https://api.opencagedata.com/geocode/v1/google-v3-json?address=82+Clerkenwell+Road%2C+London+EC1M+5RF%2C+United+Kingdom&pretty=1&key=YOUR-API-KEY` A JSON geocoding response contains 3 elements: - `total_results ` - the number of elements in the ` results` array - `results` - an array of result responses - `status` - the overall status of the request Example `google-v3-json` response: { "results" : [ { "address_components" : [ { "long_name" : "Europe", "short_name" : "Europe", "types" : [ "continent" ] }, { "long_name" : "London", "short_name" : "London", "types" : [ "locality", "political" ] }, { "long_name" : "England", "short_name" : "England", "types" : [ "administrative_area_level_1", "political" ] }, { "long_name" : "Greater London", "short_name" : "Greater London", "types" : [ "administrative_area_level_2", "political" ] }, { "long_name" : "European Union", "short_name" : "European Union", "types" : [ "political_union" ] }, { "long_name" : "SW1A 2DX", "short_name" : "SW1A 2DX", "types" : [ "postal_code" ] }, { "long_name" : "United Kingdom", "short_name" : "United Kingdom", "types" : [ "country", "political" ] } ], "formatted_address" : "London SW1A 2DX, United Kingdom", "geometry" : { "bounds" : { "northeast" : { "lat" : "51.6673219", "lng" : "0.0323526" }, "southwest" : { "lat" : "51.3473219", "lng" : "-0.2876474" } }, "location" : { "lat" : "51.5073219", "lng" : "-0.1276474" } } }, { "address_components" : [ { "long_name" : "London", "short_name" : "London", "types" : [ "administrative_area_level_2", "political" ] }, { "long_name" : "Europe", "short_name" : "Europe", "types" : [ "continent" ] }, { "long_name" : "England", "short_name" : "England", "types" : [ "administrative_area_level_1", "political" ] }, { "long_name" : "Greater London", "short_name" : "Greater London", "types" : [ "administrative_area_level_2", "political" ] }, { "long_name" : "European Union", "short_name" : "European Union", "types" : [ "political_union" ] }, { "long_name" : "United Kingdom", "short_name" : "United Kingdom", "types" : [ "country", "political" ] } ], "formatted_address" : "London, United Kingdom", "geometry" : { "bounds" : { "northeast" : { "lat" : "51.6918741", "lng" : "0.3340155" }, "southwest" : { "lat" : "51.2867601", "lng" : "-0.5103751" } }, "location" : { "lat" : "51.4893335", "lng" : "-0.144055084527687" } } }, { "address_components" : [ { "long_name" : "City of London", "short_name" : "City of London", "types" : [ "administrative_area_level_2", "political" ] }, { "long_name" : "Europe", "short_name" : "Europe", "types" : [ "continent" ] }, { "long_name" : "England", "short_name" : "England", "types" : [ "administrative_area_level_1", "political" ] }, { "long_name" : "Greater London", "short_name" : "Greater London", "types" : [ "administrative_area_level_2", "political" ] }, { "long_name" : "European Union", "short_name" : "European Union", "types" : [ "political_union" ] }, { "long_name" : "United Kingdom", "short_name" : "United Kingdom", "types" : [ "country", "political" ] } ], "formatted_address" : "City of London, United Kingdom", "geometry" : { "bounds" : { "northeast" : { "lat" : "51.5233213", "lng" : "-0.0727261" }, "southwest" : { "lat" : "51.5068696", "lng" : "-0.1138211" } }, "location" : { "lat" : "51.514947", "lng" : "-0.0930460965094679" } } }, { "address_components" : [ { "long_name" : "North America", "short_name" : "North America", "types" : [ "continent" ] }, { "long_name" : "London", "short_name" : "London", "types" : [ "locality", "political" ] }, { "long_name" : "Ontario", "short_name" : "Ontario", "types" : [ "administrative_area_level_1", "political" ] }, { "long_name" : "Southwestern Ontario", "short_name" : "Southwestern Ontario", "types" : [ "administrative_area_level_2", "political" ] }, { "long_name" : "N6B 2P8", "short_name" : "N6B 2P8", "types" : [ "postal_code" ] }, { "long_name" : "Canada", "short_name" : "Canada", "types" : [ "country", "political" ] } ], "formatted_address" : "London, ON N6B 2P8, Canada", "geometry" : { "bounds" : { "northeast" : { "lat" : "43.148576", "lng" : "-81.086643" }, "southwest" : { "lat" : "42.828576", "lng" : "-81.406643" } }, "location" : { "lat" : "42.988576", "lng" : "-81.246643" } } }, { "address_components" : [ { "long_name" : "London", "short_name" : "London", "types" : [ "administrative_area_level_2", "political" ] }, { "long_name" : "North America", "short_name" : "North America", "types" : [ "continent" ] }, { "long_name" : "Ontario", "short_name" : "Ontario", "types" : [ "administrative_area_level_1", "political" ] }, { "long_name" : "Southwestern Ontario", "short_name" : "Southwestern Ontario", "types" : [ "administrative_area_level_2", "political" ] }, { "long_name" : "Canada", "short_name" : "Canada", "types" : [ "country", "political" ] } ], "formatted_address" : "Southwestern Ontario, ON, Canada", "geometry" : { "bounds" : { "northeast" : { "lat" : "43.0730461", "lng" : "-81.1070784" }, "southwest" : { "lat" : "42.824599", "lng" : "-81.3906556" } }, "location" : { "lat" : "42.9537654", "lng" : "-81.2291529" } } }, { "address_components" : [ { "long_name" : "Laurel County", "short_name" : "Laurel County", "types" : [ "administrative_area_level_2", "political" ] }, { "long_name" : "North America", "short_name" : "North America", "types" : [ "continent" ] }, { "long_name" : "London", "short_name" : "London", "types" : [ "locality", "political" ] }, { "long_name" : "Kentucky", "short_name" : "Kentucky", "types" : [ "administrative_area_level_1", "political" ] }, { "long_name" : "40741", "short_name" : "40741", "types" : [ "postal_code" ] }, { "long_name" : "United States of America", "short_name" : "United States of America", "types" : [ "country", "political" ] } ], "formatted_address" : "London, KY 40741, United States of America", "geometry" : { "bounds" : { "northeast" : { "lat" : "37.15226", "lng" : "-84.035957" }, "southwest" : { "lat" : "37.079759", "lng" : "-84.126262" } }, "location" : { "lat" : "37.1289771", "lng" : "-84.0832646" } } }, { "address_components" : [ { "long_name" : "Madison County", "short_name" : "Madison County", "types" : [ "administrative_area_level_2", "political" ] }, { "long_name" : "North America", "short_name" : "North America", "types" : [ "continent" ] }, { "long_name" : "London", "short_name" : "London", "types" : [ "locality", "political" ] }, { "long_name" : "Ohio", "short_name" : "Ohio", "types" : [ "administrative_area_level_1", "political" ] }, { "long_name" : "43140", "short_name" : "43140", "types" : [ "postal_code" ] }, { "long_name" : "United States of America", "short_name" : "United States of America", "types" : [ "country", "political" ] } ], "formatted_address" : "London, OH 43140, United States of America", "geometry" : { "bounds" : { "northeast" : { "lat" : "39.921786", "lng" : "-83.389997" }, "southwest" : { "lat" : "39.85928", "lng" : "-83.478923" } }, "location" : { "lat" : "39.8864493", "lng" : "-83.448253" } } }, { "address_components" : [ { "long_name" : "Pope County", "short_name" : "Pope County", "types" : [ "administrative_area_level_2", "political" ] }, { "long_name" : "North America", "short_name" : "North America", "types" : [ "continent" ] }, { "long_name" : "London", "short_name" : "London", "types" : [ "locality", "political" ] }, { "long_name" : "Arkansas", "short_name" : "Arkansas", "types" : [ "administrative_area_level_1", "political" ] }, { "long_name" : "United States of America", "short_name" : "United States of America", "types" : [ "country", "political" ] } ], "formatted_address" : "London, AR, United States of America", "geometry" : { "bounds" : { "northeast" : { "lat" : "35.3389327", "lng" : "-93.1874567" }, "southwest" : { "lat" : "35.3169503", "lng" : "-93.2716305" } }, "location" : { "lat" : "35.328973", "lng" : "-93.2529553" } } }, { "address_components" : [ { "long_name" : "Tulare County", "short_name" : "Tulare County", "types" : [ "administrative_area_level_2", "political" ] }, { "long_name" : "North America", "short_name" : "North America", "types" : [ "continent" ] }, { "long_name" : "California", "short_name" : "California", "types" : [ "administrative_area_level_1", "political" ] }, { "long_name" : "London", "short_name" : "London", "types" : [ "locality", "political" ] }, { "long_name" : "United States of America", "short_name" : "United States of America", "types" : [ "country", "political" ] } ], "formatted_address" : "London, CA, United States of America", "geometry" : { "bounds" : { "northeast" : { "lat" : "36.4884367", "lng" : "-119.4385395" }, "southwest" : { "lat" : "36.4734452", "lng" : "-119.4497699" } }, "location" : { "lat" : "36.4760619", "lng" : "-119.4431785" } } } ], "status" : "OK" } ## OpenAPI specification As a convenience we provide an [Open API specification for the OpenCage Geocoding API](https://opencagedata.com/openapi.yaml). ## Other geolocation technologies There are many different geolocation technologies, and geocoding is often confused or conflated with them. You may find our guides useful where we explain the attributes of each technology: - [Browser geolocation and geocoding](https://opencagedata.com/guides/how-to-determine-user-location-via-browser-geolocation) - [The difference between IP geolocation and geocoding](https://opencagedata.com/guides/how-ip-geolocation-differs-from-geocoding) - [The differences between geocoding and geosearch](https://opencagedata.com/guides/the-difference-between-geocoding-and-geosearch) Finally, we are sometimes asked if we can locate a mobile phone simply via the phone number. **No, we can't, and neither can anyone else**. Please [read the details on our blog](https://blog.opencagedata.com/post/we-can-not-convert-a-phone-number-into-a-location-sorry). ## Help Us Improve If anything in this documentation is unclear, or you have questions about the geocoding API [please get in touch with us](https://opencagedata.com/contact#technicalgc). Geocoding the world is a tough challenge, we would love your help. Much of our code [is open source](https://github.com/opencagedata/), feedback or pull requests are always appreciated. ### Bugs Unfortunately, humanity has not always chosen to name places in a way that is simple for computers to decipher. The task a geocoder faces is a difficult one. A geocoder consists of two things, software and the underlying data. So there are two types of problems that can occur: a software problem, or data problems (erroneous or missing data). In both cases we want to solve it, but what needs to be done depends on the type of problem we're facing. Regardless, we appreciate your feedback and will work with you to get better. ### Security Issues We make every effort to keep user data secure, please see [our security policy](https://opencagedata.com/security-policy) for details. If you find a security vulnerability please report it to security @ opencagedata.com, we will follow up with you promptly. Please see the details of our [security bounty program](https://opencagedata.com/security-bounty). If you wish to encrypt your report you can find our public key on [our security.txt](https://opencagedata.com/.well-known/security.txt). Thank you. ## Thanks Thank you for using the OpenCage geocoding API. Thanks also to everyone who has contributed data and software to [OpenStreetMap and the other open geo datasources we rely on](https://opencagedata.com/credits). Learn more about [how we give back to the open geospatial community](https://opencagedata.com/about#geo-innovation).