X-Git-Url: https://git.openstreetmap.org./nominatim.git/blobdiff_plain/cc3827b52013a0bd2ff397592ee64a9a1698583e..0af8dac3d35a94afe0b6ad775f3226d8d147501d:/docs/api/Details.md diff --git a/docs/api/Details.md b/docs/api/Details.md index 357b6a4b..b836efd3 100644 --- a/docs/api/Details.md +++ b/docs/api/Details.md @@ -1,92 +1,126 @@ # 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: +``` xml +https://nominatim.openstreetmap.org/details?osmtype=[N|W|R]&osmid=&class= ``` - https://nominatim.openstreetmap.org/details?osmtype=[N|W|R]&osmid= -``` - -Both parameters are required, the type is one of node(N), way(W) or relation(R). -Or - -``` - https://nominatim.openstreetmap.org/details?placeid= +`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 +`amenity=restaurant`, there will be two place entries in Nominatim, one for a +restaurant, one for a hotel. You need to specify `class=tourism` or `class=amentity` +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. + +``` 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 -* `format=[html|json]` - -See [Place Output Formats](Output.md) for details on each format. (Default: html) - -* `json_callback=` +## Parameters -Wrap json output in a callback function (JSONP) i.e. `()`. -Only has an effect for JSON output formats. +This section lists additional optional parameters. -* `pretty=[0|1]` +### Output format -For JSON output will add indentation to make it more human-readable. (Default: 0) +| Parameter | Value | Default | +|-----------| ----- | ------- | +| json_callback | function name | _unset_ | +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. ### 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 POIs and address that depend on the place. Only POIs +that use this place to determine their address will be returned. -* `group_hierarchy=[0|1]` +| Parameter | Value | Default | +|-----------| ----- | ------- | +| group_hierarchy | 0 or 1 | 0 | -For JSON output will group the places by type. (Default: 0) +When set to 1, the output of the address hierarchy will be +grouped by type. -* `polygon_geojson=[0|1]` +| Parameter | Value | Default | +|-----------| ----- | ------- | +| polygon_geojson | 0 or 1 | 0 | -Include geometry of result. (Default for JSON: 0, for HTML: 1) + +Include geometry of result. ### Language of results -* `accept-language=` +| Parameter | Value | Default | +|-----------| ----- | ------- | +| accept-language | browser language string | content of "Accept-Language" HTTP header | -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. +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). ## Examples -##### HTML - -[https://nominatim.openstreetmap.org/details.php?osmtype=W&osmid=38210407]() - ##### JSON -[https://nominatim.openstreetmap.org/details.php?osmtype=W&osmid=38210407&format=json]() +[https://nominatim.openstreetmap.org/details?osmtype=W&osmid=38210407&format=json](https://nominatim.openstreetmap.org/details?osmtype=W&osmid=38210407&format=json) ```json