updates (added suggest/nearby)

DOCS.md

@@ -4,22 +4,45 @@ Full text search endpoint (queries the elasticsearch doc store, slightly slower
 
 #### Parameters
 * required:
-  * **input**
+  * **input**: query string
+* optional:
+  * **lat**: latitude from where you are searching
+  * **lon**: longitude
+  * **zoom**: zoom level at which you are viewing the world
+  * **size**: number of results you need (defaults to 10)
+  * **layers**: datasets you want to query upon (defaults to ```poi,admin,address```). 
+    * It can be ```poi```, ```admin``` or ```address``` 
+    * ```poi``` expands internally to ```geoname```, ```osmnode```, ```osmway``` 
+    * ```admin``` expands to ```admin0```, ```admin1```, ```admin2```, ```neighborhood```, ```locality```, ```local_admin```
+    * ```address``` expands to ```osmaddress```, ```openaddresses```
+    * or it can also be specific to one particular dataset for example: ```geoname```
+  * **bbox**: the bounding box where you want all your results to appear in. 
+    * It can be one of the following comma separated string value
+    * bottom_left lat, bottom_left lon, top_right lat, top_right lon
+    * left,bottom,right,top
+    * min Longitude , min Latitude , max Longitude , max Latitude 
+
+## /search/coarse
+This is a coarse forward geocoder endpoint: only searches admin dataset layers
+
+#### Parameters
+* required:
+  * **input** 
 * optional:
   * **lat**
   * **lon**
   * **zoom**
-  * **bbox**
-    * the bounding box where you want all your results to appear and be contained within that bbox, it can be one of the following comma separated strings, all of which are different ways of saying the same thing:
-      * bottom_left lat, bottom_left lon, top_right lat, top_right lon
-      * left, bottom, right, top
-      * min Longitude, min Latitude, max Longitude, max Latitude 
+  * **bbox**: the bounding box where you want all your results to appear in. 
+    * It can be one of the following comma separated string value
+    * bottom_left lat, bottom_left lon, top_right lat, top_right lon
+    * left,bottom,right,top
+    * min Longitude , min Latitude , max Longitude , max Latitude 
   * **size** (defaults to 10)
-  * **layers** (defaults to ```poi,admin,address```)
+  * **layers** (set to ```admin``` by default)
 
 ## /suggest
 
-The autocomplete endpoint: fast response time, served from memory
+The autocomplete endpoint: fast response time. Mixes results from around the provided lat/lon and also from precision level 1 and 3
 
 #### Parameters
 * required:
@@ -30,27 +53,39 @@ The autocomplete endpoint: fast response time, served from memory
 * optional:
   * **zoom**: zoom level at which you are viewing the world
   * **size**: number of results you need (defaults to 10)
-  * **layers**: datasets you want to query upon (defaults to ```poi,admin,address```). It can be ```poi```, ```admin``` or ```address``` 
-    * ```poi``` expands internally to ```geoname```, ```osmnode```, ```osmway``` 
-    * ```admin``` expands to ```admin0```, ```admin1```, ```admin2```, ```neighborhood```, ```locality```, ```local_admin```
-    * ```address``` expands to ```osmaddress```, ```openaddresses```
-    * or it can also be specific to one particular dataset for example: ```geoname```
+  * **layers**: datasets you want to query upon (defaults to ```poi,admin,address```)
 
 ## /suggest/coarse
 
 Only queries the admin layers
 
 #### Parameters
-* this endpoint is the equivalent of ```/suggest``` with the layers param set to ```admin```
-* takes all other params that ```/suggest``` takes
+* required:
+  * **input**: query string
+  * **lat**: latitude from where you are searching
+  * **lon**: longitude
+    * lat/lon are **required** currently because of this [open issue](https://github.com/elasticsearch/elasticsearch/issues/6444)
+* optional:
+  * **zoom**: zoom level at which you are viewing the world
+  * **size**: number of results you need (defaults to 10)
+  * **layers**: datasets you want to query upon (defaults to ```admin```)
 
-## /search/coarse
+## /suggest/nearby
 
-Similar to the suggest endpoint 
+* Works as autocomplete for places located nearby the lat/lon
+* Its the same as ```/suggest``` but the results are all within 50kms of lat/lon thats passed
+* Unlike ```/suggest```, ```/suggest/nearby``` does not mix results from different precision levels (500km, 1000km etc from lat/lon)
 
 #### Parameters
-* the equivalent of /search with the layers param set to ```admin```
-* ```/search/coarse``` takes all other params that /search takes
+* required:
+  * **input**: query string
+  * **lat**: latitude from where you are searching
+  * **lon**: longitude
+    * lat/lon are **required** currently because of this [open issue](https://github.com/elasticsearch/elasticsearch/issues/6444)
+* optional:
+  * **zoom**: zoom level at which you are viewing the world
+  * **size**: number of results you need (defaults to 10)
+  * **layers**: datasets you want to query upon (defaults to ```poi,admin,address```)
 
 ## /reverse
 
@@ -58,11 +93,11 @@ Reverse geocoding endpoint
 
 #### Parameters
 * required:
-  * **lat**
-  * **lon**
+  * **lat**: latitude
+  * **lon**: longitude
 * optional:
-  * **zoom**
-  * **bbox**
+  * **zoom**: zoom level
+  * **bbox**: bounding box
   * **layers** (defaults to ```poi,admin,address```)
 
 ## /doc