From a921961c7ddd85ab03b51c12dd671005bfd098e0 Mon Sep 17 00:00:00 2001 From: Severyn Kozak Date: Tue, 5 May 2015 16:27:36 -0400 Subject: [PATCH] Remove redundant parameter documentation. DOCS.md -Rather than repeating parameter documentation verbatim for similar endpoints, simply reference the related endpoints. --- DOCS.md | 67 +++++++++++++++++++++------------------------------------ 1 file changed, 24 insertions(+), 43 deletions(-) diff --git a/DOCS.md b/DOCS.md index 9854b37c..2851a8ef 100644 --- a/DOCS.md +++ b/DOCS.md @@ -1,21 +1,20 @@ ## /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 +* **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**: 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` +* **layers**: the datasets you wish to query (defaults to `poi,admin,address`). 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` + * 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()` @@ -30,29 +29,24 @@ Full text search endpoint which queries the elasticsearch doc store, slightly sl ## /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) +* **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 @@ -60,48 +54,35 @@ The autocomplete endpoint, it offers fast response time. Mixes results from arou * **layers**: datasets you wish to query (defaults to `poi,admin,address`) * **details**: (defaults to `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 @@ -112,7 +93,7 @@ Reverse geocoding endpoint. ## /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**