4.5 KiB
Determining Result Quality
Each result returned from Pelias contains several different properties to help you programmatically determine if a result is good enough for your purposes.
layer
This is essentially what type of result was returned, for example whether the result was an address, a city, or a country (a full list of possible layers can be found in the search endpoint documentation).
The layers parameter can be used to filter on this if you know ahead of time what you want. Results returned that are of a different layer than you expect generally mean incorrect results.
match_type
This field is present on queries to the search and structured search endpoints only.
There are three possible values: exact, interpolated, and fallback;
If Pelias found exactly what it believes you were looking for, the match_type value will be exact.
If Pelias determined you are querying for a street address, and could not find that exact address, but was able to estimate where that address might be (if it exists) via the interpolation engine, the match type will be interpolated.
If Pelias wasn't able to return exactly what it thinks you asked for, it will try to return something that relates to your query in an intelligent way. These fallback results will be records that follow the relationships of places in the real world.
Some examples:
A query for [1600 Pennsylvania Avenue, Seattle, Washington](/v1/search?text=1600 Pennsylvania Avenue, Seattle, WA) returns the city of Seattle, since there is no Pennsylvania Avenue in Seattle. In previous versions of Pelias, this query would return 1600 Pennsylvania Avenue addresses in other parts of the world (such as the famous White House address in Washington, D.C.).
A query for France will return one result, with match_type exact. However, a query for the non-existent city of Berlin, France will also return France, but in this case with a match type of fallback. Pelias knows you were looking for something in the country of France called Berlin. It couldn't find it, so instead of returning one of the many other Berlins, it returns France. This demonstrates that the match_type value depends on the query and the result.
confidence
This is a general score computed to calculate how likely result is what was asked for. It's meant to be a combination of all the information available to Pelias.
It's not super sophisticated, and results may not be sorted in confidence-score order. In that case results returned first should be trusted more. Confidence scores are floating point numbers ranging from 0.0 to 1.0.
Confidence scores are calculated differently for different endpoints:
For reverse geocoding it's based on distance from the reverse geocoded point. The progression of confidence scores is as follows:
| distance | confidence score |
|---|---|
| < 1 meter | 1.0 |
| 1 - 10 meters | 0.9 |
| 11 - 100 meters | 0.8 |
| 101 - 250 meters | 0.7 |
| 251 - 1000 meters | 0.6 |
For forward geocoding and autocomplete, several factors affect the score. These factors are:
- the
match_type, as described above - whether the postal code matched (postal codes must be an optional part of all Pelias queries since not all records have known postal codes)
- for address results, whether the housenumber and street name match the input query
- whether any other fields are obviously non-matching (such as the city, region, or country fields).
In all cases, confidence scores for fallback results will be reduced.
accuracy
The accuracy field gives information on the accuracy of the latitude/longitude point returned with the given result. This value is a property of the result itself and won't change based on the query. There are currently two possible values for the accuracy field: point and centroid.
point results are generally addresses, venues, or interpolated addresses. A point result means the record represents a record that can reasonably be represented by a single latitude/longitude point.
centroid results, on the other hand, are records that represent a larger area, such as a city or country. Pelias cannot currently return results with geometries made of polygons or lines, so all such records are estimated with a centroid.