]> git.openstreetmap.org Git - nominatim.git/blob - docs/api/Details.md
Merge pull request #3321 from lonvia/remove-duplicate-partials
[nominatim.git] / 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 ```