# 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=<value>&class=<value>
```
- https://nominatim.openstreetmap.org/details?osmtype=[N|W|R]&osmid=<value>
-```
-
-Both parameters are required, the type is one of node(N), way(W) or relation(R).
-Or
-
-```
- https://nominatim.openstreetmap.org/details?placeid=<value>
+`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=<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
-* `format=[html|json]`
-
-See [Place Output Formats](Output.md) for details on each format. (Default: html)
-
-* `json_callback=<string>`
+## Parameters
-Wrap json output in a callback function (JSONP) i.e. `<string>(<json>)`.
-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=<browser language string>`
+| 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)
+[https://nominatim.openstreetmap.org/details?osmtype=W&osmid=38210407&format=json](https://nominatim.openstreetmap.org/details?osmtype=W&osmid=38210407&format=json)
```json
projects / nominatim.git / blobdiff