Addrova

Python SDK

The addrova package is the official Python client. It needs Python 3.10 or later and a single dependency, httpx. Synchronous (Addrova) and asynchronous (AsyncAddrova) clients have the same methods.

Install

The package is not published on PyPI yet; install it from the repository. [À VÉRIFIER : publication sur PyPI]

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

Geocode, reverse, autocomplete, repair

from addrova import Addrova

with Addrova() as client:  # key read from 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"])  # display it with the results (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"]])  # covered countries, sources, licences

For the asynchronous client, use AsyncAddrova, async with and await client.geocode(...).

Batch files

with Addrova() as client:
    job = client.submit_batch("clients.csv", address_column="adresse", country="FR")
    job = client.wait_batch(job["id"])
    open("clients-geocoded.csv", "wb").write(client.batch_result(job["id"]))
    client.delete_batch(job["id"])  # purge now (otherwise automatic after the retention period)

Errors and retries

  • The SDK retries automatically on 429 rate_limited, 5xx errors and network errors, with exponential backoff and jitter, honouring Retry-After. max_retries is 3 by default.
  • Typed exceptions: AuthenticationError, InvalidRequestError (including UnsupportedCountryError for a country that is not covered), NotFoundError, ConflictError, RateLimitError, QuotaExceededError (not retried), ServerError and TransportError. All derive from AddrovaError and carry status, code and request_id, never the address you sent.

Privacy

geocode sends the address in the body of a POST, never in the URL. The SDK logs no address, and it also strips the query string from the URLs that httpx logs. What the API logs and keeps is on the compliance page.