Skip to Content
GeocodingHow-to guidesCertify a new country

Certify a new country

For: implementers and product owners.

Before you promise geocoding by address in a country, measure what share of the customers’ real addresses the system locates correctly. This guide describes what is needed, what is measured and how the decision is made.

What a country needs

PieceWhat forRequiredToday
Administrative boundaries (communes, districts) with code, name and polygonThe district check. Without them, every place in the country needs reviewYesChile (communes, CUT code), Peru (districts, ubigeo)
Internal addresses (street, number, district, point)Locate addresses at no costNoChile (OpenAddresses)
A certified providerLocate the addresses that are not in the internal sourcesNo, but without it addresses go to reviewChile: Mapbox in use, with no measurement published here. Peru: none certified
How the customer writes its addressesChoose the spreadsheet columnsYesPer customer

The boundaries and the internal addresses are country data loaded into the platform. The rest of the system (source order, cache, quota, API) does not change.

Gather the test addresses

Take real addresses, in the format the customer writes them. Split them into groups that behave differently:

GroupExample category
Capital, street and numberAv. Arequipa 1234, Lince
Provinces, street and numberA secondary city
No numberS/N, Km 12 Carretera Central
Block and lotMz. B Lt. 4
Named placesA port, an industrial park

Each group needs its own result: a good average can hide a group where nothing works. Weight the result by the share of each group in the customer’s real trips.

Get the true point of each address

For each address, get its correct point: from the internal addresses, from the customer, from a GPS route that ended there, or marked by hand. Without a correct point, an address cannot be used to measure.

Measure

The measurement is done outside the platform, with a script that calls the provider’s API: the platform does not expose the candidates and, without permanent mode, sends everything to review. Call without storing results (Mapbox with permanent=false) and store only the metrics.

MetricWhat it says
UsableThe result is address-level, falls in the correct district (checked with the polygon) and is a short distance from the correct point
Median distance to the correct pointHow far off the geofence ends up
Result levelHow often it returns only a street, a neighborhood or a city
Would go to reviewHow many would go to To review with the system’s rules

Before measuring, define what percentage of usable results and what distance the customer accepts. That is the certification threshold.

Pitfall: compare the district by polygon, not by the name the provider returns. Some providers leave out the district in metropolitan areas, and comparing by name gives a false result.

Validate in production

Before certifying, resolve a batch of pilot addresses in the customer’s organization, with a limited quota, and check To review and Monthly usage. What happens there decides.

Decide

ResultWhat to offer
CertifiedAddresses by spreadsheet, with review of the cases that fail
Not certifiedPlus Code or coordinates in the spreadsheet, existing geofences, and manual review

Example: Peru

Measurement of 2026-10-29: 440 addresses in Peru, grouped by type, with the district checked by polygon (INEI boundaries). No provider was certified:

GroupMapbox usableGoogle usable
Lima, street and number55%68%
Provinces5%45%
Block and lot, kilometer, no numberless than 15%less than 15%
Total, weighted by the share of each group22%39%

The addresses from the pilot trips are still missing; they decide the certification.

In Peru, the recommendation is to ask for Plus Code or coordinates in the spreadsheet, or to use geofences already drawn. Addresses that still arrive go through the cache and the provider, and those that fail go to review.

Known pitfalls

PitfallEffect
Asking for results in a language (language=es in Mapbox)Makes results worse in Peru. The platform does not send it
Measuring with permanent modeCosts more and stores results. Measure without it
Using only addresses from the capitalOverestimates the result
A district name that repeats in the countryThe system asks for the code. The spreadsheet must carry the code or a unique name
Last updated on