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 tranlated into specific OpenStreetMap(OSM) tags (e.g. Pub => amenity=pub).
   9 Note that this only limits the items to be found. It is not suited to return complete
  10 lists of OSM objects of a specific type.
  11 Use [Overpass API](https://overpass-api.de/) for that.
  12
  13 ## Parameters
  14
  15 The search API has the following two formats:
  16
  17 ```
  18    https://nominatim.openstreetmap.org/search/<query>?<params>
  19 ```
  20
  21 This format only accepts a free-form query string where the
  22 parts of the query are separated by slashes.
  23
  24 ```
  25    https://nominatim.openstreetmap.org/search?<params>
  26 ```
  27
  28 In this form, the query may be given through two different sets of parameters:
  29
  30 * `q=<query>`
  31
  32     Free-form query string to search for.
  33     Free-form queries are processed first left to right and then right to
  34     left if that fails. So you may search for
  35     [pilkington avenue, birmingham](//nominatim.openstreetmap.org/search?q=pilkington+avenue,birmingham) as well as for
  36     [birmingham, pilkington avenue](//nominatim.openstreetmap.org/search?q=birmingham,+pilkington+avenue).
  37     Commas are optional, but improve performance by reducing the complexity
  38     of the search.
  39
  40
  41 * `street=<housenumber> <streetname>`
  42   `city=<city>`
  43   `county=<county>`
  44   `state=<state>`
  45   `country=<country>`
  46   `postalcode=<postalcode>`
  47
  48     Alternative query string format for structured requests.
  49     Structured requests are faster but are less robust against alternative
  50     OSM tagging schemas. **Do not combine with** `q=<query>` **parameter**.
  51
  52 All three query forms accept the additional paramters listed below.
  53
  54 ### Output format
  55
  56 * `format=[html|xml|json|jsonv2|geojson|geocodejson]`
  57
  58 See [Place Output Formats](Output.md) for details on each format. (Default: html)
  59
  60 * `json_callback=<string>`
  61
  62 Wrap json output in a callback function (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.
  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 code, e.g. `gb` for the United Kingdom, `de` for Germany.
  99
 100
 101 * `exclude_place_ids=<place_id,[place_id],[place_id]`
 102
 103 If you do not want certain OSM objects to appear in the search
 104 result, give a comma separated list of the `place_id`s you want to skip.
 105 This can be used to broaden search results. For example, if a previous
 106 query only returned a few results, then including those here would cause
 107 the search to return other, less accurate, matches (if possible).
 108
 109
 110 * `limit=<integer>`
 111
 112 Limit the number of returned results. (Default: 10)
 113
 114
 115 * `viewbox=<x1>,<y1>,<x2>,<y2>`
 116
 117 The preferred area to find search results. Any two corner points of the box
 118 are accepted in any order as long as they span a real box.
 119
 120
 121 * `bounded=[0|1]`
 122
 123 When a viewbox is given, restrict the result to items contained with that
 124 viewbox (see above). When `viewbox` and `bounded` are given, an amenity
 125 only search is allowed. In this case, give the special keyword for the
 126 amenity in squaer brackets, e.g. `[pub]`. (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 Simplify the output geometry before returning. 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 in 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
 161
 162 * `debug=[0|1]`
 163
 164 Output assorted developer debug information. Data on internals of Nominatim's
 165 "Search Loop" logic, and SQL queries. The output is (rough) HTML format.
 166 This overrides the specified machine readable format. (Default: 0)
 167
 168
 169
 170 ## Examples
 171
 172
 173 ##### XML with polygon points
 174
 175 * [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)
 176 * [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)
 177 * [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)
 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       polygonpoints="[['-1.81592098644987','52.5487429714954'],['-1.81592290792183','52.5487234624632'],...]"
 185       lat="52.5487429714954" lon="-1.81602098644987"
 186       display_name="135, Pilkington Avenue, Wylde Green, City of Birmingham, West Midlands (county), B72, United Kingdom"
 187       class="place" type="house">
 188       <house_number>135</house_number>
 189       <road>Pilkington Avenue</road>
 190       <village>Wylde Green</village>
 191       <town>Sutton Coldfield</town>
 192       <city>City of Birmingham</city>
 193       <county>West Midlands (county)</county>
 194       <postcode>B72</postcode>
 195       <country>United Kingdom</country>
 196       <country_code>gb</country_code>
 197     </place>
 198   </searchresults>
 199 ```
 200
 201 ##### JSON with SVG polygon
 202
 203 [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)
 204
 205 ```json
 206     {
 207         "address": {
 208             "city": "Berlin",
 209             "city_district": "Mitte",
 210             "construction": "Unter den Linden",
 211             "continent": "European Union",
 212             "country": "Deutschland",
 213             "country_code": "de",
 214             "house_number": "1",
 215             "neighbourhood": "Scheunenviertel",
 216             "postcode": "10117",
 217             "public_building": "Kommandantenhaus",
 218             "state": "Berlin",
 219             "suburb": "Mitte"
 220         },
 221         "boundingbox": [
 222             "52.5170783996582",
 223             "52.5173187255859",
 224             "13.3975105285645",
 225             "13.3981599807739"
 226         ],
 227         "class": "amenity",
 228         "display_name": "Kommandantenhaus, 1, Unter den Linden, Scheunenviertel, Mitte, Berlin, 10117, Deutschland, European Union",
 229         "importance": 0.73606775332943,
 230         "lat": "52.51719785",
 231         "licence": "Data \u00a9 OpenStreetMap contributors, ODbL 1.0. https://www.openstreetmap.org/copyright",
 232         "lon": "13.3978352028938",
 233         "osm_id": "15976890",
 234         "osm_type": "way",
 235         "place_id": "30848715",
 236         "svg": "M 13.397511 -52.517283599999999 L 13.397829400000001 -52.517299800000004 13.398131599999999 -52.517315099999998 13.398159400000001 -52.517112099999999 13.3975388 -52.517080700000001 Z",
 237         "type": "public_building"
 238     }
 239 ```
 240
 241 ##### JSON with address details
 242
 243 [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)
 244
 245 ```json
 246     {
 247         "address": {
 248             "bakery": "B\u00e4cker Kamps",
 249             "city_district": "Mitte",
 250             "continent": "European Union",
 251             "country": "Deutschland",
 252             "country_code": "de",
 253             "footway": "Bahnsteig U6",
 254             "neighbourhood": "Sprengelkiez",
 255             "postcode": "13353",
 256             "state": "Berlin",
 257             "suburb": "Wedding"
 258         },
 259         "boundingbox": [
 260             "52.5460929870605",
 261             "52.5460968017578",
 262             "13.3591794967651",
 263             "13.3591804504395"
 264         ],
 265         "class": "shop",
 266         "display_name": "B\u00e4cker Kamps, Bahnsteig U6, Sprengelkiez, Wedding, Mitte, Berlin, 13353, Deutschland, European Union",
 267         "icon": "https://nominatim.openstreetmap.org/images/mapicons/shopping_bakery.p.20.png",
 268         "importance": 0.201,
 269         "lat": "52.5460941",
 270         "licence": "Data \u00a9 OpenStreetMap contributors, ODbL 1.0. https://www.openstreetmap.org/copyright",
 271         "lon": "13.35918",
 272         "osm_id": "317179427",
 273         "osm_type": "node",
 274         "place_id": "1453068",
 275         "type": "bakery"
 276     }
 277 ```
 278
 279 ##### GeoJSON
 280
 281 [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)
 282
 283 ```json
 284 {
 285   "type": "FeatureCollection",
 286   "licence": "Data © OpenStreetMap contributors, ODbL 1.0. https://osm.org/copyright",
 287   "features": [
 288     {
 289       "type": "Feature",
 290       "properties": {
 291         "place_id": "35811445",
 292         "osm_type": "node",
 293         "osm_id": "2846295644",
 294         "display_name": "17, Strada Pictor Alexandru Romano, Bukarest, Bucharest, Sector 2, Bucharest, 023964, Romania",
 295         "place_rank": "30",
 296         "category": "place",
 297         "type": "house",
 298         "importance": 0.62025
 299       },
 300       "bbox": [
 301         26.1156689,
 302         44.4354754,
 303         26.1157689,
 304         44.4355754
 305       ],
 306       "geometry": {
 307         "type": "Point",
 308         "coordinates": [
 309           26.1157189,
 310           44.4355254
 311         ]
 312       }
 313     }
 314   ]
 315 }
 316 ```
 317
 318 ##### GeocodeJSON
 319
 320 [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)
 321
 322 ```json
 323 {
 324   "type": "FeatureCollection",
 325   "geocoding": {
 326     "version": "0.1.0",
 327     "attribution": "Data © OpenStreetMap contributors, ODbL 1.0. https://osm.org/copyright",
 328     "licence": "ODbL",
 329     "query": "Αγία Τριάδα, Αδωνιδος, Athens, Greece"
 330   },
 331   "features": [
 332     {
 333       "type": "Feature",
 334       "properties": {
 335         "geocoding": {
 336           "type": "place_of_worship",
 337           "label": "Αγία Τριάδα, Αδωνιδος, Άγιος Νικόλαος, 5º Δημοτικό Διαμέρισμα Αθηνών, Athens, Municipality of Athens, Regional Unit of Central Athens, Region of Attica, Attica, 11472, Greece",
 338           "name": "Αγία Τριάδα",
 339           "admin": null
 340         }
 341       },
 342       "geometry": {
 343         "type": "Point",
 344         "coordinates": [
 345           23.72949633941,
 346           38.0051697
 347         ]
 348       }
 349     }
 350   ]
 351 }
 352 ```