X-Git-Url: https://git.openstreetmap.org./nominatim.git/blobdiff_plain/57bf76a0e1d766bc90afcb8a748c5e25e7aa6f08..6b1c32893b8741f37b0256eea8f62d2ae4c8651b:/docs/api/Details.md diff --git a/docs/api/Details.md b/docs/api/Details.md index 66b52409..c50378c5 100644 --- a/docs/api/Details.md +++ b/docs/api/Details.md @@ -1,89 +1,132 @@ # 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= +``` xml +https://nominatim.openstreetmap.org/details?osmtype=[N|W|R]&osmid=&class= ``` -Both parameters are required, the type is one of node(N), way(W) or relation(R). +`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= +``` -Or +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. -``` - https://nominatim.openstreetmap.org/details?placeid= -``` +!!! 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. -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. +## Parameters -Additional optional parameters are explained below. +This section lists additional optional parameters. ### Output format -* `format=[html|json]` +| Parameter | Value | Default | +|-----------| ----- | ------- | +| json_callback | function name | _unset_ | -See [Place Output Formats](Output.md) for details on each format. (Default: html) +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. -* `json_callback=` +| Parameter | Value | Default | +|-----------| ----- | ------- | +| pretty | 0 or 1 | 0 | -Wrap json output in a callback function (JSONP) i.e. `()`. -Only has an effect for JSON output formats. +`[PHP-only]` Add indentation to the output to make it more human-readable. -* `pretty=[0|1]` -For JSON output will add indentation to make it more human-readable. (Default: 0) +### Output details +| Parameter | Value | Default | +|-----------| ----- | ------- | +| addressdetails | 0 or 1 | 0 | -### Output details +When set to 1, include a breakdown of the address into elements. -* `addressdetails=[0|1]` +| Parameter | Value | Default | +|-----------| ----- | ------- | +| keywords | 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 list of name keywords and address keywords +in the result. -* `keywords=[0|1]` +| Parameter | Value | Default | +|-----------| ----- | ------- | +| linkedplaces | 0 or 1 | 1 | -Include a list of name keywords and address keywords (word ids). (Default: 0) +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. -* `linkedplaces=[0|1]` +| Parameter | Value | Default | +|-----------| ----- | ------- | +| hierarchy | 0 or 1 | 0 | -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 lower in the address hierarchy. -* `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. -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) +| Parameter | Value | Default | +|-----------| ----- | ------- | +| group_hierarchy | 0 or 1 | 0 | -* `group_hierarchy=[0|1]` +When set to 1, the output of the address hierarchy will be +grouped by type. -For JSON output will group the places by type. (Default: 0) +| Parameter | Value | Default | +|-----------| ----- | ------- | +| polygon_geojson | 0 or 1 | 0 | -* `polygon_geojson=[0|1]` -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](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.php?osmtype=W&osmid=38210407&format=json)