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