API Reference
Request Format
Requests can be sent to any of the following endpoints
Region 1: US
https://us1.locationiq.com/v1/reverse?key=YOUR_ACCESS_TOKEN&lat=LATITUDE&lon=LONGITUDE&format=json
Region 2: Europe
https://eu1.locationiq.com/v1/reverse?key=YOUR_ACCESS_TOKEN&lat=LATITUDE&lon=LONGITUDE&format=json
Request Example
curl --request GET \
--url 'https://us1.locationiq.com/v1/reverse?key=YOUR_ACCESS_TOKEN&lat=-37.870662&lon=144.9803321&format=json'
var settings = {
"async": true,
"crossDomain": true,
"url": "https://us1.locationiq.com/v1/reverse?key=YOUR_ACCESS_TOKEN&lat=-37.870662&lon=144.9803321&format=json",
"method": "GET"
}
$.ajax(settings).done(function (response) {
console.log(response);
});
import requests
url = "https://us1.locationiq.com/v1/reverse"
data = {
'key': 'YOUR_ACCESS_TOKEN',
'lat': '-37.870662',
'lon': '144.9803321',
'format': 'json'
}
response = requests.get(url, params=data)
print(response.text)
<?php
$curl = curl_init('https://us1.locationiq.com/v1/reverse?key=YOUR_ACCESS_TOKEN&lat=-37.870662&lon=144.9803321&format=json');
curl_setopt_array($curl, array(
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_CUSTOMREQUEST => 'GET',
));
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
Required Parameters
Name | Description |
---|---|
key | Authentication key. |
lat | Latitude of the location to generate an address for. |
lon | Longitude of the location to generate an address for. |
Optional Parameters
Name | Description | Values |
---|---|---|
zoom | Level of detail required where 0 is country and 18 is house/building. Defaults to 18 . A lower number increases speed of the server's response. Read more. | [0 to 18 ] |
format | Output Format. Defaults to xml . See note | [json | xml | xmlv1.1 ] |
addressdetails | Include a breakdown of the address of this result into elements. Defaults to 1 . Read more. | [0 | 1 ] |
namedetails | Include a list of alternative names in the results. These may include language variants, references, operator and brand. | [0 | 1 ] |
accept-language | Preferred language order for showing search results, overrides the value specified in the Accept-Language HTTP header. Defaults to en . To use native language for the response when available, use accept-language=native . Either uses standard rfc2616 accept-language string or a simple comma separated list of language codes. Read more. | |
osm_type | A specific osm type, node / way / relation to search an address for | [N | W | R ] |
osm_id | A specific osm node / way / relation to return an address for | |
json_callback | Wrap json output in a callback function (JSONP) i.e. (). Only has an effect for JSON output formats. | |
polygon_geojson | Output geometry of results in geojson format. | [0 | 1 ] |
polygon_kml | Output geometry of results in kml format. | [0 | 1 ] |
polygon_svg | Output geometry of results in svg format. | [0 | 1 ] |
polygon_text | Output geometry of results as a WKT. | [0 | 1 ] |
extratags | Include additional information in the result if available, e.g. wikipedia link, opening hours. | [0 | 1 ] |
Optional LocationIQ specific Parameters
Compatibility
The following parameters are available only on LocationIQ and are not backward-compatible with Nominatim.
Name | Description | Values |
---|---|---|
normalizeaddress | Makes parsing of the address object easier by returning a predictable and defined list of elements. Defaults to 0 for backward compatibility. We recommend setting this to 1 for new projects. | [0 | 1 ] |
normalizecity | For responses with no city value in the address section, the next available element in this order - city_district , locality , town , borough , municipality , village , hamlet , quarter , neighbourhood - from the address section will be normalized to city. Defaults to 0 . | [0 | 1 ] |
statecode | Adds state or province code when available to the state_code key inside the address object. Currently supported for addresses in the USA, Canada and Australia. Defaults to 0 | [0 | 1 ] |
showdistance | Returns the straight line distance (meters) between the input location and the result's location. Value is set in the distance key of the response. Defaults to 0 | [0 | 1 ] |
postaladdress | Returns address inside the postaladdress key, that is specifically formatted for each country. Currently supported for addresses in Belgium, Brazil, France, Germany, Greece, Ireland, Italy, Portugal, South Africa, Spain and United Kingdom. Defaults to 0 | [0 | 1 ] |
source | If this parameter is not specified, LocationIQ uses multiple public and proprietary datasets to return results. If you'd like to restrict results to only OpenStreetMap data, you can set the value of this parameter to nom . This will only query our internal cluster of Nominatim servers, and return results. We may still apply some post-processing steps to these results though, so results may vary from the official Nominatim instance. | [nom | null ] |
oceans | Allows you to specify whether or not the API should return the name of an ocean or sea if the coordinates provided fall within a body of water. By default, this parameter is set to 0 for backward compatibility. When set to 1 and used in conjunction with addressdetails=1 , the response will contain a limited address section consisting of only the name and water elements, providing the name of the ocean or sea the coordinates correspond to, if the coordinates fall within a body of water. | [0 | 1 ] |
Response
Compatibility
This version (v1) of our Reverse Geocoding API is compatible with OpenStreetMap's Nominatim Geocoder in both JSON & XML formats. However, all our enhancements such as additional datasets and algorithms are supported only in
json
orxmlv1.1
format options.
Response Example
{
"place_id": "26693344",
"licence": "https://locationiq.com/attribution",
"osm_type": "node",
"osm_id": "2525193585",
"lat": "-37.870662",
"lon": "144.9803321",
"display_name": "Imbiss 25, Blessington Street, St Kilda, City of Port Phillip, Greater Melbourne, Victoria, 3182, Australia",
"address": {
"cafe": "Imbiss 25",
"road": "Blessington Street",
"suburb": "St Kilda",
"county": "City of Port Phillip",
"region": "Greater Melbourne",
"state": "Victoria",
"postcode": "3182",
"country": "Australia",
"country_code": "au"
},
"boundingbox": [
"-37.870762",
"-37.870562",
"144.9802321",
"144.9804321"
]
}
Response Parameters
Name | Description |
---|---|
place_id | An internal identifier for this result in the LocationIQ database. This value may vary across our servers, and change often, so do not use this as an identifier for caching or storage. |
licence | The Licence and attribution requirements |
osm_type | The type of this result. One of node ,way or relation . |
osm_id | The corresponding OSM ID of this result. |
boundingbox | Array of bounding box coordinates where this result is located. The order is as below: - min lat / bottom-left Latitude - max lat / top-right Latitude - min lon / bottom-left Longitude - max lon / top-right Longitude |
lat | The Latitude of this result |
lon | The Longitude of this result |
display_name | The display name of this result, with complete address |
importance | Calculated importance of this result compared to the search query the user has provided. Ranges between 0 and 1. Type: float |
icon | The URL of an icon representing this result, if applicable. |
address | The address breakdown into individual components. Returned when addressdetails=1 is set in the request. Important components include (but not limited to) country, postcode, state, county, city, town. Read more. |
extratags | The dictionary with additional useful tags like website or maxspeed. Returned when extratags=1 is set in the request. |
namedetails | The dictionary with full list of available names including ref etc. Returned when namedetails=1 is set in the request. |
geojson | Output geometry of results in geojson format. Returned when polygon_geojson=1 is set in the request. |
geokml | Output geometry of results in kml format. Returned when polygon_kml=1 is set in the request. |
svg | Output geometry of results in svg format. Returned when polygon_svg=1 is set in the request. |
geotext | Output geometry of results as a WKT. Returned when polygon_text=1 is set in the request. |
LocationIQ Specific elements in the response
Name | Description |
---|---|
statecode | A state or province code when available. Returned when statecode is set in the request |
distance | The straight line distance (meters) between the input location and the result's location. Returned when showdistance is set in the request. |
postal_address | Returns address specifically formatted for each country. Returned when postaladdress is set in the request. |
Updated over 1 year ago