Python SDK

The official navvo Python client is a server-side wrapper over the Navvo Web Service. It is typed, retry-aware, and dependency-free — by default it uses only the Python standard library, so it installs and runs anywhere; if httpx is installed it is used automatically for connection pooling. There is no map UI or tile fetching — for rendering a map in the browser use Navvo Maps.

Requires: Python 3.8+ · Base URL: https://navvo.io/api/v1

Install

pip install navvo
# optional pooled HTTP transport:
pip install "navvo[httpx]"

Authenticate

Every call is sent with the x-api-key header. The key is read from the NAVVO_API_KEY environment variable by default, or pass it explicitly:

from navvo import NavvoClient

navvo = NavvoClient()                       # uses $NAVVO_API_KEY
navvo = NavvoClient("nvvo_your_key_here")   # explicit

The SDK never puts the key in a URL — except style_url(), which builds a browser-fetchable map style URL where the key must ride as ?api_key= (browsers cannot set headers on tile/style requests).

Quickstart

from navvo import NavvoClient, LatLng, BBox

with NavvoClient() as navvo:
    # Forward geocode — string coordinates are parsed to floats for you
    hits = navvo.geocode("Abdali Hospital, Amman", limit=5)
    print(hits[0].lat, hits[0].lng, hits[0].display_name)

    # Plan a route — you pass lat/lng; the SDK serialises lon/lat on the wire
    plan = navvo.route(locations=[
        {"lat": 31.95, "lng": 35.91, "name": "A"},
        {"lat": 31.99, "lng": 35.95, "name": "B"},
    ], costing="auto")
    print("ETA seconds:", plan.trip["summary"]["time"])
    path = plan.geometry()          # decoded polyline -> list[LatLng]

    # Live, condition-aware extras
    wx = navvo.weather_point(31.95, 35.91)
    inc = navvo.incidents(bbox=BBox(35.85, 31.9, 35.99, 31.99), limit=10)

Coordinates — never backwards

You always supply points as LatLng(lat=..., lng=...) (or a {"lat":.., "lng":..} dict / (lat, lng) tuple). The SDK owns every wire-format difference: {lon, lat} for route()/traffic_route(), {lat, lon} for the routing passthrough payloads, separate lat/lon params for reverse geocode, west,south,east,north for BBox, [lng, lat] for GeoJSON, and WKT POINT(lng lat) for place center (parse it with place.center_latlng).

Retries & errors

Transient failures (5xx, 429/quota, network blips) are retried with exponential backoff and full jitter, honouring Retry-After; client errors (400/401/403/404) are never retried. All errors subclass NavvoError:

from navvo.errors import (
    NavvoRateLimitError, NavvoForbiddenError, NavvoServiceUnavailableError,
)

try:
    r = navvo.geocode("Abdali Hospital, Amman")
except NavvoRateLimitError as e:
    print("rate limited, retry after", e.retry_after, "s")
except NavvoForbiddenError as e:
    print("scope/quota problem:", e.reason or e.message)
except NavvoServiceUnavailableError:
    print("geocoder upstream is down — fall back")

The geocoder/routing envelope ({provider, available, data}) is unwrapped for you, and an unknown place slug returns None (a soft-null, not an error).

Method map

Each method maps to the endpoint documented in the API reference. geocode, places, place, route, and matrix return typed objects with the common fields parsed and the full payload preserved on .raw.