actions: run legacy test against newest postgresql 16

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

diff --git a/docs/api/Reverse.md b/docs/api/Reverse.md
index 13805fd45edc7cab65b80d868270367c54f0777e..216ce6e613907b5a96d035d4d0a06eedd53197b9 100644 (file)
--- a/docs/api/Reverse.md
+++ b/docs/api/Reverse.md
@@ -1,76 +1,133 @@
 # Reverse Geocoding
 
 # Reverse Geocoding
 

-Reverse geocoding generates an address from a latitude and longitude or from
-an OSM object.
+Reverse geocoding generates an address from a coordinate given as
+latitude and longitude.

 
 

-## Parameters
+## 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.
+
+## Endpoint

 
 The main format of the reverse API is
 
 ```
 
 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:
+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.

 
 

-* `lat=<value>` `lon=<value>`

 
 

-    A geographic location to generate an address for. The coordiantes must be
-    in WGS84 format.
+!!! danger "Deprecation warning"
+    The reverse API used to allow address lookup for a single OSM object by
+    its OSM id for `[PHP-only]`. The use is considered deprecated.
+    Use the [Address Lookup API](Lookup.md) instead.

 
 

-* `osm_type=[N|W|R]` `osm_id=<value>`
+!!! danger "Deprecation warning"
+    The API can also be used with the URL
+    `https://nominatim.openstreetmap.org/reverse.php`. This is now deprecated
+    and will be removed in future versions.

 
 

-    A specific OSM node(N), way(W) or relation(R) to return an address for.

 
 

-In both cases exactly one object is returned. The two input parameters cannot
-be used at the same time. Both accept the additional optional parameters listed
-below.
+## Parameters
+
+This section lists additional parameters to further influence the output.

 
 ### Output format
 
 
 ### Output format
 

-* `format=[xml|json|jsonv2|geojson|geocodejson]`
+| Parameter | Value | Default |
+|-----------| ----- | ------- |
+| format    | one of: `xml`, `json`, `jsonv2`, `geojson`, `geocodejson` | `xml` |
+
+See [Place Output Formats](Output.md) for details on each format.
+

 
 

-See [Place Output Formats](Output.md) for details on each format. (Default: html)
+| Parameter | Value | Default |
+|-----------| ----- | ------- |
+| json_callback | function name | _unset_ |

 
 

-* `json_callback=<string>`
+When given, then JSON output will be wrapped in a callback function with
+the given name. See [JSONP](https://en.wikipedia.org/wiki/JSONP) for more
+information.

 
 

-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.
 
 Only has an effect for JSON output formats.
 

+

 ### Output details
 
 ### Output details
 

-* `addressdetails=[0|1]`
+| Parameter | Value | Default |
+|-----------| ----- | ------- |
+| addressdetails | 0 or 1 | 1 |
+
+When set to 1, include a breakdown of the address into elements.
+The exact content of the address breakdown depends on the output format.

 
 

-Include a breakdown of the address into elements. (Default: 1)
+!!! tip
+    If you are interested in a stable classification of address categories
+    (suburb, city, state, etc), have a look at the `geocodejson` format.
+    All other formats return classifications according to OSM tagging.
+    There is a much larger set of categories and they are not always consistent,
+    which makes them very hard to work with.

 
 
 
 

-* `extratags=[0|1]`
+| Parameter | Value | Default |
+|-----------| ----- | ------- |
+| extratags | 0 or 1 | 0 |

 
 

-Include additional information in the result if available,
-e.g. wikipedia link, opening hours. (Default: 0)
+When set to 1, the response include any additional information in the result
+that is available in the database, e.g. wikipedia link, opening hours.

 
 
 
 

-* `namedetails=[0|1]`
+| Parameter | Value | Default |
+|-----------| ----- | ------- |
+| namedetails | 0 or 1 | 0 |

 
 

-Include a list of alternative names in the results. These may include
-language variants, references, operator and brand. (Default: 0)
+When set to 1, include a full list of names for the result. These may include
+language variants, older names, references and brand.

 
 
 ### Language of results
 
 
 
 ### Language of results
 

-* `accept-language=<browser language string>`
+| Parameter | Value | Default |
+|-----------| ----- | ------- |
+| accept-language | browser language string | content of "Accept-Language" HTTP header |

 
 

-Preferred language order for showing search results, overrides the value
-specified in the "Accept-Language" HTTP header.
-Either use a standard RFC2616 accept-language string or a simple
-comma-separated list of language codes.
+Preferred language order for showing search results. This may either be
+a simple comma-separated list of language codes or have the same format
+as the ["Accept-Language" HTTP header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language).

 
 

-### Result limitation
+!!! tip
+    First-time users of Nominatim tend to be confused that they get different
+    results when using Nominatim in the browser versus in a command-line tool
+    like wget or curl. The command-line tools
+    usually don't send any Accept-Language header, prompting Nominatim
+    to show results in the local language. Browsers on the contratry always
+    send the currently chosen browser language.

 
 

-* `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.
+### Result restriction
+
+| Parameter | Value | Default |
+|-----------| ----- | ------- |
+| zoom      | 0-18  | 18      |
+
+Level of detail required for the address. 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
 In terms of address details the zoom levels are as follows:
 
  zoom | address detail


@@ -79,41 +136,81 @@ In terms of address details the zoom levels are as follows:
   5   | state
   8   | county
   10  | city
   5   | state
   8   | county
   10  | city

-  14  | suburb
+  12  | town / borough
+  13  | village / suburb
+  14  | neighbourhood
+  15  | any settlement

   16  | major streets
   17  | major and minor streets
   18  | building
 
 
   16  | major streets
   17  | major and minor streets
   18  | building
 
 

+| Parameter | Value | Default |
+|-----------| ----- | ------- |
+| layer     | comma-separated list of: `address`, `poi`, `railway`, `natural`, `manmade` | _unset_ (no restriction) |
+
+**`[Python-only]`**
+
+The layer filter allows to select places by themes.
+
+The `address` layer contains all places that make up an address:
+address points with house numbers, streets, inhabited places (suburbs, villages,
+cities, states etc.) and administrative boundaries.
+
+The `poi` layer selects all point of interest. This includes classic points
+of interest like restaurants, shops, hotels but also less obvious features
+like recycling bins, guideposts or benches.
+
+The `railway` layer includes railway infrastructure like tracks.
+Note that in Nominatim's standard configuration, only very few railway
+features are imported into the database.
+
+The `natural` layer collects features like rivers, lakes and mountains while
+the `manmade` layer functions as a catch-all for features not covered by the
+other layers.
+
+

 ### Polygon output
 
 ### Polygon output
 

-* `polygon_geojson=1`
-* `polygon_kml=1`
-* `polygon_svg=1`
-* `polygon_text=1`
+| Parameter | Value  | Default |
+|-----------| -----  | ------- |
+| polygon_geojson | 0 or 1 | 0 |
+| polygon_kml     | 0 or 1 | 0 |
+| polygon_svg     | 0 or 1 | 0 |
+| polygon_text    | 0 or 1 | 0 |

 
 

-Output geometry of results as a GeoJSON, KML, SVG or WKT. Only one of these
-options can be used at a time. (Default: 0)
+Add the full geometry of the place to the result output. Output formats
+in GeoJSON, KML, SVG or WKT are supported. Only one of these
+options can be used at a time.

 
 

-* `polygon_threshold=0.0`
+| Parameter | Value  | Default |
+|-----------| -----  | ------- |
+| polygon_threshold | floating-point number | 0.0 |

 
 

-Simplify the output geometry before returning. The parameter is the
+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
 tolerance in degrees with which the geometry may differ from the original

-geometry. Topology is preserved in the result. (Default: 0.0)
+geometry. Topology is preserved in the geometry.
+

 
 ### Other
 
 
 ### Other
 

-* `email=<valid email address>`
+| Parameter | Value  | Default |
+|-----------| -----  | ------- |
+| email     | valid email address | _unset_ |

 
 If you are making large numbers of request please include an appropriate email
 
 If you are making large numbers of request please include an appropriate email

-address to identify your requests. See Nominatim's [Usage Policy](https://operations.osmfoundation.org/policies/nominatim/) for more details.
+address to identify your requests. See Nominatim's
+[Usage Policy](https://operations.osmfoundation.org/policies/nominatim/) for more details.

 
 
 
 

-* `debug=[0|1]`
+| Parameter | Value  | Default |
+|-----------| -----  | ------- |
+| debug     | 0 or 1 | 0       |

 
 Output assorted developer debug information. Data on internals of Nominatim's
 
 Output assorted developer debug information. Data on internals of Nominatim's

-"Search Loop" logic, and SQL queries. The output is (rough) HTML format.
-This overrides the specified machine readable format. (Default: 0)
+"search loop" logic, and SQL queries. The output is HTML format.
+This overrides the specified machine readable format.

 
 
 ## Examples
 
 
 ## Examples


@@ -149,7 +246,7 @@ This overrides the specified machine readable format. (Default: 0)
   "licence":"Data © OpenStreetMap contributors, ODbL 1.0. https:\/\/www.openstreetmap.org\/copyright",
   "osm_type":"way",
   "osm_id":"280940520",
   "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",
   "lon":"-58.7064573",
   "place_rank":"26",
   "category":"highway",