pelias
/
documentation
mirror of https://github.com/pelias/documentation.git
1
0
Fork 0
Code Issues Releases Activity
Browse Source

Removes Swagger from master repository 

Should we want to revitalize the work with Swagger, this lives in its own branch now at: https://github.com/pelias/pelias-doc/tree/swagger-docs
pull/17/head
Riordan 9 years ago
parent
2c806be0d5
commit
d66b16d779
4 changed files with 0 additions and 501 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Unified View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 0
      swagger-docs/definitions.md
  2. 24
      swagger-docs/overview.md
  3. 122
      swagger-docs/paths.md
  4. 355
      swagger-docs/pelias-v1-api-swagger.yml

0
swagger-docs/definitions.md
Unescape View File

24
swagger-docs/overview.md
Unescape View File

@ -1,24 +0,0 @@
# 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

122
swagger-docs/paths.md
Unescape View File

@ -1,122 +0,0 @@
## 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|
### Takes the coordinates of a location and searches for the name or address of the place it's from.
```
GET /reverse
```
#### Parameters
|Type|Name|Description|Required|Schema|Default|
|----|----|----|----|----|----|
|QueryParameter|point.lon||true| (float)||
|QueryParameter|point.lat||true| (float)||
|QueryParameter|boundary.circle.lon||false|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|layer||false|||
#### Responses
|HTTP Code|Description|Schema|
|----|----|----|
|200|All Good.|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 thrown 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

355
swagger-docs/pelias-v1-api-swagger.yml
Unescape View File

@ -1,355 +0,0 @@
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 #
################################################################################
Write Preview
Loading…
Cancel
Save