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