You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
211 lines
8.3 KiB
211 lines
8.3 KiB
swagger: '2.0' |
|
################################################################################ |
|
# API Information # |
|
################################################################################ |
|
info: |
|
title: Pelias API |
|
description: | |
|
Search the world with Pelias by Mapzen |
|
---------- |
|
|
|
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). |
|
|
|
# Pelias and Client-Side Javascript on the Web |
|
Pelias is designed to easily work with client-side javascript you may write on the web. If you are already using [Leaflet](http://leafletjs.com) to display your map tiles, we provide a [leaflet plugin](https://github.com/pelias/leaflet-geocoder) to simplify the process. |
|
|
|
If you are writing your own code to integrate with Pelias, you should know that Pelias supports [Cross-Resource Origin Sharing (CORS)](https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS), a standard to allow a web page to use a javascript/JSON resource from a domain different than the one you're serving your site from. |
|
|
|
## Do you support JSONP? |
|
Pelias does not currently support JSONP, another standard for |
|
|
|
|
|
|
|
version: "1.0.0" |
|
# the domain of the service |
|
host: pelias.mapzen.com |
|
# array of all schemes that your API supports |
|
schemes: |
|
- http |
|
- https |
|
# will be prefixed to all paths |
|
basePath: /v1 |
|
produces: |
|
- application/vnd.geo+json |
|
- application/json |
|
################################################################################ |
|
# Security # |
|
################################################################################ |
|
securityDefinitions: |
|
api_key: |
|
type: apiKey |
|
name: api_key |
|
in: query |
|
description: | |
|
Use of Mapzen Search service requires an API key. Register for a free API key at the [Mapzen Developer Portal](https://mapzen.com/developer). |
|
|
|
We have generous rate limits (30,000 requests/day, 3 requests/second), and if you require more capacity, you can [run Pelias](https://github.com/pelias/vagrant) on your own servers, or [get in touch](mailto:pelias@mapzen.com) with the team at Mapzen. |
|
|
|
Use of the Mapzen Place Search API uses API tokens as part of the URL parameters like: |
|
<code> |
|
https://pelias.mapzen.com/v1/search?text=New York City&api_key=pelias-prod-xxxxxx</code> |
|
|
|
By clicking the Authenticate button above, you can paste your API Key in from the [Mapzen Developer Portal](https://mapzen.com/developer), |
|
security: |
|
- api_key: [] |
|
|
|
################################################################################ |
|
# API Calls # |
|
################################################################################ |
|
paths: |
|
/search: |
|
get: |
|
tags: |
|
- forward geocoding |
|
- search |
|
summary: Geocodes a user's search query |
|
parameters: |
|
- name: text |
|
in: query |
|
description: User's search string |
|
required: true |
|
type: string |
|
format: string |
|
|
|
- name: focus.point.lon |
|
in: query |
|
description: 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. |
|
required: false |
|
type: number |
|
format: float |
|
|
|
- name: focus.point.lat |
|
in: query |
|
description: 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. |
|
required: false |
|
type: number |
|
format: float |
|
|
|
- name: focus.viewport.min_lon |
|
in: query |
|
description: | |
|
`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. |
|
required: false |
|
type: number |
|
format: float |
|
|
|
- name: focus.viewport.min_lat |
|
in: query |
|
description: | |
|
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. |
|
required: false |
|
type: number |
|
format: float |
|
|
|
- name: focus.viewport.max_lon |
|
in: query |
|
description: | |
|
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. |
|
required: false |
|
type: number |
|
format: float |
|
|
|
- name: focus.viewport.max_lat |
|
in: query |
|
description: | |
|
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. |
|
required: false |
|
type: number |
|
format: float |
|
|
|
- name: layer |
|
in: query |
|
type: string |
|
format: string |
|
description: | |
|
//TK |
|
|
|
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 thrown in the `geocoding` block of the response. |
|
required: false |
|
collectionFormat: csv |
|
|
|
- name: source |
|
in: query |
|
required: false |
|
type: string |
|
collectionFormat: csv |
|
description: tk |
|
|
|
|
|
- name: boundary.circle.lon |
|
in: query |
|
required: false |
|
type: number |
|
format: float |
|
description: tk |
|
minimum: -180.0 |
|
maximum: 180.0 |
|
|
|
- name: boundary.circle.lat |
|
in: query |
|
required: false |
|
type: number |
|
format: float |
|
description: tk |
|
minimum: -90 |
|
maximum: 90 |
|
|
|
- name: boundary.circle.radius |
|
in: query |
|
required: false |
|
type: number |
|
format: float |
|
description: Maximum distance in meters from the centroid to search from. Forms the radius of a bounding circle. |
|
|
|
- name: boundary.rect |
|
in: query |
|
type: number |
|
|
|
- name: boundary.country |
|
in: query |
|
type: string |
|
|
|
- name: size |
|
in: query |
|
type: integer |
|
format: int32 |
|
minimum: 1 |
|
maximum: 50 |
|
default: 10 |
|
required: no |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
security: |
|
- api_key: [] |
|
|
|
responses: |
|
200: |
|
description: a GeoJSON FeatureCollection array of geocoded places |
|
|
|
|
|
################################################################################ |
|
# Definitions # |
|
################################################################################
|
|
|