Diana Shkolnikov
9 years ago
3 changed files with 148 additions and 0 deletions
@ -0,0 +1,24 @@
|
||||
# Mapzen Search API |
||||
|
||||
## Overview |
||||
Searching the world with the Mapzen Search API, powered by [Pelias](https://github.com/pelias/pelias). |
||||
---------- |
||||
|
||||
Pelias is an experimental, open geocoder from [Mapzen](https://mapzen.com). It's built from the ground up as an open source and open data-friendly geocoder that's designed to operate on top of any new |
||||
|
||||
This documentation refers specifically to Mapzen Search (//TODO: do we want to call this Mapzen Place Search?), powered by Pelias, but is mirrored in the API of the [Pelias code](https://github.com/pelias/pelias). |
||||
|
||||
|
||||
### Version information |
||||
Version: 1.0.0 |
||||
|
||||
### URI scheme |
||||
Host: pelias.mapzen.com |
||||
BasePath: /v1 |
||||
Schemes: HTTP, HTTPS |
||||
|
||||
### Produces |
||||
|
||||
* application/vnd.geo+json |
||||
|
||||
|
||||
@ -0,0 +1,124 @@
|
||||
## Paths |
||||
### Fast response endpoint to provide an end-user suggestions of matching places as they're typing the search string. Returns 10 matching places. Intended for use while the user is typing a response. For searching a complete query (if autocomplete doesn't deliver a match), use the /search endpoint. |
||||
``` |
||||
GET /autocomplete |
||||
``` |
||||
|
||||
#### Parameters |
||||
|Type|Name|Description|Required|Schema|Default| |
||||
|----|----|----|----|----|----| |
||||
|QueryParameter|text|User's search string|true|string (string)|| |
||||
|QueryParameter|focus.point.lon|Focal point longitude. Ideally a user's device location, but can also be a focal point (like the center of their view). Used to provide results close to the user, while still finding good matches globally. Used in conjunction with `focus.point.lat`. Accepts only WGS84 longitutdes.|false|number (float)|| |
||||
|QueryParameter|focus.point.lat|Focal point latitude. Used to provide results close to the user, while still finding good matches globally. Used in conjunction with `focus.point.lon`. Accepts only WGS84 latitudes.|false|number (float)|| |
||||
|
||||
|
||||
#### Responses |
||||
|HTTP Code|Description|Schema| |
||||
|----|----|----| |
||||
|200|A GeoJSON FeatureCollection array of geocoded places.|No Content| |
||||
|400|Invalid request. Check that you are passing along valid parameters without conflicting options.|No Content| |
||||
|
||||
|
||||
#### Tags |
||||
|
||||
* search |
||||
* forward geocoding |
||||
|
||||
### Retrieves the full GeoJSON record for a given place. ID determined from the results of a `/search`, `/autocomplete`, or `/reverse` response. |
||||
``` |
||||
GET /place |
||||
``` |
||||
|
||||
#### Parameters |
||||
|Type|Name|Description|Required|Schema|Default| |
||||
|----|----|----|----|----|----| |
||||
|QueryParameter|ids|Place ID from Mapzen Search.|false|string (string)|| |
||||
|
||||
|
||||
#### Responses |
||||
|HTTP Code|Description|Schema| |
||||
|----|----|----| |
||||
|200|ok|No Content| |
||||
|
||||
|
||||
### Searches for the name of a place based on a lon/lat location. Used for address reverse geocoding, point of interest (POI) reverse geocoding, and reverse coarse geocoding. |
||||
``` |
||||
GET /reverse |
||||
``` |
||||
|
||||
#### Parameters |
||||
|Type|Name|Description|Required|Schema|Default| |
||||
|----|----|----|----|----|----| |
||||
|QueryParameter|point.lon|tk|true|number (float)|| |
||||
|QueryParameter|point.lat|tk|true|number (float)|| |
||||
|QueryParameter|boundary.circle.lon|tk|true|number (float)|| |
||||
|QueryParameter|boundary.circle.lat||false|number (float)|| |
||||
|QueryParameter|boundary.circle.radius|bounding circle radius (in KM).|false|number (float)|| |
||||
|QueryParameter|boundary.country|Limits search to only return matches within a specific country. Accepts 2 or 3 letter country codes based on ISO [Alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Current_codes) or [Alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Current_codes) abbreviations.|false|string (string)|| |
||||
|QueryParameter|layers|tk|false|string|| |
||||
|QueryParameter|sources|tk|false|string|| |
||||
|QueryParameter|size||false|integer (int32)|10| |
||||
|
||||
|
||||
#### Responses |
||||
|HTTP Code|Description|Schema| |
||||
|----|----|----| |
||||
|200|GeoJSON FeatureCollection|No Content| |
||||
|
||||
|
||||
### Geocodes a user's search query |
||||
``` |
||||
GET /search |
||||
``` |
||||
|
||||
#### Parameters |
||||
|Type|Name|Description|Required|Schema|Default| |
||||
|----|----|----|----|----|----| |
||||
|QueryParameter|text|User's search string|true|string (string)|| |
||||
|QueryParameter|focus.point.lon|Focal point longitude. Ideally a user's device location, but can also be a focal point. Used to provide results close to the user, while still finding good matches globally. Used in conjunction with `focus.point.lat`. Accepts only WGS84 longitutdes.|false|number (float)|| |
||||
|QueryParameter|focus.point.lat|Focal point latitude. Used to provide results close to the user, while still finding good matches globally. Used in conjunction with `focus.point.lon`. Accepts only WGS84 latitudes.|false|number (float)|| |
||||
|QueryParameter|focus.viewport.min_lon|`focus.viewport` provides focus to user's viewable map area, using the viewable screen to calibrate results relevant for an end-user's area of interest based on what's on screen, where that is located, and the level of zoom. |
||||
|
||||
This parameter limits the user's viewport latitude (furthest bottom coordinate). Used to provide results close to the user, while still finding good matches globally. Used in conjunction with `focus.viewport.min_lat`, `focus.viewport.min_lon`, `focus.viewport.max_lon`, and `focus.viewport.max_lat`. |
||||
|
||||
Accepts only WGS84 longitudes. |
||||
|false|number (float)|| |
||||
|QueryParameter|focus.viewport.min_lat|This parameter limits the user's viewport longitude (furthest left coordinate). Used to provide results close to the user, while still finding good matches globally. Used in conjunction with `focus.viewport.min_lat`, `focus.viewport.min_lon`, `focus.viewport.max_lon`, and `focus.viewport.max_lat`. |
||||
Accepts only WGS84 latitudes. |
||||
|false|number (float)|| |
||||
|QueryParameter|focus.viewport.max_lon|This parameter limits the user's viewport latitude (furthest right coordinate). Used to provide results close to the user, while still finding good matches globally. Used in conjunction with `focus.viewport.min_lat`, `focus.viewport.min_lon`, `focus.viewport.max_lon`, and `focus.viewport.max_lat`. |
||||
|
||||
Accepts only WGS84 longitudes. |
||||
|false|number (float)|| |
||||
|QueryParameter|focus.viewport.max_lat|This parameter limits the user's viewport longitude (furthest top coordinate). Used to provide results close to the user, while still finding good matches globally. Used in conjunction with `focus.viewport.min_lat`, `focus.viewport.min_lon`, `focus.viewport.max_lon`, and `focus.viewport.max_lat`. |
||||
Accepts only WGS84 latitudes. |
||||
|false|number (float)|| |
||||
|QueryParameter|layers|For more than one layer, accepts a comma separated list of valid layers. If any of those layers is invalid, the request will still be honored, but a warning will be noted in the `geocoding` block of the response. |
||||
|false|string (string)|| |
||||
|QueryParameter|sources|tk|false|string|| |
||||
|QueryParameter|boundary.circle.lon|tk|false|number (float)|| |
||||
|QueryParameter|boundary.circle.lat|tk|false|number (float)|| |
||||
|QueryParameter|boundary.circle.radius|Maximum distance in meters from the centroid to search from. Forms the radius of a bounding circle.|false|number (float)|| |
||||
|QueryParameter|boundary.rect.min_lon||false|number (float)|| |
||||
|QueryParameter|boundary.rect.min_lat||false|number (float)|| |
||||
|QueryParameter|boundary.rect.max_lon||false|number (float)|| |
||||
|QueryParameter|boundary.rect.max_lat||false|number (float)|| |
||||
|QueryParameter|boundary.country|Limits search to only return matches within a specific country. Accepts 2 or 3 letter country codes based on ISO [Alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Current_codes) or [Alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Current_codes) abbreviations. |
||||
|false|string (string)|| |
||||
|QueryParameter|size|Maximum number of possible matching places to be returned|false|integer (int32)|10| |
||||
|QueryParameter|private|Option to disable query logging in Mapzen Search. Defaults to False.|false|boolean|false| |
||||
|
||||
|
||||
#### Responses |
||||
|HTTP Code|Description|Schema| |
||||
|----|----|----| |
||||
|200|a GeoJSON FeatureCollection array of geocoded places|No Content| |
||||
|400|invalid request. Check that you are passing along valid parameters|No Content| |
||||
|403|invalid API key. Register for a valid API key at the [Mapzen Developer Portal](https://mapzen.com/developer).|No Content| |
||||
|
||||
|
||||
#### Tags |
||||
|
||||
* forward geocoding |
||||
* search |
||||
|
||||
Loading…
Reference in new issue