add FAQ about finding bad postcodes

[nominatim.git] / docs / api / Reverse.md

diff --git a/docs/api/Reverse.md b/docs/api/Reverse.md
index 22e0133160d5dce90275c20fa103dbd1a65d5a7a..083000aa171322f40e92085e68ba66e8d9c77314 100644 (file)
--- 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?<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 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 [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](https://en.wikipedia.org/wiki/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
@@ -69,8 +81,9 @@ comma-separated list of language codes.
 
 * `zoom=[0-18]`
 
-Level of detail required for the address. Default: 18. 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=<valid email address>`
 
-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)
       <postcode>B72</postcode>
       <country>United Kingdom</country>
       <country_code>gb</country_code>
-    </addressparts>   
+    </addressparts>
   </reversegeocode>
 ```
 
@@ -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",