Merge remote-tracking branch 'upstream/master'

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

diff --git a/docs/api/Details.md b/docs/api/Details.md
index b5405c836e932ef38bc5296b42b55347a73d5476..c50378c5a6275cf0be3f0f0da1fd424c32ac1b84 100644 (file)
--- a/docs/api/Details.md
+++ b/docs/api/Details.md
@@ -1,19 +1,26 @@
 # Place details
 
 # Place details
 

-Lookup details about a single place by id. The default output is HTML for debugging search logic and results.
+Show all details about a single place saved in the database.

 
 

-**The details page (including JSON output) exists for debugging only and must not be downloaded automatically**, see [Nominatim Usage Policy](https://operations.osmfoundation.org/policies/nominatim/).
+This API endpoint is meant for visual inspection of the data in the database,
+mainly together with [Nominatim-UI](https://github.com/osm-search/nominatim-ui/).
+The parameters of the endpoint and the output may change occasionally between
+versions of Nominatim. Do not rely on the output in scripts or applications.
+
+!!! warning
+    The details endpoint at https://nominatim.openstreetmap.org
+    may not used in scripts or bots at all.
+    See [Nominatim Usage Policy](https://operations.osmfoundation.org/policies/nominatim/).

 
 
 
 

-## Parameters

 
 The details API supports the following two request formats:
 
 
 The details API supports the following two request formats:
 

-```
-  https://nominatim.openstreetmap.org/details?osmtype=[N|W|R]&osmid=<value>&class=<value>
+``` xml
+https://nominatim.openstreetmap.org/details?osmtype=[N|W|R]&osmid=<value>&class=<value>

 ```
 
 ```
 

-`osmtype` and `osmid` are required parameter. The type is one of node (N), way (W)
+`osmtype` and `osmid` are required parameters. The type is one of node (N), way (W)

 or relation (R). The id must be a number. The `class` parameter is optional and
 allows to distinguish between entries, when the corresponding OSM object has more
 than one main tag. For example, when a place is tagged with `tourism=hotel` and
 or relation (R). The id must be a number. The `class` parameter is optional and
 allows to distinguish between entries, when the corresponding OSM object has more
 than one main tag. For example, when a place is tagged with `tourism=hotel` and


@@ -23,72 +30,102 @@ to get exactly the one you want. If there are multiple places in the database
 but the `class` parameter is left out, then one of the places will be chosen
 at random and displayed.
 
 but the `class` parameter is left out, then one of the places will be chosen
 at random and displayed.
 

-```
-  https://nominatim.openstreetmap.org/details?placeid=<value>
+``` xml
+https://nominatim.openstreetmap.org/details?place_id=<value>

 ```
 
 ```
 

-Placeids are assigned sequentially during Nominatim data import. The id for a place is different between Nominatim installation (servers) and changes when data gets reimported. Therefore it can't be used as permanent id and shouldn't be used in bug reports.
+Place IDs are assigned sequentially during Nominatim data import. The ID
+for a place is different between Nominatim installation (servers) and
+changes when data gets reimported. Therefore it cannot be used as
+a permanent id and shouldn't be used in bug reports.

 
 

+!!! danger "Deprecation warning"
+    The API can also be used with the URL
+    `https://nominatim.openstreetmap.org/details.php`. This is now deprecated
+    and will be removed in future versions.

 
 

-Additional optional parameters are explained below.

 
 

-### Output format
+## Parameters

 
 

-* `format=[html|json]`
+This section lists additional optional parameters.

 
 

-See [Place Output Formats](Output.md) for details on each format. (Default: html)
+### Output format

 
 

-* `json_callback=<string>`
+| Parameter | Value | Default |
+|-----------| ----- | ------- |
+| json_callback | function name | _unset_ |

 
 

-Wrap JSON output in a callback function (JSONP) i.e. `<string>(<json>)`.
-Only has an effect for JSON output formats.
+When set, 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.

 
 

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

 
 

-For JSON output will add indentation to make it more human-readable. (Default: 0)
+`[PHP-only]` Add indentation to the output to make it more human-readable.

 
 
 ### Output details
 
 
 
 ### Output details
 

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

 
 

-Include a breakdown of the address into elements. (Default for JSON: 0, for HTML: 1)
+When set to 1, include a breakdown of the address into elements.

 
 

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

 
 

-Include a list of name keywords and address keywords (word ids). (Default: 0)
+When set to 1, include a list of name keywords and address keywords
+in the result.

 
 

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

 
 

-Include details of places higher in the address hierarchy. E.g. for a street this is usually the city, state, postal code, country. (Default: 1)
+Include details of places that are linked with this one. Places get linked
+together when they are different forms of the same physical object. Nominatim
+links two kinds of objects together: place nodes get linked with the
+corresponding administrative boundaries. Waterway relations get linked together with their
+members.

 
 

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

 
 

-Include details of places lower in the address hierarchy. E.g. for a city this usually a list of streets, suburbs, rivers. (Default for JSON: 0, for HTML: 1)
+Include details of places lower in the address hierarchy.

 
 

-* `group_hierarchy=[0|1]`
+`[Python-only]` will only return properly parented places. These are address
+or POI-like places that reuse the address of their parent street or place.

 
 

-For JSON output will group the places by type. (Default: 0)
+| Parameter | Value | Default |
+|-----------| ----- | ------- |
+| group_hierarchy  | 0 or 1 | 0 |

 
 

-* `polygon_geojson=[0|1]`
+When set to 1, the output of the address hierarchy will be
+grouped by type.

 
 

-Include geometry of result. (Default for JSON: 0, for HTML: 1)
+| Parameter | Value  | Default |
+|-----------| -----  | ------- |
+| polygon_geojson | 0 or 1 | 0 |

 
 

-### Language of results

 
 

-* `accept-language=<browser language string>`
+Include geometry of result.

 
 

-Preferred language order for showing result, 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.
+### Language of results

 
 

+| Parameter | Value | Default |
+|-----------| ----- | ------- |
+| accept-language | browser language string | content of "Accept-Language" HTTP header |

 
 

-## Examples
+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).

 
 

-##### HTML

 
 

-[https://nominatim.openstreetmap.org/details.php?osmtype=W&osmid=38210407](https://nominatim.openstreetmap.org/details.php?osmtype=W&osmid=38210407)
+## Examples

 
 ##### JSON
 
 
 ##### JSON