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]`
  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 * `extratags=1`
 110     * Include additional information in the result if available, e.g. wikipedia link, opening hours.
 111
 112 * `namedetails=1`
 113     * Include a list of alternative names in the results.
 114     * These may include language variants, references, operator and brand.
 115
 116 ### Examples
 117
 118 * [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)
 119 * [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)
 120 * [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)
 121
 122 ```xml
 123   <searchresults timestamp="Sat, 07 Nov 09 14:42:10 +0000" querystring="135 pilkington, avenue birmingham" polygon="true">
 124     <place
 125       place_id="1620612" osm_type="node" osm_id="452010817"
 126       boundingbox="52.548641204834,52.5488433837891,-1.81612110137939,-1.81592094898224"
 127       polygonpoints="[['-1.81592098644987','52.5487429714954'],['-1.81592290792183','52.5487234624632'],...]"
 128       lat="52.5487429714954" lon="-1.81602098644987"
 129       display_name="135, Pilkington Avenue, Wylde Green, City of Birmingham, West Midlands (county), B72, United Kingdom"
 130       class="place" type="house">
 131       <house_number>135</house_number>
 132       <road>Pilkington Avenue</road>
 133       <village>Wylde Green</village>
 134       <town>Sutton Coldfield</town>
 135       <city>City of Birmingham</city>
 136       <county>West Midlands (county)</county>
 137       <postcode>B72</postcode>
 138       <country>United Kingdom</country>
 139       <country_code>gb</country_code>
 140     </place>
 141   </searchresults>
 142 ```
 143
 144 * [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)
 145
 146 ```json
 147     {
 148         "address": {
 149             "city": "Berlin",
 150             "city_district": "Mitte",
 151             "construction": "Unter den Linden",
 152             "continent": "European Union",
 153             "country": "Deutschland",
 154             "country_code": "de",
 155             "house_number": "1",
 156             "neighbourhood": "Scheunenviertel",
 157             "postcode": "10117",
 158             "public_building": "Kommandantenhaus",
 159             "state": "Berlin",
 160             "suburb": "Mitte"
 161         },
 162         "boundingbox": [
 163             "52.5170783996582",
 164             "52.5173187255859",
 165             "13.3975105285645",
 166             "13.3981599807739"
 167         ],
 168         "class": "amenity",
 169         "display_name": "Kommandantenhaus, 1, Unter den Linden, Scheunenviertel, Mitte, Berlin, 10117, Deutschland, European Union",
 170         "importance": 0.73606775332943,
 171         "lat": "52.51719785",
 172         "licence": "Data \u00a9 OpenStreetMap contributors, ODbL 1.0. https://www.openstreetmap.org/copyright",
 173         "lon": "13.3978352028938",
 174         "osm_id": "15976890",
 175         "osm_type": "way",
 176         "place_id": "30848715",
 177         "svg": "M 13.397511 -52.517283599999999 L 13.397829400000001 -52.517299800000004 13.398131599999999 -52.517315099999998 13.398159400000001 -52.517112099999999 13.3975388 -52.517080700000001 Z",
 178         "type": "public_building"
 179     }
 180 ```
 181
 182 * [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)
 183
 184 ```json
 185     {
 186         "address": {
 187             "bakery": "B\u00e4cker Kamps",
 188             "city_district": "Mitte",
 189             "continent": "European Union",
 190             "country": "Deutschland",
 191             "country_code": "de",
 192             "footway": "Bahnsteig U6",
 193             "neighbourhood": "Sprengelkiez",
 194             "postcode": "13353",
 195             "state": "Berlin",
 196             "suburb": "Wedding"
 197         },
 198         "boundingbox": [
 199             "52.5460929870605",
 200             "52.5460968017578",
 201             "13.3591794967651",
 202             "13.3591804504395"
 203         ],
 204         "class": "shop",
 205         "display_name": "B\u00e4cker Kamps, Bahnsteig U6, Sprengelkiez, Wedding, Mitte, Berlin, 13353, Deutschland, European Union",
 206         "icon": "https://nominatim.openstreetmap.org/images/mapicons/shopping_bakery.p.20.png",
 207         "importance": 0.201,
 208         "lat": "52.5460941",
 209         "licence": "Data \u00a9 OpenStreetMap contributors, ODbL 1.0. https://www.openstreetmap.org/copyright",
 210         "lon": "13.35918",
 211         "osm_id": "317179427",
 212         "osm_type": "node",
 213         "place_id": "1453068",
 214         "type": "bakery"
 215     }
 216 ```