update DOCS.md for readability, etc

DOCS.md

@@ -1,53 +1,79 @@
+## /search
+
+Full text search endpoint (queries the elasticsearch doc store, slightly slower than suggest)
+
+#### 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 
+  * **size** (defaults to 10)
+  * **layers** (defaults to ```poi,admin,address```)
+
 ## /suggest
-* this is the autocomplete endpoint (fast response time/ straight from the memory)
+
-* takes the following params
+The autocomplete endpoint: fast response time, served from memory
-  * **input**: query string (required)
+
-  * **lat**: latitude from where you are searching (required)
+#### Parameters
-  * **lon**: longitude (required)
+* required:
-  * **zoom**: zoom level at which you are viewing the world (optional)
+  * **input**: query string
-  * **size**: number of results you need (optional, defaults to 10)
+  * **lat**: latitude from where you are searching
-  * **layers**: datasets you want to query upon (optional, defaults to ```poi,admin,address```). It can be ```poi```, ```admin``` or ```address``` 
+  * **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```). 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```
-* Lat/Lon is **required** currently because of this [open issue](https://github.com/elasticsearch/elasticsearch/issues/6444)
 
 ## /suggest/coarse
-* Only queries the admin layers
-* Its the same as ```/suggest``` with layers param set to ```admin```
-* ```/suggest/coarse``` takes all other params that ```/suggest``` takes
 
-## /search
+Only queries the admin layers
-* this is the full text search endpoint (looks up elasticsearch doc store, slightly slower than suggest)
+
-* takes the following params (same as suggest)
+#### Parameters
-  * **input** (required)
+* this endpoint is the equivalent of ```/suggest``` with the layers param set to ```admin```
-  * **lat** (optional)
+* takes all other params that ```/suggest``` takes
-  * **lon** (optional)
-  * **zoom** (optional)
-  * **bbox**: (optional) 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 string (they are all 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 
-  * **size** (optional, defaults to 10)
-  * **layers** (optional, defaults to ```poi,admin,address```)
 
 ## /search/coarse
-* Similar to its suggest counterpart 
+
-* Its /search with layers param set to ```admin```
+Similar to the suggest endpoint 
+
+#### Parameters
+* the equivalent of /search with the layers param set to ```admin```
 * ```/search/coarse``` takes all other params that /search takes
 
 ## /reverse
-* Does reverse geocoding
+
-* It takes the following params
+Reverse geocoding endpoint
-  * **lat** (required)
+
-  * **lon** (required)
+#### Parameters
-  * **zoom** (optional)
+* required:
-  * **bbox** (optional)
+  * **lat**
-  * **layers** (optional, defaults to ```poi,admin,address```)
+  * **lon**
+* optional:
+  * **zoom**
+  * **bbox**
+  * **layers** (defaults to ```poi,admin,address```)
 
 ## /doc
-* retrieve a document or multiple documents at once
+
-* it takes just one param
+Retrieves a document or multiple documents at once
-  * **id**: (required) unique id of the document that need to be retrieved (should be in the form of type:id for example: ```geoname:4163334```
+
-  * **ids**: (if multiple docs are to be fetched in bulk) an array of ids
+#### Parameters
+* required:
+  * one of **id** or **ids**
+    * **id**:
+      * unique id of the document that to be retrieved
+      * should be in the form of type:id, for example: ```geoname:4163334```
+    * **ids**
+      * if multiple docs are to be fetched in bulk, an array of ids