]> git.openstreetmap.org Git - nominatim.git/blob - docs/api/Search.md
Merge pull request #2865 from Romeo-PHILLIPS/fix/documentation_status_code
[nominatim.git] / docs / api / Search.md
1 # Search queries
2
3 The search API allows you to look up a location from a textual description
4 or address. Nominatim supports structured and free-form search queries.
5
6 The search query may also contain
7 [special phrases](https://wiki.openstreetmap.org/wiki/Nominatim/Special_Phrases)
8 which are translated into specific OpenStreetMap (OSM) tags (e.g. Pub => `amenity=pub`).
9 This can be used to narrow down the kind of objects to be returned.
10
11 !!! warning
12     Special phrases are not suitable to query all objects of a certain type in an
13     area. Nominatim will always just return a collection of the best matches. To
14     download OSM data by object type, use the [Overpass API](https://overpass-api.de/).
15
16 ## Parameters
17
18 The search API has the following format:
19
20 ```
21    https://nominatim.openstreetmap.org/search?<params>
22 ```
23
24 The search term may be specified with two different sets of parameters:
25
26 * `q=<query>`
27
28     Free-form query string to search for.
29     Free-form queries are processed first left-to-right and then right-to-left if that fails. So you may search for
30     [pilkington avenue, birmingham](https://nominatim.openstreetmap.org/search?q=pilkington+avenue,birmingham) as well as for
31     [birmingham, pilkington avenue](https://nominatim.openstreetmap.org/search?q=birmingham,+pilkington+avenue).
32     Commas are optional, but improve performance by reducing the complexity of the search.
33
34
35 * `street=<housenumber> <streetname>`
36 * `city=<city>`
37 * `county=<county>`
38 * `state=<state>`
39 * `country=<country>`
40 * `postalcode=<postalcode>`
41
42     Alternative query string format split into several parameters for structured requests.
43     Structured requests are faster but are less robust against alternative
44     OSM tagging schemas. **Do not combine with** `q=<query>` **parameter**.
45
46 Both query forms accept the additional parameters listed below.
47
48 ### Output format
49
50 * `format=[xml|json|jsonv2|geojson|geocodejson]`
51
52 See [Place Output Formats](Output.md) for details on each format. (Default: jsonv2)
53
54 !!! note
55     The Nominatim service at
56     [https://nominatim.openstreetmap.org](https://nominatim.openstreetmap.org)
57     has a different default behaviour for historical reasons. When the
58     `format` parameter is omitted, the request will be forwarded to the Web UI.
59
60 * `json_callback=<string>`
61
62 Wrap JSON output in a callback function ([JSONP](https://en.wikipedia.org/wiki/JSONP)) i.e. `<string>(<json>)`.
63 Only has an effect for JSON output formats.
64
65 ### Output details
66
67 * `addressdetails=[0|1]`
68
69 Include a breakdown of the address into elements. (Default: 0)
70
71
72 * `extratags=[0|1]`
73
74 Include additional information in the result if available,
75 e.g. wikipedia link, opening hours. (Default: 0)
76
77
78 * `namedetails=[0|1]`
79
80 Include a list of alternative names in the results. These may include
81 language variants, references, operator and brand. (Default: 0)
82
83
84 ### Language of results
85
86 * `accept-language=<browser language string>`
87
88 Preferred language order for showing search results, overrides the value
89 specified in the ["Accept-Language" HTTP header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language).
90 Either use a standard RFC2616 accept-language string or a simple
91 comma-separated list of language codes.
92
93 ### Result limitation
94
95 * `countrycodes=<countrycode>[,<countrycode>][,<countrycode>]...`
96
97 Limit search results to one or more countries. `<countrycode>` must be the
98 [ISO 3166-1alpha2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) code,
99 e.g. `gb` for the United Kingdom, `de` for Germany.
100
101 Each place in Nominatim is assigned to one country code based
102 on OSM country boundaries. In rare cases a place may not be in any country
103 at all, for example, in international waters.
104
105 * `exclude_place_ids=<place_id,[place_id],[place_id]`
106
107 If you do not want certain OSM objects to appear in the search
108 result, give a comma separated list of the `place_id`s you want to skip.
109 This can be used to retrieve additional search results. For example, if a
110 previous query only returned a few results, then including those here would
111 cause the search to return other, less accurate, matches (if possible).
112
113
114 * `limit=<integer>`
115
116 Limit the number of returned results. (Default: 10, Maximum: 50)
117
118
119 * `viewbox=<x1>,<y1>,<x2>,<y2>`
120
121 The preferred area to find search results. Any two corner points of the box
122 are accepted as long as they span a real box. `x` is longitude,
123 `y` is latitude.
124
125
126 * `bounded=[0|1]`
127
128 When a viewbox is given, restrict the result to items contained within that
129 viewbox (see above). When `viewbox` and `bounded=1` are given, an amenity
130 only search is allowed. Give the special keyword for the amenity in square
131 brackets, e.g. `[pub]` and a selection of objects of this type is returned.
132 There is no guarantee that the result is complete. (Default: 0)
133
134
135 ### Polygon output
136
137 * `polygon_geojson=1`
138 * `polygon_kml=1`
139 * `polygon_svg=1`
140 * `polygon_text=1`
141
142 Output geometry of results as a GeoJSON, KML, SVG or WKT. Only one of these
143 options can be used at a time. (Default: 0)
144
145 * `polygon_threshold=0.0`
146
147 Return a simplified version of the output geometry. The parameter is the
148 tolerance in degrees with which the geometry may differ from the original
149 geometry. Topology is preserved in the result. (Default: 0.0)
150
151 ### Other
152
153 * `email=<valid email address>`
154
155 If you are making large numbers of request please include an appropriate email
156 address to identify your requests. See Nominatim's [Usage Policy](https://operations.osmfoundation.org/policies/nominatim/) for more details.
157
158 * `dedupe=[0|1]`
159
160 Sometimes you have several objects in OSM identifying the same place or
161 object in reality. The simplest case is a street being split into many
162 different OSM ways due to different characteristics. Nominatim will
163 attempt to detect such duplicates and only return one match unless
164 this parameter is set to 0. (Default: 1)
165
166 * `debug=[0|1]`
167
168 Output assorted developer debug information. Data on internals of Nominatim's
169 "Search Loop" logic, and SQL queries. The output is (rough) HTML format.
170 This overrides the specified machine readable format. (Default: 0)
171
172
173
174 ## Examples
175
176
177 ##### XML with kml polygon
178
179 * [https://nominatim.openstreetmap.org/search?q=135+pilkington+avenue,+birmingham&format=xml&polygon_geojson=1&addressdetails=1](https://nominatim.openstreetmap.org/search?q=135+pilkington+avenue,+birmingham&format=xml&polygon_geojson=1&addressdetails=1)
180
181 ```xml
182   <searchresults timestamp="Sat, 07 Nov 09 14:42:10 +0000" querystring="135 pilkington, avenue birmingham" polygon="true">
183     <place
184       place_id="1620612" osm_type="node" osm_id="452010817"
185       boundingbox="52.548641204834,52.5488433837891,-1.81612110137939,-1.81592094898224"
186       lat="52.5487429714954" lon="-1.81602098644987"
187       display_name="135, Pilkington Avenue, Wylde Green, City of Birmingham, West Midlands (county), B72, United Kingdom"
188       class="place" type="house">
189       <geokml>
190         <Polygon>
191           <outerBoundaryIs>
192             <LinearRing>
193               <coordinates>-1.816513,52.548756599999997 -1.816434,52.548747300000002 -1.816429,52.5487629 -1.8163717,52.548756099999999 -1.8163464,52.548834599999999 -1.8164599,52.548848100000001 -1.8164685,52.5488213 -1.8164913,52.548824000000003 -1.816513,52.548756599999997</coordinates>
194             </LinearRing>
195           </outerBoundaryIs>
196         </Polygon>
197       </geokml>
198       <house_number>135</house_number>
199       <road>Pilkington Avenue</road>
200       <village>Wylde Green</village>
201       <town>Sutton Coldfield</town>
202       <city>City of Birmingham</city>
203       <county>West Midlands (county)</county>
204       <postcode>B72</postcode>
205       <country>United Kingdom</country>
206       <country_code>gb</country_code>
207     </place>
208   </searchresults>
209 ```
210
211 ##### JSON with SVG polygon
212
213 [https://nominatim.openstreetmap.org/search/Unter%20den%20Linden%201%20Berlin?format=json&addressdetails=1&limit=1&polygon_svg=1](https://nominatim.openstreetmap.org/search/Unter%20den%20Linden%201%20Berlin?format=json&addressdetails=1&limit=1&polygon_svg=1)
214
215 ```json
216     {
217         "address": {
218             "city": "Berlin",
219             "city_district": "Mitte",
220             "construction": "Unter den Linden",
221             "continent": "European Union",
222             "country": "Deutschland",
223             "country_code": "de",
224             "house_number": "1",
225             "neighbourhood": "Scheunenviertel",
226             "postcode": "10117",
227             "public_building": "Kommandantenhaus",
228             "state": "Berlin",
229             "suburb": "Mitte"
230         },
231         "boundingbox": [
232             "52.5170783996582",
233             "52.5173187255859",
234             "13.3975105285645",
235             "13.3981599807739"
236         ],
237         "class": "amenity",
238         "display_name": "Kommandantenhaus, 1, Unter den Linden, Scheunenviertel, Mitte, Berlin, 10117, Deutschland, European Union",
239         "importance": 0.73606775332943,
240         "lat": "52.51719785",
241         "licence": "Data \u00a9 OpenStreetMap contributors, ODbL 1.0. https://www.openstreetmap.org/copyright",
242         "lon": "13.3978352028938",
243         "osm_id": "15976890",
244         "osm_type": "way",
245         "place_id": "30848715",
246         "svg": "M 13.397511 -52.517283599999999 L 13.397829400000001 -52.517299800000004 13.398131599999999 -52.517315099999998 13.398159400000001 -52.517112099999999 13.3975388 -52.517080700000001 Z",
247         "type": "public_building"
248     }
249 ```
250
251 ##### JSON with address details
252
253 [https://nominatim.openstreetmap.org/?addressdetails=1&q=bakery+in+berlin+wedding&format=json&limit=1](https://nominatim.openstreetmap.org/?addressdetails=1&q=bakery+in+berlin+wedding&format=json&limit=1)
254
255 ```json
256     {
257         "address": {
258             "bakery": "B\u00e4cker Kamps",
259             "city_district": "Mitte",
260             "continent": "European Union",
261             "country": "Deutschland",
262             "country_code": "de",
263             "footway": "Bahnsteig U6",
264             "neighbourhood": "Sprengelkiez",
265             "postcode": "13353",
266             "state": "Berlin",
267             "suburb": "Wedding"
268         },
269         "boundingbox": [
270             "52.5460929870605",
271             "52.5460968017578",
272             "13.3591794967651",
273             "13.3591804504395"
274         ],
275         "class": "shop",
276         "display_name": "B\u00e4cker Kamps, Bahnsteig U6, Sprengelkiez, Wedding, Mitte, Berlin, 13353, Deutschland, European Union",
277         "icon": "https://nominatim.openstreetmap.org/images/mapicons/shopping_bakery.p.20.png",
278         "importance": 0.201,
279         "lat": "52.5460941",
280         "licence": "Data \u00a9 OpenStreetMap contributors, ODbL 1.0. https://www.openstreetmap.org/copyright",
281         "lon": "13.35918",
282         "osm_id": "317179427",
283         "osm_type": "node",
284         "place_id": "1453068",
285         "type": "bakery"
286     }
287 ```
288
289 ##### GeoJSON
290
291 [https://nominatim.openstreetmap.org/search?q=17+Strada+Pictor+Alexandru+Romano%2C+Bukarest&format=geojson](https://nominatim.openstreetmap.org/search?q=17+Strada+Pictor+Alexandru+Romano%2C+Bukarest&format=geojson)
292
293 ```json
294 {
295   "type": "FeatureCollection",
296   "licence": "Data © OpenStreetMap contributors, ODbL 1.0. https://osm.org/copyright",
297   "features": [
298     {
299       "type": "Feature",
300       "properties": {
301         "place_id": "35811445",
302         "osm_type": "node",
303         "osm_id": "2846295644",
304         "display_name": "17, Strada Pictor Alexandru Romano, Bukarest, Bucharest, Sector 2, Bucharest, 023964, Romania",
305         "place_rank": "30",
306         "category": "place",
307         "type": "house",
308         "importance": 0.62025
309       },
310       "bbox": [
311         26.1156689,
312         44.4354754,
313         26.1157689,
314         44.4355754
315       ],
316       "geometry": {
317         "type": "Point",
318         "coordinates": [
319           26.1157189,
320           44.4355254
321         ]
322       }
323     }
324   ]
325 }
326 ```
327
328 ##### GeocodeJSON
329
330 [https://nominatim.openstreetmap.org/search?q=%CE%91%CE%B3%CE%AF%CE%B1+%CE%A4%CF%81%CE%B9%CE%AC%CE%B4%CE%B1%2C+%CE%91%CE%B4%CF%89%CE%BD%CE%B9%CE%B4%CE%BF%CF%82%2C+Athens%2C+Greece&format=geocodejson](https://nominatim.openstreetmap.org/search?q=%CE%91%CE%B3%CE%AF%CE%B1+%CE%A4%CF%81%CE%B9%CE%AC%CE%B4%CE%B1%2C+%CE%91%CE%B4%CF%89%CE%BD%CE%B9%CE%B4%CE%BF%CF%82%2C+Athens%2C+Greece&format=geocodejson)
331
332 ```json
333 {
334   "type": "FeatureCollection",
335   "geocoding": {
336     "version": "0.1.0",
337     "attribution": "Data © OpenStreetMap contributors, ODbL 1.0. https://osm.org/copyright",
338     "licence": "ODbL",
339     "query": "Αγία Τριάδα, Αδωνιδος, Athens, Greece"
340   },
341   "features": [
342     {
343       "type": "Feature",
344       "properties": {
345         "geocoding": {
346           "type": "place_of_worship",
347           "label": "Αγία Τριάδα, Αδωνιδος, Άγιος Νικόλαος, 5º Δημοτικό Διαμέρισμα Αθηνών, Athens, Municipality of Athens, Regional Unit of Central Athens, Region of Attica, Attica, 11472, Greece",
348           "name": "Αγία Τριάδα",
349           "admin": null
350         }
351       },
352       "geometry": {
353         "type": "Point",
354         "coordinates": [
355           23.72949633941,
356           38.0051697
357         ]
358       }
359     }
360   ]
361 }
362 ```