diff --git a/swagger-docs/definitions.md b/swagger-docs/definitions.md deleted file mode 100644 index e69de29..0000000 diff --git a/swagger-docs/overview.md b/swagger-docs/overview.md deleted file mode 100644 index 704b9d6..0000000 --- a/swagger-docs/overview.md +++ /dev/null @@ -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 - - diff --git a/swagger-docs/paths.md b/swagger-docs/paths.md deleted file mode 100644 index 27df101..0000000 --- a/swagger-docs/paths.md +++ /dev/null @@ -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 - diff --git a/swagger-docs/pelias-v1-api-swagger.yml b/swagger-docs/pelias-v1-api-swagger.yml deleted file mode 100644 index 0b582d7..0000000 --- a/swagger-docs/pelias-v1-api-swagger.yml +++ /dev/null @@ -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: - - https://pelias.mapzen.com/v1/search?text=New York City&api_key=pelias-prod-xxxxxx - - 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 # -################################################################################