]> git.openstreetmap.org Git - nominatim.git/blobdiff - docs/api/Search.md
projects / nominatim.git / blobdiff
? search:
summary | shortlog | log | commit | commitdiff | tree
raw | inline | side by side
cache all postcodes
[nominatim.git] / docs / api / Search.md
diff --git a/docs/api/Search.md b/docs/api/Search.md
index 1cb6cef0163cce6b83a616378e2f2b1c95e9b5e0..eada817f089f309a7bf3cecb2791de423c711508 100644 (file)
--- a/docs/api/Search.md
+++ b/docs/api/Search.md
@@ -1,65 +1,59 @@
 # Search queries
 
 # Search queries
 
-The search API allows to look up a location from a textual description.
-Nominatim supports structured as well as free-form search queries.
+The search API allows you to look up a location from a textual description
+or address. Nominatim supports structured and free-form search queries.
 
 The search query may also contain
 [special phrases](https://wiki.openstreetmap.org/wiki/Nominatim/Special_Phrases)
 
 The search query may also contain
 [special phrases](https://wiki.openstreetmap.org/wiki/Nominatim/Special_Phrases)
-which are tranlated into specific OpenStreetMap(OSM) tags (e.g. Pub => amenity=pub).
-Note that this only limits the items to be found. It is not suited to return complete
-lists of OSM objects of a specific type.
-Use [Overpass API](https://overpass-api.de/) for that.
+which are translated into specific OpenStreetMap (OSM) tags (e.g. Pub => `amenity=pub`).
+This can be used to narrow down the kind of objects to be returned.
 
 
-## Parameters
-
-The search API has the following two formats:
+!!! warning
+    Special phrases are not suitable to query all objects of a certain type in an
+    area. Nominatim will always just return a collection of the best matches. To
+    download OSM data by object type, use the [Overpass API](https://overpass-api.de/).
 
 
-```
-   https://nominatim.openstreetmap.org/search/<query>?<params>
-```
+## Parameters
 
 
-This format only accepts a free-form query string where the
-parts of the query are separated by slashes.
+The search API has the following format:
 
 ```
    https://nominatim.openstreetmap.org/search?<params>
 ```
 
 
 ```
    https://nominatim.openstreetmap.org/search?<params>
 ```
 
-In this form, the query may be given through two different sets of parameters:
+The search term may be specified with two different sets of parameters:
 
 * `q=<query>`
 
     Free-form query string to search for.
 
 * `q=<query>`
 
     Free-form query string to search for.
-    Free-form queries are processed first left to right and then right to
-    left if that fails. So you may search for
+    Free-form queries are processed first left-to-right and then right-to-left if that fails. So you may search for
     [pilkington avenue, birmingham](//nominatim.openstreetmap.org/search?q=pilkington+avenue,birmingham) as well as for
     [birmingham, pilkington avenue](//nominatim.openstreetmap.org/search?q=birmingham,+pilkington+avenue).
     [pilkington avenue, birmingham](//nominatim.openstreetmap.org/search?q=pilkington+avenue,birmingham) as well as for
     [birmingham, pilkington avenue](//nominatim.openstreetmap.org/search?q=birmingham,+pilkington+avenue).
-    Commas are optional, but improve performance by reducing the complexity
-    of the search.
+    Commas are optional, but improve performance by reducing the complexity of the search.
 
 
 * `street=<housenumber> <streetname>`
 
 
 * `street=<housenumber> <streetname>`
-  `city=<city>`
-  `county=<county>`
-  `state=<state>`
-  `country=<country>`
-  `postalcode=<postalcode>`
+* `city=<city>`
+* `county=<county>`
+* `state=<state>`
+* `country=<country>`
+* `postalcode=<postalcode>`
 
 
-    Alternative query string format for structured requests.
+    Alternative query string format split into several parameters for structured requests.
     Structured requests are faster but are less robust against alternative
     OSM tagging schemas. **Do not combine with** `q=<query>` **parameter**.
 
     Structured requests are faster but are less robust against alternative
     OSM tagging schemas. **Do not combine with** `q=<query>` **parameter**.
 
-All three query forms accept the additional paramters listed below.
+Both query forms accept the additional parameters listed below.
 
 ### Output format
 
 
 ### Output format
 
-* `format=[html|xml|json|jsonv2|geojson|geocodejson]`
+* `format=[xml|json|jsonv2|geojson|geocodejson]`
 
 
-See below for details on each format. (Default: html)
+See [Place Output Formats](Output.md) for details on each format. (Default: jsonv2)
 
 * `json_callback=<string>`
 
 
 * `json_callback=<string>`
 
-Wrap json output in a callback function (JSONP) i.e. `<string>(<json>)`.
+Wrap JSON output in a callback function ([JSONP](https://en.wikipedia.org/wiki/JSONP)) i.e. `<string>(<json>)`.
 Only has an effect for JSON output formats.
 
 ### Output details
 Only has an effect for JSON output formats.
 
 ### Output details
@@ -86,7 +80,7 @@ language variants, references, operator and brand. (Default: 0)
 * `accept-language=<browser language string>`
 
 Preferred language order for showing search results, overrides the value
 * `accept-language=<browser language string>`
 
 Preferred language order for showing search results, overrides the value
-specified in the "Accept-Language" HTTP header.
+specified in the ["Accept-Language" HTTP header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language).
 Either use a standard RFC2616 accept-language string or a simple
 comma-separated list of language codes.
 
 Either use a standard RFC2616 accept-language string or a simple
 comma-separated list of language codes.
 
@@ -95,35 +89,41 @@ comma-separated list of language codes.
 * `countrycodes=<countrycode>[,<countrycode>][,<countrycode>]...`
 
 Limit search results to one or more countries. `<countrycode>` must be the
 * `countrycodes=<countrycode>[,<countrycode>][,<countrycode>]...`
 
 Limit search results to one or more countries. `<countrycode>` must be the
-ISO 3166-1alpha2 code, e.g. `gb` for the United Kingdom, `de` for Germany.
+[ISO 3166-1alpha2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) code,
+e.g. `gb` for the United Kingdom, `de` for Germany.
 
 
+Each place in Nominatim is assigned to one country code based
+on OSM country boundaries. In rare cases a place may not be in any country
+at all, for example, in international waters.
 
 * `exclude_place_ids=<place_id,[place_id],[place_id]`
 
 If you do not want certain OSM objects to appear in the search
 result, give a comma separated list of the `place_id`s you want to skip.
 
 * `exclude_place_ids=<place_id,[place_id],[place_id]`
 
 If you do not want certain OSM 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).
+This can be used to retrieve additional 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).
 
 
 * `limit=<integer>`
 
 
 
 * `limit=<integer>`
 
-Limit the number of returned results. (Default: 10)
+Limit the number of returned results. (Default: 10, Maximum: 50)
 
 
 * `viewbox=<x1>,<y1>,<x2>,<y2>`
 
 The preferred area to find search results. Any two corner points of the box
 
 
 * `viewbox=<x1>,<y1>,<x2>,<y2>`
 
 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.
+are accepted as long as they span a real box. `x` is longitude,
+`y` is latitude.
 
 
 * `bounded=[0|1]`
 
 
 
 * `bounded=[0|1]`
 
-When a viewbox is given, restrict the result to items contained with that
-viewbox (see above). When `viewbox` and `bounded` are given, an amenity
-only search is allowed. In this case, give the special keyword for the
-amenity in squaer brackets, e.g. `[pub]`. (Default: 0)
+When a viewbox is given, restrict the result to items contained within that
+viewbox (see above). When `viewbox` and `bounded=1` are given, an amenity
+only search is allowed. Give the special keyword for the amenity in square
+brackets, e.g. `[pub]` and a selection of objects of this type is returned.
+There is no guarantee that the result is complete. (Default: 0)
 
 
 ### Polygon output
 
 
 ### Polygon output
@@ -138,7 +138,7 @@ options can be used at a time. (Default: 0)
 
 * `polygon_threshold=0.0`
 
 
 * `polygon_threshold=0.0`
 
-Simplify the output geometry before returning. The parameter is the
+Return a simplified version of the output geometry. The parameter is the
 tolerance in degrees with which the geometry may differ from the original
 geometry. Topology is preserved in the result. (Default: 0.0)
 
 tolerance in degrees with which the geometry may differ from the original
 geometry. Topology is preserved in the result. (Default: 0.0)
 
@@ -152,13 +152,11 @@ address to identify your requests. See Nominatim's [Usage Policy](https://operat
 * `dedupe=[0|1]`
 
 Sometimes you have several objects in OSM identifying the same place or
 * `dedupe=[0|1]`
 
 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
+object in reality. The simplest case is a street being split into many
 different OSM ways due to different characteristics. Nominatim will
 attempt to detect such duplicates and only return one match unless
 this parameter is set to 0. (Default: 1)
 
 different OSM ways due to different characteristics. Nominatim will
 attempt to detect such duplicates and only return one match unless
 this parameter is set to 0. (Default: 1)
 
-
-
 * `debug=[0|1]`
 
 Output assorted developer debug information. Data on internals of Nominatim's
 * `debug=[0|1]`
 
 Output assorted developer debug information. Data on internals of Nominatim's
@@ -170,21 +168,27 @@ This overrides the specified machine readable format. (Default: 0)
 ## Examples
 
 
 ## Examples
 
 
-##### XML with polygon points
+##### XML with kml polygon
 
 
-* [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)
-* [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)
-* [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)
+* [https://nominatim.openstreetmap.org/search?q=135+pilkington+avenue,+birmingham&format=xml&polygon_geojson=1&addressdetails=1](https://nominatim.openstreetmap.org/search?q=135+pilkington+avenue,+birmingham&format=xml&polygon_geojson=1&addressdetails=1)
 
 ```xml
   <searchresults timestamp="Sat, 07 Nov 09 14:42:10 +0000" querystring="135 pilkington, avenue birmingham" polygon="true">
 
 ```xml
   <searchresults timestamp="Sat, 07 Nov 09 14:42:10 +0000" querystring="135 pilkington, avenue birmingham" polygon="true">
-    <place 
-      place_id="1620612" osm_type="node" osm_id="452010817" 
-      boundingbox="52.548641204834,52.5488433837891,-1.81612110137939,-1.81592094898224" 
-      polygonpoints="[['-1.81592098644987','52.5487429714954'],['-1.81592290792183','52.5487234624632'],...]" 
-      lat="52.5487429714954" lon="-1.81602098644987" 
-      display_name="135, Pilkington Avenue, Wylde Green, City of Birmingham, West Midlands (county), B72, United Kingdom" 
+    <place
+      place_id="1620612" osm_type="node" osm_id="452010817"
+      boundingbox="52.548641204834,52.5488433837891,-1.81612110137939,-1.81592094898224"
+      lat="52.5487429714954" lon="-1.81602098644987"
+      display_name="135, Pilkington Avenue, Wylde Green, City of Birmingham, West Midlands (county), B72, United Kingdom"
       class="place" type="house">
       class="place" type="house">
+      <geokml>
+        <Polygon>
+          <outerBoundaryIs>
+            <LinearRing>
+              <coordinates>-1.816513,52.548756599999997 -1.816434,52.548747300000002 -1.816429,52.5487629 -1.8163717,52.548756099999999 -1.8163464,52.548834599999999 -1.8164599,52.548848100000001 -1.8164685,52.5488213 -1.8164913,52.548824000000003 -1.816513,52.548756599999997</coordinates>
+            </LinearRing>
+          </outerBoundaryIs>
+        </Polygon>
+      </geokml>
       <house_number>135</house_number>
       <road>Pilkington Avenue</road>
       <village>Wylde Green</village>
       <house_number>135</house_number>
       <road>Pilkington Avenue</road>
       <village>Wylde Green</village>
@@ -240,7 +244,7 @@ This overrides the specified machine readable format. (Default: 0)
 
 ##### JSON with address details
 
 
 ##### JSON with address details
 
-[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)
+[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)
 
 ```json
     {
 
 ```json
     {
Open Source search based on OpenStreetMap data