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.
355 lines
12 KiB
355 lines
12 KiB
swagger: '2.0' |
|
################################################################################ |
|
# API Information # |
|
################################################################################ |
|
info: |
|
title: Mapzen Search API |
|
description: | |
|
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: "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 |
|
################################################################################ |
|
# 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 [MapzenDeveloper 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: layers |
|
in: query |
|
type: string |
|
format: string |
|
description: | |
|
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: sources |
|
in: query |
|
required: false |
|
type: string |
|
collectionFormat: csv |
|
description: tk |
|
|
|
# BOUNDARY CIRCLE |
|
- 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. |
|
|
|
# BOUNDARY RECTANGLE |
|
- name: boundary.rect.min_lon |
|
in: query |
|
type: number |
|
format: float |
|
- name: boundary.rect.min_lat |
|
in: query |
|
type: number |
|
format: float |
|
- name: boundary.rect.max_lon |
|
in: query |
|
type: number |
|
format: float |
|
- name: boundary.rect.max_lat |
|
in: query |
|
type: number |
|
format: float |
|
|
|
|
|
- name: boundary.country |
|
in: query |
|
format: string |
|
type: string |
|
description: | |
|
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. |
|
|
|
|
|
|
|
- name: size |
|
in: query |
|
type: integer |
|
format: int32 |
|
minimum: 1 |
|
maximum: 50 |
|
default: 10 |
|
required: false |
|
description: Maximum number of possible matching places to be returned |
|
|
|
|
|
## VIEW NOT BEING IMPLEMENTED AT THIS TIME |
|
# - name: view |
|
# in: query |
|
# type: string |
|
# default: "standard" |
|
# enum: |
|
# - "standard" |
|
# - "mobile" |
|
|
|
- name: private |
|
in: query |
|
type: boolean |
|
default: false |
|
required: false |
|
description: Option to disable query logging in Mapzen Search. Defaults to False. |
|
|
|
|
|
security: |
|
- api_key: [] |
|
|
|
responses: |
|
200: |
|
description: a GeoJSON FeatureCollection array of geocoded places |
|
400: |
|
description: invalid request. Check that you are passing along valid parameters |
|
403: |
|
description: invalid API key. Register for a valid API key at the [Mapzen Developer Portal](https://mapzen.com/developer). |
|
|
|
|
|
|
|
|
|
/autocomplete: |
|
get: |
|
summary: 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. |
|
tags: [search, forward geocoding] |
|
|
|
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 (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. |
|
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 |
|
|
|
security: |
|
- api_key: [] |
|
|
|
responses: |
|
200: |
|
description: A GeoJSON FeatureCollection array of geocoded places. |
|
400: |
|
description: Invalid request. Check that you are passing along valid parameters without conflicting options. |
|
|
|
/reverse: |
|
get: |
|
summary: Takes the coordinates of a location and searches for the name or address of the place it's from. |
|
|
|
parameters: |
|
- name: point.lon |
|
in: query |
|
format: float |
|
required: true |
|
min: -180 |
|
max: 180 |
|
|
|
- name: point.lat |
|
in: query |
|
format: float |
|
required: true |
|
min: -90 |
|
max: 90 |
|
|
|
|
|
- name: boundary.circle.lon |
|
in: query |
|
type: number |
|
format: float |
|
required: false |
|
min: -180 |
|
max: 180 |
|
|
|
- name: boundary.circle.lat |
|
in: query |
|
type: number |
|
format: float |
|
required: false |
|
min: -90 |
|
max: 180 |
|
|
|
- name: boundary.circle.radius |
|
in: query |
|
type: number |
|
format: float |
|
required: false |
|
description: bounding circle radius (in KM). |
|
|
|
- name: boundary.country |
|
in: query |
|
type: string |
|
format: string |
|
required: false |
|
description: 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. |
|
|
|
- name: layer |
|
in: query |
|
|
|
|
|
|
|
|
|
|
|
responses: |
|
200: |
|
description: All Good. |
|
|
|
security: |
|
- api_key: [] |
|
|
|
/place: |
|
get: |
|
summary: Retrieves the full GeoJSON record for a given place. ID determined from the results of a `/search`, `/autocomplete`, or `/reverse` response. |
|
|
|
parameters: |
|
- name: ids |
|
in: query |
|
format: string |
|
type: string |
|
description: Place ID from Mapzen Search. |
|
|
|
|
|
|
|
responses: |
|
200: |
|
description: ok |
|
|
|
security: |
|
- api_key: [] |
|
|
|
|
|
|
|
################################################################################ |
|
# Definitions # |
|
################################################################################
|
|
|