Skip to content

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.