Determining Result Quality¶
Each result contains several different properties to help you programmatically determine if a result is good enough for your purposes.
match_type
¶
This field is present on queries to the search and structured search endpoints only.
match_type |
Meaning |
---|---|
exact |
The API believes it has found an exact match for what you were searching for. |
interpolated |
The API believes that you are searching for a street address, but an exact match was not found in our database. However, the API was able to interpolate a result between known addresses along the road geometry. |
fallback |
Neither an exact match nor an an interpolated match could be found, so the API attempted to fall back (ex: to a street or city) following logical spatial relationships in an intelligent manner. |
Some examples:¶
A query for a nonexistent address like 123 missing street, Seattle, WA
will return a result for Seattle, WA
with a match_type
of fallback
.
A query for France
will return a result, with match_type
of exact
. However, a query for a nonexistent city like
Berlin, France
will also return a result for the country of France, but it will have a match_type
of fallback
.
The API is able to determine that you were looking for something named Berlin in the country France.
It couldn't find it, so instead of returning one of the many other places named Berlin, it returns France.
confidence
¶
confidence
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 the Pelias backend. It is not super sophisticated, and the result
with the highest confidence score is not necessarily the best in all cases. Generally, results returned first
should be trusted more.
Confidence scores have endpoint-specific meanings (noted below), and are expressed as a floating point number between 0 and 1.
Reverse Geocoding¶
Confidence is based on distance from the search point.
confidence |
Distance |
---|---|
1.0 | < 1 meter |
0.9 | < 10 meters |
0.8 | < 100 meters |
0.7 | < 250 meters |
0.6 | < 1km |
0.5 | >= 1km |
Forward Geocoding and Autocomplete¶
For forward geocoding and autocomplete, several factors affect the score:
- The
match_type
, as described above - Whether the postal code matched (postal codes must be an optional part of all queries since not all records have known postal codes)
- For address results, whether the house number 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.
layer
¶
This lets you know which layer the result came from. The layers
parameter (comma-separated list) can be
used in all queries to filter out undesired results if you know what type(s) of data you are looking for.
source
¶
This lets you know which source the result came from. The sources
parameter (comma-separated list) can
be used in all queries to filter out undesired results if you know which source(s) are the most useful for your search.
In many cases, you should consider the layer first, but source can also be useful.
accuracy
¶
The accuracy field gives information on the accuracy of the geographic coordinates in the result. This value is a property of the result itself and won't change based on the query.
accuraty |
Meaning |
---|---|
point |
Generally addresses, venues, or interpolated addresses. A point result means that the record can reasonably be represented by a single geographic point. |
centroid |
Records that represent a larger area, such as a city or country. These cannot be represented by a single point, so a centroid is given instead. |