# NetCov

> NetCov is an API for broadband internet coverage in Italy. One call to the
> coverage endpoint returns every access-network technology available at an
> address (or coordinates): FTTH, FTTC/VDSL, FWA, ADSL — each with the
> operator and the declared speeds. Data comes from the official AGCOM
> Broadband Map database (CC BY 4.0) and the ANNCSU geographic archive
> (CC BY 4.0), refreshed monthly. The Italian-language website is
> netcov.io; the API lives at api.netcov.io.

## Core facts

- Language of the site: Italian. API error messages: English.
- Coverage data source: Broadband Map di AGCOM (banca dati BroadbandMap di
  Agcom, CC BY 4.0, maps.agcom.it), redistributed per the CC BY 4.0 license.
- Geographic data source: ANNCSU — Istat / Agenzia delle Entrate, Archivio
  Nazionale dei Numeri Civici e delle Strade Urbane (CC BY 4.0).
- Data refresh: monthly, aligned with AGCOM's published updates.
- Italian address coverage: 7,894 comuni; ~20.7 million civic numbers;
  745k indexed streets; 13.3 million coverage cells.
- Latency: ~5 ms median per request; throughput: several thousand req/s.
- Legal note: coverage reflects declared data in the AGCOM archive; it is
  not a guarantee of actual service availability.
- Attribution is required on every display of coverage data (see
  /legale and the OpenAPI spec).

## Authentication

- API keys: Bearer token, "Authorization: Bearer gk_live_..."
- Free plan: ~30 requests/min, 1,000/day, no expiration. Keys are created
  self-serve at /portal (magic-link login, no password).
- Keys must be kept server-side; do not embed them in browser JavaScript,
  except browser-plan keys (see below).
- Embedded browser keys: keys with plan browser carry an origins allowlist.
  They are GET-only and are accepted only when the Origin header (fallback
  Referer) host matches an allowed entry. Use them in the data-key attribute
  of the netcov-widget tag or in public autocomplete forms. Admin endpoints
  POST /admin/keys and POST /admin/keys/{id}/limits accept origins.

## API endpoints (base URL: https://api.netcov.io)

- GET /coverage/italy — query params: code= (stable address code, the
  recommended way to re-query a stored address), or address=... or
  lat=...&lon=... (optional limit=, strict=1). Returns the resolved
  location (object with comune, civico, latitude, longitude, confidence,
  and a stable address code such as "p4353350"; older/composite codes look
  like "napoli/via toledo/21" and both resolve), deduplicated cells
  (one row per operator+technology, best speed kept) and a consumer
  summary object: unique technologies (e.g. ["ftth","fwa"]), unique
  operators, and the best offer (technology/tier/downlink_mbps/operator).
  The summary also carries by_technology: one row per technology with
  technology, max_downlink_mbps, best_speed_tier and operators, sorted by
  max downlink descending with deduplicated strings (mirrors the Python SDK
  by_technology helper).
  Displays use proper Italian case such as Via Crespole e Fabbriche 125
  Pistoia; codes, CAP/postal codes, coordinates and confidence values are
  unchanged.
  strict=1 returns 404 when the civic number does not exist; the notice
  field explains fallback precision.
- GET /geocode — normalize an Italian address to comune/via/civico/lat/lon,
  or resolve a stored code= back to the same address.
- GET /autocomplete — street/civic/comune suggestions from ANNCSU (city
  param first). Street suggestions carry a civics array: the street's
  existing civic numbers, each with a stable code — the form can offer
  "pick a civic" chips and submit the code directly for exact coverage.
  When the address ends in a civic number ("via tol 2") the results are
  civic-level (kind "civico") with codes too. Quota: core limits x15.
  Autocomplete responses carry an ETag header; sending it back in
  If-None-Match returns 304 Not Modified when the suggestion set is
  unchanged. Public forms should debounce autocomplete by at least 250 ms
  and cache results client-side for 60 s per city plus query.
- GET /credits — quota snapshot for the authenticated key (1 req/s).
- Errors: JSON envelope {"error", "code", "request_id", "doc_url",
  "retry_after?"} mapping 1:1 to https://netcov.io/errors. Codes and HTTP
  status: missing_token 401, invalid_token 401, forbidden 403,
  bad_request 400, address_not_found 404, not_found 404,
  rate_limit_exceeded 429, daily_quota_exceeded 429,
  monthly_quota_exceeded 429, credits_rate_limited 429,
  coverage_unavailable 503, streets_unavailable 503, internal 500.
  Quote request_id in support tickets.
- Interactive testing: /playground (browser console, spec-driven).

## SDKs and integrations

- TypeScript: @netcov-io/client (published on npm)
- Python: netcov-sdk (coming to PyPI; use direct REST calls for now)
- MCP server: coming soon
- WordPress plugin: coming soon (use the embed widget or the PHP shortcode in /guide/wordpress for now)
- OpenAPI spec: https://netcov.io/openapi.json (same spec the /playground uses)

## Audience pages

- / — product overview, coverage technologies, FAQ
- /playground — interactive API console (spec-driven, try endpoints with
  your key from the browser)
- /sviluppatori — quickstart (raw HTTP, pip, npm), Django notes, endpoints,
  demo keys (demo_gigabit, demo_adsl, demo_none, demo_404, demo_429 return
  deterministic scenarios), sample addresses per outcome, usage object,
  fields= trimming (400 on unknown keys), 15x autocomplete quota norm
- /guide/nextjs — Next.js/React coverage form: proxy route, autocomplete, cache
- /guide/django — Django + netcov-sdk: settings, service layer, proxy view, template
- /guide/wordpress — plugin + PHP shortcode with key server-side
- /operatori/reseller — reseller lead-qualification flow, multi-site keys
- /operatori/api-vs-scraping — why a dedicated API beats scraping the AGCOM map
- /widget — 3-line coverage-check widget (script tag, demo mode)
- /errors — error codes with causes and solutions (/errors.json: JSON)
- /status — service state, monthly data refresh (1st of month)
- /changelog — additive API changes
- /affidabilita-dati — data origin and limitations (declared vs actual
  coverage, granularity, strict mode)
- /adempimento-agcom — Italian AGCOM obligation (art. 98-quaterdecies of
  the Codice delle comunicazioni elettroniche, DL 19/2026): providers must
  inform consumers of all access networks available at their address,
  competitors included; NetCov feeds these coverage checkers
- /prezzi — free permanent key; higher volume on request
- /legale — legal notes, licenses, attribution
- /portal — self-serve signup and API key management (noindex)
- /contatti — support and partner contacts

## Attribution strings (required, byte-exact as returned by the API)

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

## Full version

- Everything above, expanded with quickstart, all endpoints, all error
  codes and integration snippets: https://netcov.io/llms-full.txt