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