]> git.openstreetmap.org Git - nominatim.git/blob - docs/api/Details.md
Merge remote-tracking branch 'upstream/master'
[nominatim.git] / docs / api / Details.md
1 # Place details
2
3 Show all details about a single place saved in the database.
4
5 !!! warning
6     The details page exists for debugging only. You may not use it in scripts
7     or to automatically query details about a result.
8     See [Nominatim Usage Policy](https://operations.osmfoundation.org/policies/nominatim/).
9
10
11 ## Parameters
12
13 The details API supports the following two request formats:
14
15 ``` xml
16 https://nominatim.openstreetmap.org/details?osmtype=[N|W|R]&osmid=<value>&class=<value>
17 ```
18
19 `osmtype` and `osmid` are required parameters. The type is one of node (N), way (W)
20 or relation (R). The id must be a number. The `class` parameter is optional and
21 allows to distinguish between entries, when the corresponding OSM object has more
22 than one main tag. For example, when a place is tagged with `tourism=hotel` and
23 `amenity=restaurant`, there will be two place entries in Nominatim, one for a
24 restaurant, one for a hotel. You need to specify `class=tourism` or `class=amentity`
25 to get exactly the one you want. If there are multiple places in the database
26 but the `class` parameter is left out, then one of the places will be chosen
27 at random and displayed.
28
29 ``` xml
30 https://nominatim.openstreetmap.org/details?place_id=<value>
31 ```
32
33 Place IDs are assigned sequentially during Nominatim data import. The ID
34 for a place is different between Nominatim installation (servers) and
35 changes when data gets reimported. Therefore it cannot be used as
36 a permanent id and shouldn't be used in bug reports.
37
38
39 Additional optional parameters are explained below.
40
41 ### Output format
42
43 * `json_callback=<string>`
44
45 Wrap JSON output in a callback function (JSONP) i.e. `<string>(<json>)`.
46
47 * `pretty=[0|1]`
48
49 Add indentation to make it more human-readable. (Default: 0)
50
51
52 ### Output details
53
54 * `addressdetails=[0|1]`
55
56 Include a breakdown of the address into elements. (Default: 0)
57
58 * `keywords=[0|1]`
59
60 Include a list of name keywords and address keywords (word ids). (Default: 0)
61
62 * `linkedplaces=[0|1]`
63
64 Include a details of places that are linked with this one. Places get linked
65 together when they are different forms of the same physical object. Nominatim
66 links two kinds of objects together: place nodes get linked with the
67 corresponding administrative boundaries. Waterway relations get linked together with their
68 members.
69 (Default: 1)
70
71 * `hierarchy=[0|1]`
72
73 Include details of places lower in the address hierarchy. (Default: 0)
74
75 * `group_hierarchy=[0|1]`
76
77 For JSON output will group the places by type. (Default: 0)
78
79 * `polygon_geojson=[0|1]`
80
81 Include geometry of result. (Default: 0)
82
83 ### Language of results
84
85 * `accept-language=<browser language string>`
86
87 Preferred language order for showing result, overrides the value
88 specified in the "Accept-Language" HTTP header.
89 Either use a standard RFC2616 accept-language string or a simple
90 comma-separated list of language codes.
91
92
93 ## Examples
94
95 ##### JSON
96
97 [https://nominatim.openstreetmap.org/details.php?osmtype=W&osmid=38210407&format=json](https://nominatim.openstreetmap.org/details.php?osmtype=W&osmid=38210407&format=json)
98
99
100 ```json
101 {
102   "place_id": 85993608,
103   "parent_place_id": 72765313,
104   "osm_type": "W",
105   "osm_id": 38210407,
106   "category": "place",
107   "type": "square",
108   "admin_level": "15",
109   "localname": "Pariser Platz",
110   "names": {
111     "name": "Pariser Platz",
112     "name:be": "Парыжская плошча",
113     "name:de": "Pariser Platz",
114     "name:es": "Plaza de París",
115     "name:he": "פאריזר פלאץ",
116     "name:ko": "파리저 광장",
117     "name:la": "Forum Parisinum",
118     "name:ru": "Парижская площадь",
119     "name:uk": "Паризька площа",
120     "name:zh": "巴黎廣場"
121   },
122   "addresstags": {
123     "postcode": "10117"
124   },
125   "housenumber": null,
126   "calculated_postcode": "10117",
127   "country_code": "de",
128   "indexed_date": "2018-08-18T17:02:45+00:00",
129   "importance": 0.339401620591472,
130   "calculated_importance": 0.339401620591472,
131   "extratags": {
132     "wikidata": "Q156716",
133     "wikipedia": "de:Pariser Platz"
134   },
135   "calculated_wikipedia": "de:Pariser_Platz",
136   "rank_address": 30,
137   "rank_search": 30,
138   "isarea": true,
139   "centroid": {
140     "type": "Point",
141     "coordinates": [
142       13.3786822618517,
143       52.5163654
144     ]
145   },
146   "geometry": {
147     "type": "Point",
148     "coordinates": [
149       13.3786822618517,
150       52.5163654
151     ]
152   }
153 }
154 ```