Every endpoint returns a GeoJSON FeatureCollection in the Pelias shape.
The geocoding block
| Field | Meaning |
|---|---|
version | Pelias response version. |
attribution | URL of the data attribution page. |
engine | name and version of the server. |
query | The parsed request: text or fields, size, the tinql that ran, and ranking. |
query.ranking | importance (text score plus importance), importance+distance (with a focus point), or text (a budget ran out and the text score alone was used). |
errors | Present only on errors: human-readable messages. |
Feature properties
Each feature has id, gid, layer, source, name, label and importance, plus the fields that are known for that place: street, postalcode, locality, county, region, country and country_code. Text searches add confidence. Results near a focus point, and all reverse results, add distance in kilometres. The collection also has a bbox of all features.
Status codes
| Status | When |
|---|---|
200 | Success, including an empty result. |
400 | A parameter is missing or invalid. |
502 | The database is unavailable. |
504 | The text-only fallback query ran out of its budget and no rows were found. |
Validation errors
curl 'http://localhost:4000/v1/search'
# HTTP 400
{
"features": [],
"geocoding": {
"errors": [
"missing param 'text'"
]
},
"type": "FeatureCollection"
}
curl 'http://localhost:4000/v1/search?text=cafe&size=99'
# HTTP 400
{
"features": [],
"geocoding": {
"errors": [
"size must be between 1 and 40"
]
},
"type": "FeatureCollection"
}
curl 'http://localhost:4000/v1/search?text=cafe&layers=street'
# HTTP 400
{
"features": [],
"geocoding": {
"errors": [
"unknown layer 'street'; supported: venue, address"
]
},
"type": "FeatureCollection"
}
curl 'http://localhost:4000/v1/search?text=cafe&focus.point.lat=48'
# HTTP 400
{
"features": [],
"geocoding": {
"errors": [
"focus.point.lat and focus.point.lon must be set together"
]
},
"type": "FeatureCollection"
}