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 # ################################################################################