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.

Tip

The API always returns results ordered best to worst, using an internal scoring mechanism of all available information. Examining the detailed information is most useful to answer these questions:

  1. Is the result good enough quality? (An address verification tool cannot use fallback results, for example.)
  2. How close is the result to what I searched for (especially for reverse geocoding)?
  3. Which sources are used? Sources often have better data in certain regions than others. This type of local optimization doesn't scale globally, but if your focus is a small area like a city, this can be extremely useful info.

match_type

This field is present on queries to the search and structured search endpoints only.

match_type Meaning
exact An exact match for your search was found.
interpolated Your search looks like a street address, but we couldn't find that house number. The result is a best guess where the requested number lies on the road given other known addresses.
fallback We couldn't find an exact match or interpolate a result, so we fall back to the closest part we can match (ex: a street or city).

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.

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.

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.