api/DOCS.md

# --- WARNING ---
## Pelias v1.0 will be released in September 2015!!!
## All users must obtain FREE developer keys in order to
## continue using the Pelias service after v1.0 has been released.
## There will be breaking changes to the API,
## so action must be taken to upgrade client code.
## Backwards compatibility will be maintained through November 2015,
## after which the old service will be deprecated and taken off line.
# ----- END -----


## /search

The full text search endpoint that matches the name of a place to points on the planet.

#### Required Parameters
* `input`: the string to search for (eg `new york city` or `london`)

#### Optional Parameters
* `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`
  * 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` (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

Like the `/search` endpoint, but performs a "coarse" search, meaning that it only searches administrative regions
(countries, states, counties, neighborhoods, etc.).

#### Required Parameters
Same as `/search`.

#### Optional Parameters
Same as `/search`.

## /suggest

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`, `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` (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
Same as `/suggest`.

#### Optional Parameters
Same as `/suggest`.


## /suggest/nearby

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
Same as `/suggest`.

#### Optional Parameters
Same as `/suggest`.

## /reverse

The reverse geocoding endpoint; matches a point on the planet to the name of that place.

#### Required Parameters
* `lat`, `lon`: The coordinates of the point.

#### Optional Parameters
* `zoom`: zoom level from which you wish to view the world
* `layers` (default: `poi,admin,address`)
* `details` (default: `true`)


## /doc

The endpoint for retrieving one or more elasticsearch documents with specific ids.

#### Required Parameters
* 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`:
    * if multiple docs are to be fetched in bulk, an array of ids