v1
latestOpenAPI 3.0.02026-07-241437122.4 KBReverse Geocoding
Reverse geocoding is the process of converting a coordinate or location (latitude, longitude) to a readable address or place name. This permits the identification of nearby street addresses, places, and/or area subdivisions such as a neighborhood, county, state, or country.
Query parameters
Latitude of the location to generate an address for.
Longitude of the location to generate an address for.
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.
Level of detail required where 0 is country and 18 is house/building. Defaults to 18. In terms of address details the zoom levels are as follows:
| zoom | address detail |
|---|---|
| 3 | country |
| 5 | state |
| 8 | county |
| 10 | city |
| 14 | suburb |
| 16 | street |
| 18 | building |
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.
Include a breakdown of the address of this result into elements. Important components include (but not limited to) country, postcode, state, county, city, town. Only those elements that are available for a given location will be returned.
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.
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.
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.
Adds state or province code when available to the state_code key inside the address object when available. 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.
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.
When one of the polygon_* outputs is chosen, return a simplified version of the output geometry. The parameter describes the tolerance in degrees with which the geometry may differ from the original geometry. Topology is preserved in the geometry.
Response
OK
Example response
{
"place_id": "223483692",
"licence": "© LocationIQ.com CC BY 4.0, Data © OpenStreetMap contributors, ODbL 1.0",
"osm_type": "way",
"osm_id": "19301621",
"boundingbox": [
"39.307405567782",
"39.307505567782",
"-84.292824851595",
"-84.292724851595"
],
"lat": "39.3074555677816",
"lon": "-84.2927748515948",
"display_name": "3894, Spring Mill Way, Hunter’s Point, Landen, Warren County, Ohio, 45039, United States of America",
"class": "place",
"type": "house",
"importance": 0.62025,
"address": {
"name": "Empire State Building",
"house_number": "3894",
"road": "Spring Mill Way",
"residential": "Hunter’s Point",
"village": "Landen",
"county": "Warren County",
"state": "Ohio",
"postcode": "45039",
"country": "United States of America",
"country_code": "us",
"city": "Landen"
}
}