Addrova

SDK Python

Le paquet addrova est le client Python officiel. Il demande Python 3.10 ou plus et une seule dépendance, httpx. Les clients synchrone (Addrova) et asynchrone (AsyncAddrova) ont les mêmes méthodes.

Installation

Le paquet n'est pas encore publié sur PyPI ; installez-le depuis le dépôt. [À VÉRIFIER : publication sur PyPI]

pip install ./sdk/python
export ADDROVA_API_KEY=adr_live_…

Géocoder, inverse, autocomplétion, réparation

from addrova import Addrova

with Addrova() as client:  # clé lue dans ADDROVA_API_KEY
    r = client.geocode("4 place d'Armes, Belfort", country="FR")
    best = r["results"][0]
    print(best["label"], best["location"], best["confidence_level"])
    print(r["attribution"])  # à afficher avec les résultats (licences)

    client.reverse(47.6376, 6.8626)
    client.autocomplete("4 place d'ar", focus=(47.64, 6.86), session="checkout-123")
    fix = client.repair("4 pl darmes belfor", country="FR")
    print(fix["status"], [(c["field"], c["reason"]) for c in fix.get("changes", [])])
    print(client.usage())
    print([c["country"] for c in client.coverage()["countries"]])  # pays couverts, sources, licences

Pour le client asynchrone, utilisez AsyncAddrova, async with et await client.geocode(...).

Fichiers par lot

with Addrova() as client:
    job = client.submit_batch("clients.csv", address_column="adresse", country="FR")
    job = client.wait_batch(job["id"])
    open("clients-geocodes.csv", "wb").write(client.batch_result(job["id"]))
    client.delete_batch(job["id"])  # purge immédiate (sinon automatique après la rétention)

Erreurs et nouvelles tentatives

  • Le SDK réessaie automatiquement sur 429 rate_limited, les erreurs 5xx et les erreurs réseau, avec backoff exponentiel et gigue, en respectant Retry-After. max_retries vaut 3 par défaut.
  • Exceptions typées : AuthenticationError, InvalidRequestError (dont UnsupportedCountryError pour un pays non couvert), NotFoundError, ConflictError, RateLimitError, QuotaExceededError (sans nouvelle tentative), ServerError et TransportError. Toutes dérivent d'AddrovaError et portent status, code et request_id, jamais l'adresse envoyée.

Confidentialité

geocode envoie l'adresse dans le corps d'un POST, jamais dans l'URL. Le SDK ne journalise aucune adresse, et retire aussi la chaîne de requête des URL journalisées par httpx. Ce que l'API journalise et conserve figure sur la page conformité.