Salta al contenuto
NetCov

Guide · Django

Guide / Django

Verifica copertura in Django con l’SDK Python

Chiave in settings, un service layer con netcov-sdk, proxy di autocomplete con cache e template che mostra summary per tecnologia. Installazione: pip install netcov-sdk (al lancio; oggi dal repo GitHub).

1 · Configurazione e service layer

La chiave vive nelle impostazioni e viene passata esplicitamente al client. Nota: ogni risposta porta un notice di precisione — leggilo sempre, invece dello stato condiviso del client.

python
# settings.py
NETCOV_API_KEY = os.environ["NETCOV_API_KEY"]
NETCOV_BASE_URL = os.environ.get("NETCOV_BASE_URL", "https://api.netcov.io")

# services.py
from django.conf import settings
from netcov_sdk import NetCov

client = NetCov(
    api_key=settings.NETCOV_API_KEY,
    base_url=settings.NETCOV_BASE_URL,
    retry=False,  # nei percorsi web decidi tu quando riprovare
)

def coverage_for(address: str):
    return client.coverage_italy(address=address, strict=True)

2 · Autocomplete via view proxy (con cache)

Il form chiama la tua view (stesso dominio, niente CORS), che interroga l’API e mette in cache per città+query: proteggi la quota giornaliera dal traffico a ogni tasto. Nel template evidenzia main_text con gli offset di matches.

python
# views.py — autocomplete proxy con cache (60 s per città+query)
from django.core.cache import cache
from django.http import JsonResponse

def autocomplete(request):
    city = request.GET.get("city", "").strip()
    q = request.GET.get("address", "").strip()
    if len(q) < 2:
        return JsonResponse({"results": []})
    key = f"netcov:ac:{city}:{q}".strip().lower()
    if (hit := cache.get(key)) is not None:
        return JsonResponse(hit)
    results = [
        {
            "kind": r.kind, "display": r.display,
            "main_text": r.main_text, "matches": r.matches,
            "code": r.code,
        }
        for r in client.autocomplete(city=city, address=q)
    ]
    # Stessa forma della risposta API (results + attribution): il client
    # che consuma questa view non deve cambiare se passi al proxy Next.js.
    body = {
        "results": results,
        "attribution": "Fonte: Istat – Agenzia delle Entrate, Archivio "
        "Nazionale dei Numeri Civici e delle Strade Urbane (ANNCSU)",
    }
    cache.set(key, body, 60)
    return JsonResponse(body)

Domande frequenti

Riferimenti: codici di errore, API Playground, README del pacchetto Python ↗.

Come configuro la chiave API in Django?

In settings.py leggi NETCOV_API_KEY e NETCOV_BASE_URL dall'ambiente (django-environ o os.environ) e passa entrambi esplicitamente a NetCov(api_key=..., base_url=...). Non affidarti ai default in produzione: l'SDK avvisa se usi il localhost di sviluppo con una chiave impostata.

Posso condividere un client tra le richieste?

Sì: un'istanza condivisa va bene (connection pooling di httpx), ma non usare client.last_notice tra richieste — è stato condiviso e si sovrascrive. Usa geocode_response(...).notice oppure coverage.notice, che sono per-chiamata.

Come uso l'SDK nelle view asincrone?

Usa AsyncNetCov con await (stessi metodi della versione sincrona) oppure avvolgi il client sincrono con sync_to_async. Disabilita il retry automatico (retry=False) nei percorsi dove non puoi attendere: solleva ApiError con retry_after e decidi tu.

Quanta quota consumano autocomplete e copertura?

Ogni chiamata di autocomplete e ogni chiamata di copertura consumano quota del tuo piano (chiavi gratuite: circa 30 richieste al minuto e 1.000 al giorno). L'autocomplete ha un budget separato e più ampio (15x). Debounce di 250 ms e cache di 60 secondi tengono i consumi sotto controllo; /credits mostra i residui in tempo reale.

Pronto a integrare?

Crea la chiave gratuita per integrare, oppure prova gli endpoint nel Playground senza account. Guide per altri stack: Guida Next.js, Guida WordPress.

Crea la tua chiave gratuitaProva nel Playground