docs/api/Details.md

   1 # Place details
   2
   3 Show all details about a single place saved in the database.
   4
   5 This API endpoint is meant for visual inspection of the data in the database
   6 and is meant for use with [Nominatim-UI](https://github.com/osm-search/nominatim-ui/).
   7 The parameters of the endpoint and the output may change occasionally between
   8 versions of Nominatim. Do not rely on the output in scripts or applications.
   9
  10
  11 !!! warning
  12     The details endpoint at https://nominatim.openstreetmap.org
  13     may not used in scripts or bots at all.
  14     See [Nominatim Usage Policy](https://operations.osmfoundation.org/policies/nominatim/).
  15
  16
  17
  18 The details API supports the following two request formats:
  19
  20 ``` xml
  21 https://nominatim.openstreetmap.org/details?osmtype=[N|W|R]&osmid=<value>&class=<value>
  22 ```
  23
  24 `osmtype` and `osmid` are required parameters. The type is one of node (N), way (W)
  25 or relation (R). The id must be a number. The `class` parameter is optional and
  26 allows to distinguish between entries, when the corresponding OSM object has more
  27 than one main tag. For example, when a place is tagged with `tourism=hotel` and
  28 `amenity=restaurant`, there will be two place entries in Nominatim, one for a
  29 restaurant, one for a hotel. You need to specify `class=tourism` or `class=amentity`
  30 to get exactly the one you want. If there are multiple places in the database
  31 but the `class` parameter is left out, then one of the places will be chosen
  32 at random and displayed.
  33
  34 ``` xml
  35 https://nominatim.openstreetmap.org/details?place_id=<value>
  36 ```
  37
  38 Place IDs are assigned sequentially during Nominatim data import. The ID
  39 for a place is different between Nominatim installation (servers) and
  40 changes when data gets reimported. Therefore it cannot be used as
  41 a permanent id and shouldn't be used in bug reports.
  42
  43 !!! danger "Deprecation warning"
  44     The API can also be used with the URL
  45     `https://nominatim.openstreetmap.org/details.php`. This is now deprecated
  46     and will be removed in future versions.
  47
  48
  49 ## Parameters
  50
  51 This section lists additional optional parameters.
  52
  53 ### Output format
  54
  55 | Parameter | Value | Default |
  56 |-----------| ----- | ------- |
  57 | json_callback | function name | _unset_ |
  58
  59 When given, then JSON output will be wrapped in a callback function with
  60 the given name. See [JSONP](https://en.wikipedia.org/wiki/JSONP) for more
  61 information.
  62
  63 | Parameter | Value | Default |
  64 |-----------| ----- | ------- |
  65 | pretty    | 0 or 1 | 0 |
  66
  67 `[PHP-only]` Add indentation to the output to make it more human-readable.
  68
  69
  70 ### Output details
  71
  72 | Parameter | Value | Default |
  73 |-----------| ----- | ------- |
  74 | addressdetails | 0 or 1 | 0 |
  75
  76 When set to 1, include a breakdown of the address into elements.
  77
  78 | Parameter | Value | Default |
  79 |-----------| ----- | ------- |
  80 | keywords  | 0 or 1 | 0 |
  81
  82 When set to 1, include a list of name keywords and address keywords
  83 in the result.
  84
  85 | Parameter | Value | Default |
  86 |-----------| ----- | ------- |
  87 | linkedplaces  | 0 or 1 | 1 |
  88
  89 Include details of places that are linked with this one. Places get linked
  90 together when they are different forms of the same physical object. Nominatim
  91 links two kinds of objects together: place nodes get linked with the
  92 corresponding administrative boundaries. Waterway relations get linked together with their
  93 members.
  94
  95 | Parameter | Value | Default |
  96 |-----------| ----- | ------- |
  97 | hierarchy  | 0 or 1 | 0 |
  98
  99 Include details of places lower in the address hierarchy.
 100
 101 `[Python-only]` will only return properly parented places. These are address
 102 or POI-like places that reuse the address of their parent street or place.
 103
 104 | Parameter | Value | Default |
 105 |-----------| ----- | ------- |
 106 | group_hierarchy  | 0 or 1 | 0 |
 107
 108 When set to 1, the output of the address hierarchy will be
 109 grouped by type.
 110
 111 | Parameter | Value  | Default |
 112 |-----------| -----  | ------- |
 113 | polygon_geojson | 0 or 1 | 0 |
 114
 115
 116 Include geometry of result.
 117
 118 ### Language of results
 119
 120 | Parameter | Value | Default |
 121 |-----------| ----- | ------- |
 122 | accept-language | browser language string | content of "Accept-Language" HTTP header |
 123
 124 Preferred language order for showing search results. This may either be
 125 a simple comma-separated list of language codes or have the same format
 126 as the ["Accept-Language" HTTP header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language).
 127
 128
 129 ## Examples
 130
 131 ##### JSON
 132
 133 [https://nominatim.openstreetmap.org/details.php?osmtype=W&osmid=38210407&format=json](https://nominatim.openstreetmap.org/details.php?osmtype=W&osmid=38210407&format=json)
 134
 135
 136 ```json
 137 {
 138   "place_id": 85993608,
 139   "parent_place_id": 72765313,
 140   "osm_type": "W",
 141   "osm_id": 38210407,
 142   "category": "place",
 143   "type": "square",
 144   "admin_level": "15",
 145   "localname": "Pariser Platz",
 146   "names": {
 147     "name": "Pariser Platz",
 148     "name:be": "Парыжская плошча",
 149     "name:de": "Pariser Platz",
 150     "name:es": "Plaza de París",
 151     "name:he": "פאריזר פלאץ",
 152     "name:ko": "파리저 광장",
 153     "name:la": "Forum Parisinum",
 154     "name:ru": "Парижская площадь",
 155     "name:uk": "Паризька площа",
 156     "name:zh": "巴黎廣場"
 157   },
 158   "addresstags": {
 159     "postcode": "10117"
 160   },
 161   "housenumber": null,
 162   "calculated_postcode": "10117",
 163   "country_code": "de",
 164   "indexed_date": "2018-08-18T17:02:45+00:00",
 165   "importance": 0.339401620591472,
 166   "calculated_importance": 0.339401620591472,
 167   "extratags": {
 168     "wikidata": "Q156716",
 169     "wikipedia": "de:Pariser Platz"
 170   },
 171   "calculated_wikipedia": "de:Pariser_Platz",
 172   "rank_address": 30,
 173   "rank_search": 30,
 174   "isarea": true,
 175   "centroid": {
 176     "type": "Point",
 177     "coordinates": [
 178       13.3786822618517,
 179       52.5163654
 180     ]
 181   },
 182   "geometry": {
 183     "type": "Point",
 184     "coordinates": [
 185       13.3786822618517,
 186       52.5163654
 187     ]
 188   }
 189 }
 190 ```