X-Git-Url: https://git.openstreetmap.org./nominatim.git/blobdiff_plain/745e52b798d82f93f3c7c7f8608f986330aa12e0..0c25e80be0868ff26e11f04298967af5f5e5adc3:/docs/api/Details.md?ds=sidebyside diff --git a/docs/api/Details.md b/docs/api/Details.md index 2776bfe2..c50378c5 100644 --- a/docs/api/Details.md +++ b/docs/api/Details.md @@ -1,19 +1,26 @@ # 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: -``` - https://nominatim.openstreetmap.org/details?osmtype=[N|W|R]&osmid=&class= +``` xml +https://nominatim.openstreetmap.org/details?osmtype=[N|W|R]&osmid=&class= ``` -`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 @@ -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. -``` - https://nominatim.openstreetmap.org/details?place_id= +``` xml +https://nominatim.openstreetmap.org/details?place_id= ``` -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=` +| Parameter | Value | Default | +|-----------| ----- | ------- | +| json_callback | function name | _unset_ | -Wrap JSON output in a callback function (JSONP) i.e. `()`. -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 -* `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=` +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