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 * `amenity=<name and/or type of POI>`
  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_kml=1&addressdetails=1](https://nominatim.openstreetmap.org/search?q=135+pilkington+avenue,+birmingham&format=xml&polygon_kml=1&addressdetails=1)
 180
 181 ```xml
 182 <?xml version="1.0" encoding="UTF-8" ?>
 183 <searchresults timestamp="Tue, 08 Aug 2023 15:45:41 +00:00"
 184                attribution="Data © OpenStreetMap contributors, ODbL 1.0. http://osm.org/copyright"
 185                querystring="135 pilkington avenue, birmingham"
 186                more_url="https://nominatim.openstreetmap.org/search?q=135+pilkington+avenue%2C+birmingham&amp;polygon_kml=1&amp;addressdetails=1&amp;limit=20&amp;exclude_place_ids=125279639&amp;format=xml"
 187                exclude_place_ids="125279639">
 188   <place place_id="125279639"
 189          osm_type="way"
 190          osm_id="90394480"
 191          lat="52.5487921"
 192          lon="-1.8164308"
 193          boundingbox="52.5487473,52.5488481,-1.8165130,-1.8163464"
 194          place_rank="30"
 195          address_rank="30"
 196          display_name="135, Pilkington Avenue, Maney, Sutton Coldfield, Wylde Green, Birmingham, West Midlands Combined Authority, England, B72 1LH, United Kingdom"
 197          class="building"
 198          type="residential"
 199          importance="9.999999994736442e-08">
 200     <geokml>
 201       <Polygon>
 202         <outerBoundaryIs>
 203           <LinearRing>
 204             <coordinates>-1.816513,52.5487566 -1.816434,52.5487473 -1.816429,52.5487629 -1.8163717,52.5487561 -1.8163464,52.5488346 -1.8164599,52.5488481 -1.8164685,52.5488213 -1.8164913,52.548824 -1.816513,52.5487566</coordinates>
 205           </LinearRing>
 206         </outerBoundaryIs>
 207       </Polygon>
 208     </geokml>
 209     <house_number>135</house_number>
 210     <road>Pilkington Avenue</road>
 211     <hamlet>Maney</hamlet>
 212     <town>Sutton Coldfield</town>
 213     <village>Wylde Green</village>
 214     <city>Birmingham</city>
 215     <ISO3166-2-lvl8>GB-BIR</ISO3166-2-lvl8>
 216     <state_district>West Midlands Combined Authority</state_district>
 217     <state>England</state>
 218     <ISO3166-2-lvl4>GB-ENG</ISO3166-2-lvl4>
 219     <postcode>B72 1LH</postcode>
 220     <country>United Kingdom</country>
 221     <country_code>gb</country_code>
 222   </place>
 223 </searchresults>
 224 ```
 225
 226 ##### JSON with SVG polygon
 227
 228 [https://nominatim.openstreetmap.org/search?q=Unter%20den%20Linden%201%20Berlin&format=json&addressdetails=1&limit=1&polygon_svg=1](https://nominatim.openstreetmap.org/search?q=Unter%20den%20Linden%201%20Berlin&format=json&addressdetails=1&limit=1&polygon_svg=1)
 229
 230 ```json
 231 [
 232   {
 233     "address": {
 234       "ISO3166-2-lvl4": "DE-BE",
 235       "borough": "Mitte",
 236       "city": "Berlin",
 237       "country": "Deutschland",
 238       "country_code": "de",
 239       "historic": "Kommandantenhaus",
 240       "house_number": "1",
 241       "neighbourhood": "Friedrichswerder",
 242       "postcode": "10117",
 243       "road": "Unter den Linden",
 244       "suburb": "Mitte"
 245     },
 246     "boundingbox": [
 247       "52.5170798",
 248       "52.5173311",
 249       "13.3975116",
 250       "13.3981577"
 251     ],
 252     "class": "historic",
 253     "display_name": "Kommandantenhaus, 1, Unter den Linden, Friedrichswerder, Mitte, Berlin, 10117, Deutschland",
 254     "importance": 0.8135042058306902,
 255     "lat": "52.51720765",
 256     "licence": "Data © OpenStreetMap contributors, ODbL 1.0. https://osm.org/copyright",
 257     "lon": "13.397834399325466",
 258     "osm_id": 15976890,
 259     "osm_type": "way",
 260     "place_id": 108681845,
 261     "svg": "M 13.3975116 -52.5172905 L 13.397549 -52.5170798 13.397715 -52.5170906 13.3977122 -52.5171064 13.3977392 -52.5171086 13.3977417 -52.5170924 13.3979655 -52.5171069 13.3979623 -52.5171233 13.3979893 -52.5171248 13.3979922 -52.5171093 13.3981577 -52.5171203 13.398121 -52.5173311 13.3978115 -52.5173103 Z",
 262     "type": "house"
 263   }
 264 ]
 265 ```
 266
 267 ##### JSON with address details
 268
 269 [https://nominatim.openstreetmap.org/search?addressdetails=1&q=bakery+in+berlin+wedding&format=jsonv2&limit=1](https://nominatim.openstreetmap.org/search?addressdetails=1&q=bakery+in+berlin+wedding&format=jsonv2&limit=1)
 270
 271 ```json
 272 [
 273   {
 274     "address": {
 275       "ISO3166-2-lvl4": "DE-BE",
 276       "borough": "Mitte",
 277       "city": "Berlin",
 278       "country": "Deutschland",
 279       "country_code": "de",
 280       "neighbourhood": "Sprengelkiez",
 281       "postcode": "13347",
 282       "road": "Lindower Straße",
 283       "shop": "Ditsch",
 284       "suburb": "Wedding"
 285     },
 286     "addresstype": "shop",
 287     "boundingbox": [
 288       "52.5427201",
 289       "52.5427654",
 290       "13.3668619",
 291       "13.3669442"
 292     ],
 293     "category": "shop",
 294     "display_name": "Ditsch, Lindower Straße, Sprengelkiez, Wedding, Mitte, Berlin, 13347, Deutschland",
 295     "importance": 9.99999999995449e-06,
 296     "lat": "52.54274275",
 297     "licence": "Data © OpenStreetMap contributors, ODbL 1.0. http://osm.org/copyright",
 298     "lon": "13.36690305710228",
 299     "name": "Ditsch",
 300     "osm_id": 437595031,
 301     "osm_type": "way",
 302     "place_id": 204751033,
 303     "place_rank": 30,
 304     "type": "bakery"
 305   }
 306 ]
 307 ```
 308
 309 ##### GeoJSON
 310
 311 [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)
 312
 313 ```json
 314 {
 315   "type": "FeatureCollection",
 316   "licence": "Data © OpenStreetMap contributors, ODbL 1.0. https://osm.org/copyright",
 317   "features": [
 318     {
 319       "type": "Feature",
 320       "properties": {
 321         "place_id": "35811445",
 322         "osm_type": "node",
 323         "osm_id": "2846295644",
 324         "display_name": "17, Strada Pictor Alexandru Romano, Bukarest, Bucharest, Sector 2, Bucharest, 023964, Romania",
 325         "place_rank": "30",
 326         "category": "place",
 327         "type": "house",
 328         "importance": 0.62025
 329       },
 330       "bbox": [
 331         26.1156689,
 332         44.4354754,
 333         26.1157689,
 334         44.4355754
 335       ],
 336       "geometry": {
 337         "type": "Point",
 338         "coordinates": [
 339           26.1157189,
 340           44.4355254
 341         ]
 342       }
 343     }
 344   ]
 345 }
 346 ```
 347
 348 ##### GeocodeJSON
 349
 350 [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)
 351
 352 ```json
 353 {
 354   "type": "FeatureCollection",
 355   "geocoding": {
 356     "version": "0.1.0",
 357     "attribution": "Data © OpenStreetMap contributors, ODbL 1.0. https://osm.org/copyright",
 358     "licence": "ODbL",
 359     "query": "Αγία Τριάδα, Αδωνιδος, Athens, Greece"
 360   },
 361   "features": [
 362     {
 363       "type": "Feature",
 364       "properties": {
 365         "geocoding": {
 366           "type": "place_of_worship",
 367           "label": "Αγία Τριάδα, Αδωνιδος, Άγιος Νικόλαος, 5º Δημοτικό Διαμέρισμα Αθηνών, Athens, Municipality of Athens, Regional Unit of Central Athens, Region of Attica, Attica, 11472, Greece",
 368           "name": "Αγία Τριάδα",
 369           "admin": null
 370         }
 371       },
 372       "geometry": {
 373         "type": "Point",
 374         "coordinates": [
 375           23.72949633941,
 376           38.0051697
 377         ]
 378       }
 379     }
 380   ]
 381 }
 382 ```