v1
latestOpenAPI 3.0.02026-07-241437122.4 KBStructured Geocoding
Structured Query offers a more specific way to search for locations. Instead of using a single text string, you can provide distinct address components in a structured format. This includes specifying elements like street, neighborhood, city, state, country, and postal code, each sent as separate API parameters.
Query parameters
Pass this parameter to specify the street address (building number, name and road).
Include this parameter to provide the city information for geocoding.
Use this to indicate the county or administrative region of the address.
Pass this to specify the state or province of the address, helping to identify the region within the country.
Include this to provide country of the address, crucial for precise geocoding on a global scale.
Use this to indicate the postal or ZIP code, aiding in pinpointing the exact area within a city or locality.
Output Format. Defaults to xml.
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 or xmlv1.1 format options.
Include a breakdown of the address of this result into elements. Defaults to 0.
Adds state or province code when available to the state_code key inside the address object when available. Defaults to 0.
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.
Restrict result to items contained within the bounds specified in the viewbox parameter. Defaults to 0.
Limit the number of returned results. Accepted value: 1 to 50. Defaults to 10.
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 <a href="https://tools.ietf.org/html/rfc2616#section-14.4" target="_blank">rfc2616 accept-language string</a> or a simple comma separated list of language codes.
Limit search results to a specific country or a comma-separated list of countries. Should be the ISO 3166-1 alpha-2 code(s).
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.
| Element Name | Description |
|---|---|
| name | House name or Point of Interest (POI) such as a Cafe or School |
| house_number | House or Building number |
| road | Roads, Highways, Freeways, Motorways |
| neighbourhood | Neighbourhoods, Allotments, Quarters, Communities |
| suburb | Suburbs, Subdivisions |
| island | Islands, Islets |
| city | Cities, Towns, Villages, Municipalities, Districts, Boroughs, Hamlets |
| county | Counties |
| state | States, Provinces, Regions, State Districts |
| state_code | State or Province Code |
| postcode | Postal Codes, Zipcodes |
| country | Countries, Nation-states |
| country_code | Country Code - 2 letter (ISO 3166-1 alpha-2) |
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.
Returns address inside the postaladdress key, that is specifically formatted for each country. Currently supported for addresses in Belgium, Brazil, France, Germany, Greece, India, Ireland, Italy, Portugal, South Africa, Spain and United Kingdom. Defaults to 0.
Returns additional information about quality of the result in a matchquality object. Defaults to 0.
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.
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
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.
Include a list of alternative names in the results. These may include language variants, references, operator and brand. Defaults to 0.
Include additional information in the result if available, e.g. wikipedia link, opening hours. Defaults to 0.
Output geometry of results in geojson format. Defaults to 0.
Output geometry of results in kml format. Defaults to 0.
Output geometry of results in svg format. Defaults to 0.
Output geometry of results as a WKT. Defaults to 0.
Wrap json output in a callback function (JSONP) i.e. <string>(<json>). Only has an effect for JSON output formats.
Response
OK
Example response
[
{
"address": {
"house_number": "3894",
"road": "Spring Mill Way",
"residential": "Hunter’s Point",
"village": "Landen",
"city": "Landen",
"county": "Warren County",
"state": "Ohio",
"postcode": "45039",
"country": "United States of America",
"country_code": "us",
"state_code": "oh"
}
}
]