docs/api/Search.md

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