X-Git-Url: https://git.openstreetmap.org./nominatim.git/blobdiff_plain/263240919cb41ef3d19baf44df39f3d209b7cac5..b310c86c55502f1bc2dfd7ada06220c1d278866c:/docs/api/Reverse.md diff --git a/docs/api/Reverse.md b/docs/api/Reverse.md index b3c75efc..083000aa 100644 --- a/docs/api/Reverse.md +++ b/docs/api/Reverse.md @@ -1,40 +1,52 @@ # 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? +https://nominatim.openstreetmap.org/reverse?lat=&lon=& ``` -There are two ways how the requested location can be specified: - -* `lat=` `lon=` - - A geographic location to generate an address for. The coordiantes must be - in WGS84 format. - -* `osm_type=[N|W|R]` `osm_id=` +where `lat` and `lon` are latitude and longitude 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 parameters 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 below for details on each format. (Default: html) +See [Place Output Formats](Output.md) for details on each format. (Default: xml) * `json_callback=` -Wrap json output in a callback function (JSONP) i.e. `()`. +Wrap JSON output in a callback function ([JSONP](https://en.wikipedia.org/wiki/JSONP)) i.e. `()`. Only has an effect for JSON output formats. ### Output details @@ -69,8 +81,9 @@ comma-separated list of language codes. * `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 @@ -80,7 +93,8 @@ In terms of address details the zoom levels are as follows: 8 | county 10 | city 14 | suburb - 16 | street + 16 | major streets + 17 | major and minor streets 18 | building @@ -96,7 +110,7 @@ options can be used at a time. (Default: 0) * `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) @@ -104,7 +118,7 @@ geometry. Topology is preserved in the result. (Default: 0.0) * `email=` -If you are making large numbers of request please include an appropriate email +If you are making a large number of requests, please include an appropriate email address to identify your requests. See Nominatim's [Usage Policy](https://operations.osmfoundation.org/policies/nominatim/) for more details. @@ -134,7 +148,7 @@ This overrides the specified machine readable format. (Default: 0) B72 United Kingdom gb - + ``` @@ -145,10 +159,10 @@ This overrides the specified machine readable format. (Default: 0) ```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", + "lat":"-34.4391708", "lon":"-58.7064573", "place_rank":"26", "category":"highway",