Précision d’un géocodage : rooftop, street, centroid et locality

Un géocodeur renvoie toujours un point, mais tous les points ne veulent pas dire la même chose. Addrova indique la nature du point dans le champ precision de chaque résultat, pour que votre code décide quoi en faire. Ce guide explique les quatre valeurs et ce qu’il faut en faire.

L’URL de base https://api.addrova.eu n’est pas encore en ligne. Tout ce qui suit suit la spécification de l’API. [À VÉRIFIER : service ouvert, URL de base définitive.]

Les quatre valeurs

`precision`	Ce qu’est le point	Usage typique
`rooftop`	Le point d’adresse du bâtiment ou de l’entrée dans le registre officiel	Tournées de livraison, visites de site, épingles de carte
`street`	Un point sur la géométrie de la rue, car le numéro n’est pas dans le registre	Analyse à l’échelle de la rue, avec un avertissement visible
`centroid`	Le centre d’un lieu nommé plus petit qu’une commune, comme un lieu-dit	Zones rurales ; ne pas présenter comme une porte
`locality`	Le centre de la commune. Les adresses CEDEX et boîtes postales reviennent aussi en `locality`, avec `components.cedex` ou `components.po_box`	Statistiques régionales, contrôle de code postal

Les noms décrivent la géométrie, pas une promesse en mètres. La distance entre le point et la vraie porte dépend du registre et du pays. Addrova n’annonce aucun chiffre de précision pour un pays avant de l’avoir mesuré : voyez la couverture pour les pays disponibles aujourd’hui et la page banc d’essai pour ce qui est mesuré à ce jour.

Pourquoi la précision et la confiance sont deux champs

precision dit quelle sorte de point vous avez reçu. confidence est la probabilité estimée que le résultat soit correct à cette précision. Un résultat locality peut avoir une confiance élevée et rester inutile pour une tournée, et un résultat rooftop peut avoir une confiance faible parce que la saisie était ambiguë. Utilisez les deux, et lisez le guide de la confiance avant de fixer un seuil.

Demander une adresse, lire la précision

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}'

Chaque résultat porte precision, confidence, confidence_level et confidence_calibrated, avec l’attribution à conserver si vous stockez le résultat.

Une règle d’aiguillage simple

Aiguillez les résultats selon la précision avant de leur faire confiance. Cet exemple accepte les points à la porte, signale ceux à la rue pour une relecture, et rejette le reste pour le cas d’usage « point de livraison ».

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 "accepter"
    if precision == "street":
        return "relire"
    return "rejeter"  # centroid et locality ne sont pas une porte

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

À savoir

Hameaux et lieux-dits reviennent en centroid : le registre donne le lieu, pas chaque maison. Montrez-les comme une zone, pas comme une épingle sur une porte.
CEDEX et boîtes postales sont un bureau de distribution, pas un bâtiment : locality avec components.cedex ou components.po_box.
Le géocodage inverse renvoie l’adresse la plus proche avec distance_m, la distance au point envoyé. Vérifiez cette distance en plus de la précision.
N’arrondissez pas l’histoire : si votre produit affiche une épingle, affichez la précision à côté quand elle n’est pas rooftop.

Essayer

Le bac à sable de l’accueil permet d’envoyer une adresse et de lire ces champs, sans compte. [À VÉRIFIER : bac à sable relié à l’API réelle.]