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).
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.
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.
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`.
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.
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.
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.
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.
