X-Git-Url: https://git.openstreetmap.org./nominatim.git/blobdiff_plain/141b32f4192819579adbc1388a90ba92d47485e6..7ea860b2c083a0b1c3cc99fb07cd803b2000f880:/docs/api/Search.md

diff --git a/docs/api/Search.md b/docs/api/Search.md
index ab702379..ace6cc8d 100644
--- a/docs/api/Search.md
+++ b/docs/api/Search.md
@@ -1,14 +1,13 @@
 # Search queries
 
-The search API allows to look up a location from a textual description.
+The search API allows you to look up a location from a textual description.
 Nominatim supports structured as well as free-form search queries.
 
 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`).
+Note that this only limits the items to be found, it's not suited to return complete
+lists of OSM objects of a specific type. For those use [Overpass API](https://overpass-api.de/).
 
 ## Parameters
 
@@ -30,26 +29,24 @@ In this form, the query may be given through two different sets of parameters:
 * `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).
-    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>`
-  `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**.
 
-All three query forms accept the additional paramters listed below.
+All three query forms accept the additional parameters listed below.
 
 ### Output format
 
@@ -59,7 +56,7 @@ See [Place Output Formats](Output.md) for details on each format. (Default: html
 
 * `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
@@ -86,7 +83,7 @@ language variants, references, operator and brand. (Default: 0)
 * `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.
 
@@ -109,21 +106,22 @@ the search to return other, less accurate, matches (if possible).
 
 * `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
-are accepted in any order as long as they span a real box.
+are accepted in any order as long as they span a real box. `x` is longitude,
+`y` is latitude.
 
 
 * `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
+viewbox (see above). When `viewbox` and `bounded=1` 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)
+amenity in square brackets, e.g. `[pub]`. (Default: 0)
 
 
 ### Polygon output
@@ -178,12 +176,12 @@ This overrides the specified machine readable format. (Default: 0)
 
 ```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"
+      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"
       class="place" type="house">
       <house_number>135</house_number>
       <road>Pilkington Avenue</road>
@@ -240,7 +238,7 @@ This overrides the specified machine readable format. (Default: 0)
 
 ##### 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
     {