# Reverse Geocoding
-Reverse geocoding generates an address from a latitude and longitude or from
-an OSM object.
+Reverse geocoding generates an address from a latitude and longitude.
+
+## How it works
+
+The reverse geocoding API does not exactly compute the address for the
+coordinate it receives. It works by finding the closest suitable OSM object
+and returning its address information. This may occasionally lead to
+unexpected results.
+
+First of all, Nominatim only includes OSM objects in
+its index that are suitable for searching. Small, unnamed paths for example
+are missing from the database and can therefore not be used for reverse
+geocoding either.
+
+The other issue to be aware of is that the closest OSM object may not always
+have a similar enough address to the coordinate you were requesting. For
+example, in dense city areas it may belong to a completely different street.
+
## Parameters
The main format of the reverse API is
```
-https://nominatim.openstreetmap.org/reverse?<query>
+https://nominatim.openstreetmap.org/reverse?lat=<value>&lon=<value>&<params>
```
-There are two ways how the requested location can be specified:
-
-* `lat=<value>` `lon=<value>`
-
- A geographic location to generate an address for. The coordiantes must be
- in WGS84 format.
-
-* `osm_type=[N|W|R]` `osm_id=<value>`
+where `lat` and `lon` are latitude and longitutde of a coordinate in WGS84
+projection. The API returns exactly one result or an error when the coordinate
+is in an area with no OSM data coverage.
- A specific OSM node(N), way(W) or relation(R) to return an address for.
+Additional paramters are accepted as listed below.
-In both cases exactly one object is returned. The two input paramters cannot
-be used at the same time. Both accept the additional optional parameters listed
-below.
+!!! warning "Deprecation warning"
+ The reverse API used to allow address lookup for a single OSM object by
+ its OSM id. This use is now deprecated. Use the [Address Lookup API](../Lookup)
+ instead.
### Output format
* `format=[xml|json|jsonv2|geojson|geocodejson]`
-See [Place Output Formats](Output.md) for details on each format. (Default: html)
+See [Place Output Formats](Output.md) for details on each format. (Default: xml)
* `json_callback=<string>`
-Wrap json output in a callback function (JSONP) i.e. `<string>(<json>)`.
+Wrap JSON output in a callback function ([JSONP](https://en.wikipedia.org/wiki/JSONP)) i.e. `<string>(<json>)`.
Only has an effect for JSON output formats.
### Output details
* `zoom=[0-18]`
-Level of detail required for the address. This is a number that corresponds
-roughly to the zoom level used in map frameworks like Leaflet.js, Openlayers etc.
+Level of detail required for the address. Default: 18. This is a number that
+corresponds roughly to the zoom level used in XYZ tile sources in frameworks
+like Leaflet.js, Openlayers etc.
In terms of address details the zoom levels are as follows:
zoom | address detail
8 | county
10 | city
14 | suburb
- 16 | street
+ 16 | major streets
+ 17 | major and minor streets
18 | building
* `polygon_threshold=0.0`
-Simplify the output geometry before returning. The parameter is the
+Return a simplified version of the output geometry. The parameter is the
tolerance in degrees with which the geometry may differ from the original
geometry. Topology is preserved in the result. (Default: 0.0)
<postcode>B72</postcode>
<country>United Kingdom</country>
<country_code>gb</country_code>
- </addressparts>
+ </addressparts>
</reversegeocode>
```
```json
{
"place_id":"134140761",
- "licence":"Data © OpenStreetMap contributors, ODbL 1.0. http:\/\/www.openstreetmap.org\/copyright",
+ "licence":"Data © OpenStreetMap contributors, ODbL 1.0. https:\/\/www.openstreetmap.org\/copyright",
"osm_type":"way",
"osm_id":"280940520",
"lat":"-34.4391708",
projects / nominatim.git / blobdiff