# 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) is there for debugging only and may 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 has the following two formats:
-```
- https://nominatim.openstreetmap.org/details?osmtype=[N|W|R]&osmid=<value>
+The details API supports the following two request formats:
+
+``` xml
+https://nominatim.openstreetmap.org/details?osmtype=[N|W|R]&osmid=<value>&class=<value>
```
-Both parameters are mandatory, the type is one of node(N), way(W) or relation(R). Up to 50 ids
-can be queried at the same time.
+`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>
+```
-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=<value>
-```
+!!! 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.
-The placeid created assigned sequentially during Nominatim data import. It is different between 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=<string>`
+| Parameter | Value | Default |
+|-----------| ----- | ------- |
+| pretty | 0 or 1 | 0 |
-Wrap json output in a callback function (JSONP) i.e. `<string>(<json>)`.
-Only has an effect for JSON output formats.
+`[PHP-only]` Add indentation to the output to make it more human-readable.
-* `pretty=[0,1]`
-Add indentation to JSON output to make it the output 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 which are 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 which are lower in the address hierarchy. E.g. for a city this usually a list of suburbs, rivers, streets. (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=<browser language string>`
+| Parameter | Value | Default |
+|-----------| ----- | ------- |
+| accept-language | browser language string | content of "Accept-Language" HTTP header |
-Preferred language order for showing search results, 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.php?osmtype=W&osmid=38210407&format=json](https://nominatim.openstreetmap.org/details.php?osmtype=W&osmid=38210407&format=json)
```json
projects / nominatim.git / blobdiff