pelias
/
documentation
mirror of https://github.com/pelias/documentation.git
1
0
Fork 0
Code Issues Releases Activity
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.
100 Commits
5 Branches
0 Tags
13 MiB
 
Tree: 6948774efc
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from '6948774efc'
${ noResults }
documentation/swagger-docs/pelias-v1-api-swagger.yml

396 lines
14 KiB
Raw Blame History

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
- name: sources
in: query
required: false
type: string
collectionFormat: csv
description: tk
- 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: 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.
# 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
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 #
################################################################################