docs/api/Search.md

   1
   2 ## Search
   3 Nominatim indexes named (or numbered) features with the OSM data set and a subset of other unnamed features (pubs, hotels, churches, etc)
   4
   5 Search terms are processed first left to right and then right to left if that fails.
   6
   7 Both searches will work: [pilkington avenue, birmingham](//nominatim.openstreetmap.org/search?q=pilkington+avenue,birmingham), [birmingham, pilkington avenue](//nominatim.openstreetmap.org/search?q=birmingham,+pilkington+avenue)
   8
   9 (Commas are optional, but improve performance by reducing the complexity of the search.)
  10
  11 Where house numbers have been defined for an area they should be used: [135 pilkington avenue, birmingham](//nominatim.openstreetmap.org/search?q=135+pilkington+avenue,+birmingham)
  12
  13 ### Special Keywords
  14 Various keywords are translated into searches for specific osm tags (e.g. Pub => amenity=pub).  A current list of [special phrases](https://wiki.openstreetmap.org/wiki/Nominatim/Special_Phrases) processed is available.
  15
  16 ### Parameters
  17
  18 ```
  19    https://nominatim.openstreetmap.org/search?<params>
  20    https://nominatim.openstreetmap.org/search/<query>?<params>
  21 ```
  22
  23 * `format=[html|xml|json|jsonv2|geojson|geocodejson]`
  24
  25     * Output format
  26     * defaults to `html`
  27
  28
  29 * `json_callback=<string>`
  30
  31     * Wrap json output in a callback function (JSONP) i.e. `<string>(<json>)`
  32
  33 * `accept-language=<browser language string>`
  34
  35     * Preferred language order for showing search results, overrides the value specified in the "Accept-Language" HTTP header.
  36     * Either uses standard rfc2616 accept-language string or a simple comma separated list of language codes.
  37
  38 * `q=<query>`
  39
  40     * Query string to search for.
  41     * Alternatively can be entered as:
  42
  43         * `street=<housenumber> <streetname>`
  44         * `city=<city>`
  45         * `county=<county>`
  46         * `state=<state>`
  47         * `country=<country>`
  48         * `postalcode=<postalcode>`
  49
  50       **(experimental)** Alternative query string format for structured requests.
  51 Structured requests are faster and require fewer server resources. **Do not combine with `q=<query>` parameter**.
  52
  53 * `countrycodes=<countrycode>[,<countrycode>][,<countrycode>]...`
  54
  55     * Limit search results to a specific country (or a list of countries).
  56     * `<countrycode>` should be the ISO 3166-1alpha2 code, e.g. `gb` for the United Kingdom, `de` for Germany, etc.
  57
  58 * `viewbox=<x1>,<y1>,<x2>,<y2>`
  59     * The preferred area to find search results. Any two corner points of the box are accepted in any order as long as they span a real box.
  60
  61 * `bounded=[0|1]`
  62     * defaults to 0
  63     * Restrict the results to only items contained with the viewbox (see above).
  64     * Restricting the results to the bounding box also enables searching by amenity only.
  65     * For example a search query of just `"[pub]"` would normally be rejected but with `bounded=1` will result in a list of items matching within the bounding box.
  66
  67 * `polygon=[0|1]`
  68     * defaults to 0
  69     * Output polygon outlines for items found **(deprecated, use one of the polygon_* parameters instead)**
  70
  71 * `addressdetails=[0|1]`
  72     * defaults to 0
  73     * Include a breakdown of the address into elements
  74
  75 * `email=<valid email address>`
  76
  77     * If you are making large numbers of request please include a valid email address or alternatively include your email address as part of the User-Agent string.
  78     * This information will be kept confidential and only used to contact you in the event of a problem, see [Usage Policy](https://operations.osmfoundation.org/policies/nominatim/) for more details.
  79
  80 * `exclude_place_ids=<place_id,[place_id],[place_id]`
  81
  82     * If you do not want certain openstreetmap objects to appear in the search result, give a comma separated list of the place_id's you want to skip. This can be used to broaden search results. For example, if a previous query only returned a few results, then including those here would cause the search to return other, less accurate, matches (if possible)
  83
  84 * `limit=<integer>`
  85     * defaults to 10
  86     * Limit the number of returned results.
  87
  88 * `dedupe=[0|1]`
  89     * defaults to 1
  90     * Sometimes you have several objects in OSM identifying the same place or object in reality. The simplest case is a street being split in many different OSM ways due to different characteristics.
  91     * Nominatim will attempt to detect such duplicates and only return one match; this is controlled by the dedupe parameter which defaults to 1. Since the limit is, for reasons of efficiency, enforced before and not after de-duplicating, it is possible that de-duplicating leaves you with less results than requested.
  92
  93 * `debug=[0|1]`
  94     * defaults to 0
  95     * Output assorted developer debug information. Data on internals of nominatim "Search Loop" logic, and SQL queries. The output is (rough) HTML format. This overrides the specified machine readable format.
  96
  97 * `polygon_geojson=1`
  98     * Output geometry of results in geojson format.
  99
 100 * `polygon_kml=1`
 101     * Output geometry of results in kml format.
 102
 103 * `polygon_svg=1`
 104     * Output geometry of results in svg format.
 105
 106 * `polygon_text=1`
 107     * Output geometry of results as a WKT.
 108
 109 * `polygon_threshold=0.0`
 110     * defaults to 0.0
 111     * Simplify the output geometry before returning. The parameter is the
 112       tolerance in degrees with which the geometry may differ from the original
 113       geometry. Topology is preserved in the result.
 114
 115 * `extratags=1`
 116     * Include additional information in the result if available, e.g. wikipedia link, opening hours.
 117
 118 * `namedetails=1`
 119     * Include a list of alternative names in the results.
 120     * These may include language variants, references, operator and brand.
 121
 122 ### Examples
 123
 124
 125 ##### XML with polygon points
 126
 127 * [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)
 128 * [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)
 129 * [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)
 130
 131 ```xml
 132   <searchresults timestamp="Sat, 07 Nov 09 14:42:10 +0000" querystring="135 pilkington, avenue birmingham" polygon="true">
 133     <place
 134       place_id="1620612" osm_type="node" osm_id="452010817"
 135       boundingbox="52.548641204834,52.5488433837891,-1.81612110137939,-1.81592094898224"
 136       polygonpoints="[['-1.81592098644987','52.5487429714954'],['-1.81592290792183','52.5487234624632'],...]"
 137       lat="52.5487429714954" lon="-1.81602098644987"
 138       display_name="135, Pilkington Avenue, Wylde Green, City of Birmingham, West Midlands (county), B72, United Kingdom"
 139       class="place" type="house">
 140       <house_number>135</house_number>
 141       <road>Pilkington Avenue</road>
 142       <village>Wylde Green</village>
 143       <town>Sutton Coldfield</town>
 144       <city>City of Birmingham</city>
 145       <county>West Midlands (county)</county>
 146       <postcode>B72</postcode>
 147       <country>United Kingdom</country>
 148       <country_code>gb</country_code>
 149     </place>
 150   </searchresults>
 151 ```
 152
 153 ##### JSON with SVG polygon
 154
 155 [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)
 156
 157 ```json
 158     {
 159         "address": {
 160             "city": "Berlin",
 161             "city_district": "Mitte",
 162             "construction": "Unter den Linden",
 163             "continent": "European Union",
 164             "country": "Deutschland",
 165             "country_code": "de",
 166             "house_number": "1",
 167             "neighbourhood": "Scheunenviertel",
 168             "postcode": "10117",
 169             "public_building": "Kommandantenhaus",
 170             "state": "Berlin",
 171             "suburb": "Mitte"
 172         },
 173         "boundingbox": [
 174             "52.5170783996582",
 175             "52.5173187255859",
 176             "13.3975105285645",
 177             "13.3981599807739"
 178         ],
 179         "class": "amenity",
 180         "display_name": "Kommandantenhaus, 1, Unter den Linden, Scheunenviertel, Mitte, Berlin, 10117, Deutschland, European Union",
 181         "importance": 0.73606775332943,
 182         "lat": "52.51719785",
 183         "licence": "Data \u00a9 OpenStreetMap contributors, ODbL 1.0. https://www.openstreetmap.org/copyright",
 184         "lon": "13.3978352028938",
 185         "osm_id": "15976890",
 186         "osm_type": "way",
 187         "place_id": "30848715",
 188         "svg": "M 13.397511 -52.517283599999999 L 13.397829400000001 -52.517299800000004 13.398131599999999 -52.517315099999998 13.398159400000001 -52.517112099999999 13.3975388 -52.517080700000001 Z",
 189         "type": "public_building"
 190     }
 191 ```
 192
 193 ##### JSON with address details
 194
 195 [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)
 196
 197 ```json
 198     {
 199         "address": {
 200             "bakery": "B\u00e4cker Kamps",
 201             "city_district": "Mitte",
 202             "continent": "European Union",
 203             "country": "Deutschland",
 204             "country_code": "de",
 205             "footway": "Bahnsteig U6",
 206             "neighbourhood": "Sprengelkiez",
 207             "postcode": "13353",
 208             "state": "Berlin",
 209             "suburb": "Wedding"
 210         },
 211         "boundingbox": [
 212             "52.5460929870605",
 213             "52.5460968017578",
 214             "13.3591794967651",
 215             "13.3591804504395"
 216         ],
 217         "class": "shop",
 218         "display_name": "B\u00e4cker Kamps, Bahnsteig U6, Sprengelkiez, Wedding, Mitte, Berlin, 13353, Deutschland, European Union",
 219         "icon": "https://nominatim.openstreetmap.org/images/mapicons/shopping_bakery.p.20.png",
 220         "importance": 0.201,
 221         "lat": "52.5460941",
 222         "licence": "Data \u00a9 OpenStreetMap contributors, ODbL 1.0. https://www.openstreetmap.org/copyright",
 223         "lon": "13.35918",
 224         "osm_id": "317179427",
 225         "osm_type": "node",
 226         "place_id": "1453068",
 227         "type": "bakery"
 228     }
 229 ```
 230
 231 ##### GeoJSON
 232
 233 [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)
 234
 235 ```json
 236 {
 237   "type": "FeatureCollection",
 238   "licence": "Data © OpenStreetMap contributors, ODbL 1.0. https://osm.org/copyright",
 239   "features": [
 240     {
 241       "type": "Feature",
 242       "properties": {
 243         "place_id": "35811445",
 244         "osm_type": "node",
 245         "osm_id": "2846295644",
 246         "display_name": "17, Strada Pictor Alexandru Romano, Bukarest, Bucharest, Sector 2, Bucharest, 023964, Romania",
 247         "place_rank": "30",
 248         "category": "place",
 249         "type": "house",
 250         "importance": 0.62025
 251       },
 252       "bbox": [
 253         26.1156689,
 254         44.4354754,
 255         26.1157689,
 256         44.4355754
 257       ],
 258       "geometry": {
 259         "type": "Point",
 260         "coordinates": [
 261           26.1157189,
 262           44.4355254
 263         ]
 264       }
 265     }
 266   ]
 267 }
 268 ```
 269
 270 ##### GeocodeJSON
 271
 272 [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)
 273
 274 ```json
 275 {
 276   "type": "FeatureCollection",
 277   "geocoding": {
 278     "version": "0.1.0",
 279     "attribution": "Data © OpenStreetMap contributors, ODbL 1.0. https://osm.org/copyright",
 280     "licence": "ODbL",
 281     "query": "Αγία Τριάδα, Αδωνιδος, Athens, Greece"
 282   },
 283   "features": [
 284     {
 285       "type": "Feature",
 286       "properties": {
 287         "geocoding": {
 288           "type": "place_of_worship",
 289           "label": "Αγία Τριάδα, Αδωνιδος, Άγιος Νικόλαος, 5º Δημοτικό Διαμέρισμα Αθηνών, Athens, Municipality of Athens, Regional Unit of Central Athens, Region of Attica, Attica, 11472, Greece",
 290           "name": "Αγία Τριάδα",
 291           "admin": null
 292         }
 293       },
 294       "geometry": {
 295         "type": "Point",
 296         "coordinates": [
 297           23.72949633941,
 298           38.0051697
 299         ]
 300       }
 301     }
 302   ]
 303 }
 304 ```