API Reference
Compatibility
This version (v1) of our Search 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
jsonorxmlv1.1format options.
Request Format
Requests can be sent to any of the following endpoints
Region 1: US
https://us1.locationiq.com/v1/search?key=YOUR_ACCESS_TOKEN&q=SEARCH_STRING&format=json
Region 2: Europe
https://eu1.locationiq.com/v1/search?key=YOUR_ACCESS_TOKEN&q=SEARCH_STRING&format=json
Request Example
curl --request GET \
--url 'https://us1.locationiq.com/v1/search?key=YOUR_ACCESS_TOKEN&q=Empire%20State%20Building&format=json'
$curl = curl_init('https://us1.locationiq.com/v1/search?key=YOUR_ACCESS_TOKEN&q=Empire%20State%20Building&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;
}
?>
import requests
url = "https://us1.locationiq.com/v1/search"
data = {
'key': 'YOUR_ACCESS_TOKEN',
'q': 'Empire State Building',
'format': 'json'
}
response = requests.get(url, params=data)
print(response.text)
var settings = {
"async": true,
"crossDomain": true,
"url": "https://us1.locationiq.com/v1/search?key=YOUR_ACCESS_TOKEN&q=Empire%20State%20Building&format=json",
"method": "GET"
}
$.ajax(settings).done(function (response) {
console.log(response);
});
Required:
| Name | Description | Required |
|---|---|---|
| key | Your API Key | Yes |
| q | Free-form query string to search for. Commas are optional, but improves performance by reducing the complexity of the search. Do not combine with structured/postalcode parameters | Either |
| street, city, county, state, country, postalcode | Alternative query string format split into several parameters for structured requests. Structured requests are faster but are less robust against alternative OSM tagging schemas. Do not combine with q=<query> parameter. | Either |
| postalcode | Alternative query string format for postal code requests that uses a special postal code dataset for geocoding. Do not combine with q=<query> or other structured parameters for postal code search. Combine with countrycodes=<countrycode> parameter for a better response | Either |
All three query forms accept the optional paramters listed below.
Optional:
| Name | Description | Values |
|---|---|---|
| format | Output Format. Defaults to xml. | [json | xml | xmlv1.1] |
| viewbox | The preferred area to find search results. Any two corner points of the box - max_lon,max_lat,min_lon,min_lat or min_lon,min_lat,max_lon,max_lat - are accepted in any order as long as they span a real box. To restrict results to those within the viewbox, use along with the bounded option. | |
| bounded | Restrict result to items contained within the bounds specified in the viewbox parameter | [0 | 1] |
| addressdetails | Include a breakdown of the address of this result into elements. Defaults to 0. Read more. | [0 | 1] |
| limit | Limit the number of returned results. Default is 10. | [1 to 50] |
| 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. | |
| countrycodes | Limit search to a list of countries. Read more. | |
| namedetails | Include a list of alternative names in the results. These may include language variants, references, operator and brand. | [0 | 1] |
| dedupe | Sometimes you have several objects in OSM identifying the same place or object in reality. The simplest case is a street being split in many different OSM ways due to different characteristics. Our Geocoder will attempt to detect such duplicates and only return one match; this is controlled by the dedupe parameter which defaults to 1. Since the limit is, for reasons of efficiency, enforced before and not after de-duplicating, it is possible that de-duplicating leaves you with less results than requested. | [0 | 1] |
| 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] |
| exclude_place_ids | If you do not want certain OSM objects to appear in the search result, give a comma separated list of the place_ids you want to skip. This can be used to broaden search results. For example, if a previous query only returned a few results, then including those here would cause the search to return other, less accurate, matches (if possible). | <comma_separated_place_ids> |
Optional - LocationIQ specific parameters:
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] |
| matchquality | Returns additional information about quality of the result in a matchquality object. Read more. 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] |
| normalizeimportance | When this parameter is absent or set to 1, the importance value(s) in the API response is limited to the range of 0 to 1. Values outside this range are adjusted to the nearest boundary (0 or 1). Setting normalizeimportance to 0 allows the importance value to be lower or higher than the specified range of 0 to 1. Defaults to 1 | [0 | 1] |
Response
Response Example
[
{
"place_id": "218751965",
"licence": "https://locationiq.com/attribution",
"osm_type": "way",
"osm_id": "34633854",
"boundingbox": [
"40.7479226",
"40.7489422",
"-73.9864855",
"-73.9848259"
],
"lat": "40.7484284",
"lon": "-73.9856546198733",
"display_name": "Empire State Building, 350, 5th Avenue, Korea Town, Manhattan Community Board 5, New York County, NYC, New York, 10018, United States of America",
"class": "tourism",
"type": "attraction",
"importance": 0.82289665394454,
"icon": "https://locationiq.com/static/images/mapicons/poi_point_of_interest.p.20.png"
},
{
"place_id": "29167569",
"licence": "https://locationiq.com/attribution",
"osm_type": "node",
"osm_id": "2709306673",
"boundingbox": [
"40.7481128",
"40.7482128",
"-73.9850458",
"-73.9849458"
],
"lat": "40.7481628",
"lon": "-73.9849958",
"display_name": "Empire State Building, 350, 5th Avenue, Korea Town, Manhattan Community Board 5, New York County, NYC, New York, 10118, United States of America",
"class": "tourism",
"type": "attraction",
"importance": 0.301,
"icon": "https://locationiq.com/static/images/mapicons/poi_point_of_interest.p.20.png"
}
]
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 |
| class | The category of this result |
| type | The 'type' of the class/category of this result |
| 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, country_code, postcode, state, county, city, town. [Read more.] (#address-details) |
| 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. |
| matchquality | Additional information about quality of the result. Returned when matchquality is set in the request. Read more |
| postal_address | Returns address specifically formatted for each country. Returned when postaladdress is set in the request. |
Updated about 1 year ago