Geocoding precision levels: rooftop, street, centroid and locality

A geocoder always returns a point, but not every point means the same thing. Addrova states what kind of point it is in the precision field of each result, so that your code can decide what to do with it. This guide explains the four values and what to do with each.

The base URL https://api.addrova.eu is not live yet. Everything below follows the API specification. [À VÉRIFIER : service ouvert, URL de base définitive.]

The four values

`precision`	What the point is	Typical use
`rooftop`	The address point of the building or entrance in the official register	Delivery routing, site visits, map pins
`street`	A point on the street geometry, because the house number is not in the register	Street-level analysis, with a visible warning
`centroid`	The centre of a named place smaller than a town, such as a hamlet (lieu-dit in France)	Rural areas; do not present as a door
`locality`	The centre of the town. CEDEX and PO box addresses also come back as `locality`, with `components.cedex` or `components.po_box` set	Regional statistics, postcode checks

The names describe the geometry, not a promise of metres. How close a point is to the real door depends on the register and the country. Addrova announces no accuracy figure for a country before it has been measured: see coverage for the countries live today and the benchmark page for what has been measured so far.

Why precision and confidence are two fields

precision says what kind of point you got. confidence is the estimated probability that the result is correct at that precision. A locality result can have a high confidence and still be useless for a delivery route, and a rooftop result can have a low confidence because the input was ambiguous. Use both, and read the confidence guide before you set a threshold.

Ask for an address, read the precision

curl -s https://api.addrova.eu/v1/geocode \
  -H "X-API-Key: $ADDROVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"q": "4 place d'\''Armes, Belfort", "country": "FR", "limit": 3}'

Each result carries precision, confidence, confidence_level and confidence_calibrated, plus the attribution you must keep when you store it.

A simple routing rule

Route results by precision before you trust them. This example accepts door-level points, flags street-level ones for a human, and rejects the rest for the use case "delivery point".

import os
import requests

resp = requests.post(
    "https://api.addrova.eu/v1/geocode",
    headers={"X-API-Key": os.environ["ADDROVA_API_KEY"]},
    json={"q": "4 place d'Armes, Belfort", "country": "FR", "limit": 3},
    timeout=10,
)
resp.raise_for_status()

def decide(result: dict) -> str:
    precision = result["precision"]
    if precision == "rooftop":
        return "accept"
    if precision == "street":
        return "review"
    return "reject"  # centroid and locality are not a door

for r in resp.json()["results"]:
    print(decide(r), r["precision"], r["label"])

Things worth knowing

Hamlets and lieux-dits come back as centroid: the register gives the place, not each house. Show them as an area, not as a pin on a door.
CEDEX and PO boxes are a delivery office, not a building: locality with components.cedex or components.po_box.
Reverse geocoding returns the nearest address with distance_m, the distance from the point you sent. Check that distance as well as the precision.
Do not round the story: if your product shows a pin, show the precision beside it when it is not rooftop.

Try it

The sandbox on the home page lets you send an address and read these fields, without an account. [À VÉRIFIER : bac à sable relié à l’API réelle.]