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 ### Output details
  63
  64 | Parameter | Value | Default |
  65 |-----------| ----- | ------- |
  66 | addressdetails | 0 or 1 | 0 |
  67
  68 When set to 1, include a breakdown of the address into elements.
  69
  70 | Parameter | Value | Default |
  71 |-----------| ----- | ------- |
  72 | keywords  | 0 or 1 | 0 |
  73
  74 When set to 1, include a list of name keywords and address keywords
  75 in the result.
  76
  77 | Parameter | Value | Default |
  78 |-----------| ----- | ------- |
  79 | linkedplaces  | 0 or 1 | 1 |
  80
  81 Include details of places that are linked with this one. Places get linked
  82 together when they are different forms of the same physical object. Nominatim
  83 links two kinds of objects together: place nodes get linked with the
  84 corresponding administrative boundaries. Waterway relations get linked together with their
  85 members.
  86
  87 | Parameter | Value | Default |
  88 |-----------| ----- | ------- |
  89 | hierarchy  | 0 or 1 | 0 |
  90
  91 Include details of POIs and address that depend on the place. Only POIs
  92 that use this place to determine their address will be returned.
  93
  94 | Parameter | Value | Default |
  95 |-----------| ----- | ------- |
  96 | group_hierarchy  | 0 or 1 | 0 |
  97
  98 When set to 1, the output of the address hierarchy will be
  99 grouped by type.
 100
 101 | Parameter | Value  | Default |
 102 |-----------| -----  | ------- |
 103 | polygon_geojson | 0 or 1 | 0 |
 104
 105
 106 Include geometry of result.
 107
 108 ### Language of results
 109
 110 | Parameter | Value | Default |
 111 |-----------| ----- | ------- |
 112 | accept-language | browser language string | content of "Accept-Language" HTTP header |
 113
 114 Preferred language order for showing search results. This may either be
 115 a simple comma-separated list of language codes or have the same format
 116 as the ["Accept-Language" HTTP header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language).
 117
 118
 119 ## Examples
 120
 121 ##### JSON
 122
 123 [https://nominatim.openstreetmap.org/details?osmtype=W&osmid=38210407&format=json](https://nominatim.openstreetmap.org/details?osmtype=W&osmid=38210407&format=json)
 124
 125
 126 ```json
 127 {
 128   "place_id": 85993608,
 129   "parent_place_id": 72765313,
 130   "osm_type": "W",
 131   "osm_id": 38210407,
 132   "category": "place",
 133   "type": "square",
 134   "admin_level": "15",
 135   "localname": "Pariser Platz",
 136   "names": {
 137     "name": "Pariser Platz",
 138     "name:be": "Парыжская плошча",
 139     "name:de": "Pariser Platz",
 140     "name:es": "Plaza de París",
 141     "name:he": "פאריזר פלאץ",
 142     "name:ko": "파리저 광장",
 143     "name:la": "Forum Parisinum",
 144     "name:ru": "Парижская площадь",
 145     "name:uk": "Паризька площа",
 146     "name:zh": "巴黎廣場"
 147   },
 148   "addresstags": {
 149     "postcode": "10117"
 150   },
 151   "housenumber": null,
 152   "calculated_postcode": "10117",
 153   "country_code": "de",
 154   "indexed_date": "2018-08-18T17:02:45+00:00",
 155   "importance": 0.339401620591472,
 156   "calculated_importance": 0.339401620591472,
 157   "extratags": {
 158     "wikidata": "Q156716",
 159     "wikipedia": "de:Pariser Platz"
 160   },
 161   "calculated_wikipedia": "de:Pariser_Platz",
 162   "rank_address": 30,
 163   "rank_search": 30,
 164   "isarea": true,
 165   "centroid": {
 166     "type": "Point",
 167     "coordinates": [
 168       13.3786822618517,
 169       52.5163654
 170     ]
 171   },
 172   "geometry": {
 173     "type": "Point",
 174     "coordinates": [
 175       13.3786822618517,
 176       52.5163654
 177     ]
 178   }
 179 }
 180 ```