docs/api/Search.md

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