# NetCov — full documentation for AI agents

> NetCov is an API for broadband internet coverage in Italy. One call returns
> every access-network technology available at an address (or coordinates):
> FTTH, FTTC/VDSL, FWA, ADSL — each with the operator and declared speeds.
> Data: official AGCOM Broadband Map (CC BY 4.0) + ANNCSU geographic archive
> (CC BY 4.0), refreshed monthly. Site (Italian): https://netcov.io. API:
> https://api.netcov.io. Short index: https://netcov.io/llms.txt. Machine
> spec: https://netcov.io/openapi.json.

## Core facts

- Site language: Italian. API error messages: English.
- Coverage: 7,894 comuni; ~20.7M civic numbers; 745k streets; 13.3M cells.
- Latency ~5 ms median; throughput several thousand req/s.
- Coverage reflects DECLARED data in the AGCOM archive, not a guarantee of
  actual service availability.
- Attribution is REQUIRED on every display of coverage data (see below).

## Authentication

- Header on every call: `Authorization: Bearer gk_live_...`
- Free plan: ~30 req/min, 1,000/day, no expiration. Self-serve keys at
  https://netcov.io/portal (magic-link login, no password).
- Keys are server-side secrets. Never embed them in browser JavaScript,
  except browser-plan keys (origins allowlist, GET-only, Origin-checked).
- Deterministic demo keys (no signup, canned scenarios): demo_gigabit
  (FTTH+VDSL), demo_adsl (ADSL only), demo_none (no technology),
  demo_404 (always 404), demo_429 (always 429 with retry_after).

## Quickstart

```bash
curl "https://api.netcov.io/coverage/italy?address=via%20Toledo%2021,%20Napoli" \
  -H "Authorization: Bearer LA_TUA_CHIAVE"
```

Trimmed real response (Via Toledo 21, Napoli — FTTH gigabit):

```json
{
  "display": "Via Toledo 21 Napoli",
  "notice": null,
  "location": {
    "cap": "80121", "civico": "21", "comune": "napoli",
    "confidence": "high", "latitude": 40.8445309,
    "longitude": 14.2491141, "match": "Via Toledo 21 Napoli",
    "provincia": "Napoli", "regione": "Campania",
    "code": "p4353350"
  },
  "summary": {
    "technologies": ["ftth", "vdsl"],
    "operators": ["Fastweb", "Open Fiber", "TIM Wholesale"],
    "best": { "technology": "ftth", "tier": "gigabit",
              "downlink_mbps": 2500.0, "operator": "Fastweb" }
  }
}
```

## Endpoints (base https://api.netcov.io)

- GET /coverage/italy — params: code= (stable address code, recommended for
  re-querying a stored address) OR address= (free text "..., Comune") OR
  lat= + lon=; optional limit=, strict=1 (404 when the civic does not exist
  instead of falling back; notice explains precision). Returns location
  (comune, civico, cap, latitude, longitude, confidence, stable code),
  cells (one row per operator+technology with best speed kept), summary
  (technologies[], operators[], best{}, by_technology[] sorted by max
  downlink desc). Every response carries attribution + a usage object
  (remaining quota, reset_seconds).
- GET /geocode — normalize an Italian address to comune/via/civico/lat/lon,
  or resolve a stored code= back to the address.
- GET /autocomplete — street/civic/comune suggestions from ANNCSU (city
  param first). Streets carry a civics array with stable codes for "pick a
  civic" chips. Quota: 15x the core limits. Responses carry ETag;
  If-None-Match gives 304. Forms must debounce >=250 ms and cache 60 s per
  city+query. Attribution: ANNCSU string (see below).
- GET /credits — quota snapshot for the key (1 req/s). Attribution: ANNCSU.
- Errors: JSON envelope {"error", "code", "request_id", "doc_url",
  "retry_after?"}, 1:1 with https://netcov.io/errors. Quote request_id in
  support tickets.

## Error codes

### missing_token (401)
Chiave mancante. Cause: La richiesta non ha l'header Authorization. Fix: Aggiungi "Authorization: Bearer gk_live_..." (o la chiave demo_) a ogni richiesta. Docs: https://netcov.io/errors

### invalid_token (401)
Chiave non valida o revocata. Cause: La chiave non esiste, è stata revocata, oppure il token è stato troncato/copiato male. Fix: Verifica la chiave nel portale; se revocata, creane una nuova. Docs: https://netcov.io/errors

### forbidden (403)
Privilegi insufficienti. Cause: Endpoint admin chiamato con una chiave senza privilegi admin. Fix: Usa la chiave admin di sistema per le operazioni di gestione. Docs: https://netcov.io/errors

### bad_request (400)
Parametri non validi. Cause: Parametri mancanti (nessun address/code/lat+lon) o valori fuori range. Fix: Controlla i parametri nella risposta e nella specifica OpenAPI. Docs: https://netcov.io/errors

### address_not_found (404)
Indirizzo non trovato. Cause: Nessun indirizzo corrisponde; in modalità strict anche quando il civico non esiste o manca. Fix: Usa l'autocomplete per suggerimenti reali e invia il code; oppure rimuovi strict=1 e leggi notice. Docs: https://netcov.io/errors

### not_found (404)
Endpoint inesistente. Cause: Percorso URL sbagliato. Fix: Verifica il percorso nella specifica (es. /coverage/italy, senza /v1). Docs: https://netcov.io/errors

### rate_limit_exceeded (429)
Frequenza superata. Cause: Più richieste del limite al minuto (rpm) consentito; il burst è ~5 secondi di margine. Fix: Rispetta retry_after (o l'header Retry-After) prima di ritentare. Il campo usage/credits mostra i limiti. Docs: https://netcov.io/errors

### daily_quota_exceeded (429)
Quota giornaliera esaurita. Cause: Superato il tetto giornaliero del piano. Fix: Attendi il reset UTC di mezzanotte o passa a un piano superiore. Docs: https://netcov.io/errors

### monthly_quota_exceeded (429)
Quota mensile esaurita. Cause: Superato il tetto mensile del piano. Fix: Attendi il reset mensile o passa a un piano superiore. Docs: https://netcov.io/errors

### credits_rate_limited (429)
Endpoint /credits limitato. Cause: Il controllo crediti è limitato a 1 richiesta al secondo per account. Fix: Metti in cache il risultato di /credits invece di chiamarlo a ogni richiesta. Docs: https://netcov.io/errors

### coverage_unavailable (503)
Database di copertura non disponibile. Cause: Il servizio sta aggiornando i dati (refresh mensile) o è in manutenzione. Fix: Riprova tra qualche minuto; durante il refresh il servizio resta in linea quasi sempre. Docs: https://netcov.io/errors

### streets_unavailable (503)
Indice strade non disponibile. Cause: Indice ANNCSU in fase di rebuild. Fix: Riprova tra qualche minuto. Docs: https://netcov.io/errors

### internal (500)
Errore interno. Cause: Errore inatteso del servizio. Fix: Riprova; se persiste, apri un ticket citando il campo request_id della risposta. Docs: https://netcov.io/errors

## SDKs and integrations

- TypeScript: @netcov-io/client (published on npm).
- Python netcov-sdk: coming to PyPI; use direct REST calls meanwhile
  (see https://netcov.io/guide/django).
- MCP server: coming soon. WordPress plugin netcov-coverage: coming soon
  (meanwhile: embed widget or PHP shortcode, https://netcov.io/widget and
  https://netcov.io/guide/wordpress).

## Embed widget (3 lines, demo mode without key)

```html
<div data-netcov-widget
     data-city="Napoli"
     data-address="via Toledo 21">
</div>
<script src="https://netcov.io/netcov-widget.js" async defer></script>
```

Production: proxy server-side holding the key, set
data-endpoint="https://tuosito.it/coverage". Live demo + guide:
https://netcov.io/widget. Interactive console: https://netcov.io/playground.

## Required attribution (byte-exact, from API responses)

- Coverage: "BroadbandMap di Agcom – Autorità per le garanzie nelle
  comunicazioni è distribuito con Licenza Creative Commons Attribuzione 4.0
  Internazionale (https://maps.agcom.it)"
- Geocode/autocomplete/credits: "Fonte: Istat – Agenzia delle Entrate,
  Archivio Nazionale dei Numeri Civici e delle Strade Urbane (ANNCSU)"

## AGCOM obligation this API serves (IT)

Art. 98-quaterdecies CCE (DL 19/2026, in force 20 Feb 2026, sanctions from
20 Jun 2026; AGCOM circular 3 Jul 2026): operators must inform consumers of
ALL access networks available at their address, competitors included.
Full guidance: https://netcov.io/adempimento-agcom. NetCov is a data tool;
compliance responsibility stays with the operator.

## Site map

- / — product overview, technologies, FAQ
- /playground — interactive API console (noindex)
- /sviluppatori — quickstart, demo keys, sample addresses, error summary
- /guide/nextjs, /guide/django, /guide/wordpress — framework guides
- /operatori/reseller — reseller flow; /operatori/api-vs-scraping — vs scraping
- /widget — embed widget; /errors (+ /errors.json) — error docs
- /status — service state; /changelog — additive API changes
- /affidabilita-dati — data limits; /adempimento-agcom — AGCOM guidance
- /prezzi — free permanent key, volume on request; /portal — signup (noindex)
- /contatti, /supporto (noindex), /termini, /privacy, /legale