Merge pull request #126 from pelias/edit-docs

some DOCS.md refactoring

DOCS.md

@@ -1,123 +1,102 @@
 ## /search
 
-Full text search endpoint which queries the elasticsearch doc store, slightly slower than suggest.
+The full text search endpoint that matches the name of a place to points on the planet.
 
 #### Required Parameters
-* **input**: query string
+* `input`: the string to search for (eg `new york city` or `london`)
 
 #### Optional Parameters
-* **lat**: latitude
-* **lon**: longitude
-* **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 `poi,admin,address`).
-  * valid values are `poi`, `admin` or `address`
+* `lat`, `lon`: the latitude/longitude coordinates to bias search results towards (may increase relevancy)
+* `zoom`: zoom level from which you wish to view the world
+* `size` (default: `10`): the number of results to return
+* `layers` (default: `poi,admin,address`): the comma-separated names of datasets you wish to query. Valid values are:
+  * aliases for multiple datasets like `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`
-  * can also be specific to one particular dataset, for example `geoname`
-* **bbox**: the bounding box from which you want all your results to come
+  * the name of one particular dataset, like `geoname` or `osmaddress`
+* `bbox`: the bounding box from which you want all your results to come
   * can be one of the following comma separated string values
     * "southwest_lng,southwest_lat,northeast_lng,northeast_lat" `L.latLngBounds(southwestLatLng, northeastLatLng).toBBoxString()`
     * bottom left lon, bottom left lat, top right lon, top right lat
     * left, bottom, right, top
     * min longitude, min latitude, max longitude, max latitude
-* **details**: indicates if results should contain detailed, should be `true` or `false`
-  * when false results will only contain `id`, `layer`, and `text` properties
-  * when true, all available properties will be included in results
+* `details` (default: `true`): indicates if results should contain detailed. Valid values:
+  * `false`: results will only contain `id`, `layer`, and `text` properties
+  * `true`: all available properties will be included in results
 
 
 ## /search/coarse
 
-This is a coarse forward geocoder endpoint which only searches admin dataset layers.
+Like the `/search` endpoint, but performs a "coarse" search, meaning that it only searches administrative regions
+(countries, states, counties, neighborhoods, etc.).
 
 #### Required Parameters
-* **input**: query string
+Same as `/search`.
 
 #### Optional Parameters
-* **lat**: latitude
-* **lon**: longitude
-* **zoom**: zoom level from which you wish to view the world
-* **bbox**: the bounding box frome which you want all your results to come
-* **size**: (defaults to 10)
-* **layers**: (defaults to `admin`)
-* **details**: (defaults to `true`)
-
+Same as `/search`.
 
 ## /suggest
 
-The autocomplete endpoint, it offers fast response time. Mixes results from around the provided lat/lon and also from precision level 1 and 3.
+The autocompletion endpoint that offers very fast response times; ideal for completing partial user input. Mixes
+results from around the provided lat/lon coordinates 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)
+* `input`: query string
+* `lat`, `lon`: The latitude/longitude coordinates to bias results towards.
+  * `lat`/`lon` are currently **required** 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 `poi,admin,address`)
-* **details**: (defaults to `true`)
-
+* `zoom`: zoom level from which you wish to view the world
+* `size` (default: `10`): number of results requested
+* `layers` (default: `poi,admin,address`): datasets you wish to query
+* `details` (default: `true`)
 
 ## /suggest/coarse
 
 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)
+Same as `/suggest`.
 
 #### 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`)
-* **details**: (defaults to `true`)
+Same as `/suggest`.
 
 
 ## /suggest/nearby
 
-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).
+Works as autocomplete for only the 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).
 
 #### 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)
+Same as `/suggest`.
 
 #### Optional Parameters
-* **zoom**: zoom level from which you wish to view the world
-* **size**: number of results you need (defaults to 10)
-* **layers**: datasets you wish to query (defaults to `poi,admin,address`)
-* **details**: (defaults to `true`)
-
+Same as `/suggest`.
 
 ## /reverse
 
-Reverse geocoding endpoint.
+The reverse geocoding endpoint; matches a point on the planet to the name of that place.
 
 #### Required Parameters
-* **lat**: latitude
-* **lon**: longitude
+* `lat`, `lon`: The coordinates of the point.
 
 #### Optional Parameters
-* **zoom**: zoom level from which you wish to view the world
-* **bbox**: bounding box
-* **layers**: (defaults to `poi,admin,address`)
-* **details**: (defaults to `true`)
+* `zoom`: zoom level from which you wish to view the world
+* `layers` (default: `poi,admin,address`)
+* `details` (default: `true`)
 
 
 ## /doc
 
-Retrieves a document or multiple documents at once.
+The endpoint for retrieving one or more elasticsearch documents with specific ids.
 
 #### Required Parameters
-* one of **id** or **ids**
-  * **id**:
+* one of `id` or `ids`
+  * `id`:
     * unique id of the document to be retrieved
     * 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