more DOCS updates

DOCS.md

@@ -1,114 +1,116 @@
 ## /search
 
-Full text search endpoint (queries the elasticsearch doc store, slightly slower than suggest)
+Full text search endpoint (queries the elasticsearch doc store, slightly slower than suggest).
 
-#### Parameters
+#### Required Parameters
-* required:
+* **input**: query string
-  * **input**: query string
+
-* optional:
+#### Optional Parameters
-  * **lat**: latitude from where you are searching
+  * **lat**: latitude
   * **lon**: longitude
-  * **zoom**: zoom level at which you are viewing the world
+  * **zoom**: zoom level from which you wish to view the world
-  * **size**: number of results you need (defaults to 10)
+  * **size**: number of results requested (defaults to 10)
-  * **layers**: datasets you want to query upon (defaults to ```poi,admin,address```). 
+  * **layers**: datasets you wish to query (defaults to ```poi,admin,address```). 
-    * It can be ```poi```, ```admin``` or ```address``` 
+    * valid values are ```poi```, ```admin``` or ```address``` 
-    * ```poi``` expands internally to ```geoname```, ```osmnode```, ```osmway``` 
+      * ```poi``` expands internally to ```geoname```, ```osmnode```, ```osmway``` 
-    * ```admin``` expands to ```admin0```, ```admin1```, ```admin2```, ```neighborhood```, ```locality```, ```local_admin```
+      * ```admin``` expands to ```admin0```, ```admin1```, ```admin2```, ```neighborhood```, ```locality```, ```local_admin```
-    * ```address``` expands to ```osmaddress```, ```openaddresses```
+      * ```address``` expands to ```osmaddress```, ```openaddresses```
-    * or it can also be specific to one particular dataset for example: ```geoname```
+    * can also be specific to one particular dataset, for example ```geoname```
-  * **bbox**: the bounding box where you want all your results to appear in. 
+  * **bbox**: the bounding box from which you want all your results to come
-    * It can be one of the following comma separated string value
+    * can be one of the following comma separated string values
-    * bottom_left lat, bottom_left lon, top_right lat, top_right lon
+      * bottom_left lat, bottom_left lon, top_right lat, top_right lon
-    * left,bottom,right,top
+      * left, bottom, right, top
-    * min Longitude , min Latitude , max Longitude , max Latitude 
+      * min longitude, min latitude, max longitude, max latitude 
+
 
 ## /search/coarse
-This is a coarse forward geocoder endpoint: only searches admin dataset layers
+This is a coarse forward geocoder endpoint: only searches admin dataset layers.
-
+
-#### Parameters
+#### Required Parameters
-* required:
+* **input**: query string
-  * **input** 
+
-* optional:
+#### Optional Parameters
-  * **lat**
+* **lat**: latitude
-  * **lon**
+* **lon**: longitude
-  * **zoom**
+* **zoom**: zoom level from which you wish to view the world
-  * **bbox**: the bounding box where you want all your results to appear in. 
+* **bbox**: the bounding box frome which you want all your results to come
-    * It can be one of the following comma separated string value
+  * can be one of the following comma separated string values
     * bottom_left lat, bottom_left lon, top_right lat, top_right lon
-    * left,bottom,right,top
+    * left, bottom, right, top
-    * min Longitude , min Latitude , max Longitude , max Latitude 
+    * min longitude, min latitude, max longitude, max latitude 
-  * **size** (defaults to 10)
+* **size** (defaults to 10)
-  * **layers** (set to ```admin``` by default)
+* **layers** (defaults to ```admin```)
+
 
 ## /suggest
 
-The autocomplete endpoint: fast response time. Mixes results from around the provided lat/lon and also from precision level 1 and 3
+The autocomplete endpoint, it offers fast response time. Mixes results from around the provided lat/lon and also from precision level 1 and 3.
+
+#### Required Parameters
+* **input**: query string
+* **lat**: latitude
+* **lon**: longitude
+  * lat/lon are **required** currently because of this [open issue](https://github.com/elasticsearch/elasticsearch/issues/6444)
+
+#### Optional Parameters
+* **zoom**: zoom level at which you are viewing the world
+* **size**: number of results requested (defaults to 10)
+* **layers**: datasets you wish to query (defaults to ```poi,admin,address```)
 
-#### Parameters
-* 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```)
 
 ## /suggest/coarse
 
-Only queries the admin layers
+Only queries the admin layers.
+
+#### Required Parameters
+* **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 Parameters
+* **zoom**: zoom level from which you wish to view the world
+* **size**: number of results requested (defaults to 10)
+* **layers**: datasets you wish to query (defaults to ```admin```)
 
-#### Parameters
-* 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```)
 
 ## /suggest/nearby
 
-* Works as autocomplete for places located nearby the lat/lon
+Works as autocomplete for places located near a latitude/longitude, this endpoint is the same as ```/suggest``` but the results are all from within 50 kilometers of the specified point.  Unlike ```/suggest```, ```/suggest/nearby``` does not mix results from different precision levels (500km, 1000km etc from 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
+#### Required Parameters
-* required:
+* **input**: query string
-  * **input**: query string
+* **lat**: latitude
-  * **lat**: latitude from where you are searching
+* **lon**: longitude
-  * **lon**: longitude
+  * lat/lon are **required** currently because of this [open issue](https://github.com/elasticsearch/elasticsearch/issues/6444)
-    * lat/lon are **required** currently because of this [open issue](https://github.com/elasticsearch/elasticsearch/issues/6444)
+
-* optional:
+#### Optional Parameters
-  * **zoom**: zoom level at which you are viewing the world
+* **zoom**: zoom level at which you are viewing the world
-  * **size**: number of results you need (defaults to 10)
+* **size**: number of results you need (defaults to 10)
-  * **layers**: datasets you want to query upon (defaults to ```poi,admin,address```)
+* **layers**: datasets you wish to query (defaults to ```poi,admin,address```)
 
 ## /reverse
 
-Reverse geocoding endpoint
+Reverse geocoding endpoint.
+
+#### Required Parameters
+* **lat**: latitude
+* **lon**: longitude
+
+#### Optional Parameters
+* **zoom**: zoom level
+* **bbox**: bounding box
+* **layers** (defaults to ```poi,admin,address```)
 
-#### Parameters
-* required:
-  * **lat**: latitude
-  * **lon**: longitude
-* optional:
-  * **zoom**: zoom level
-  * **bbox**: bounding box
-  * **layers** (defaults to ```poi,admin,address```)
 
 ## /doc
 
-Retrieves a document or multiple documents at once
+Retrieves a document or multiple documents at once.
 
-#### Parameters
+#### Required Parameters
-* required:
+* one of **id** or **ids**
-  * one of **id** or **ids**
+  * **id**:
-    * **id**:
+    * unique id of the document that to be retrieved
-      * unique id of the document that to be retrieved
+    * should be in the form of type:id, for example: ```geoname:4163334```
-      * should be in the form of type:id, for example: ```geoname:4163334```
+  * **ids**
-    * **ids**
+    * if multiple docs are to be fetched in bulk, an array of ids
-      * if multiple docs are to be fetched in bulk, an array of ids