Salta al contenuto
NetCov

Guide · Next.js e React

Guide / Next.js e React

Verifica copertura in Next.js: form completo in un pomeriggio

Il pattern è sempre lo stesso: una Route Handler proxy che custodisce la chiave, un campo con autocomplete debounced e una chiamata con il code del suggerimento scelto. Sotto, il codice pronto da copiare.

1 · Il proxy server-side (obbligatorio)

La chiave API non deve mai finire nel bundle JavaScript. La Route Handler la legge da variabile d’ambiente e inoltra la richiesta; il browser parla solo col tuo dominio.

tsx
// app/api/coverage/route.ts — proxy server-side (la chiave resta qui)
import { NextRequest, NextResponse } from "next/server";

export async function GET(req: NextRequest) {
  const q = new URL(req.url).searchParams;
  const params = new URLSearchParams({
    ...(q.get("code")
      ? { code: q.get("code")! }
      : { address: `${q.get("address")}, ${q.get("city")}` }),
  });
  const r = await fetch(
    `https://api.netcov.io/coverage/italy?${params}`,
    { headers: { Authorization: `Bearer ${process.env.NETCOV_API_KEY}` } }
  );
  return NextResponse.json(await r.json(), { status: r.status });
}

2 · Il form con autocomplete

Campo città + campo indirizzo. Mostra main_text con le porzioni matches in grassetto; i suggerimenti di tipo civico portano già il code da inviare.

tsx
// components/CoverageForm.tsx (estratto)
import { useRef, useState } from "react";

type Item = { kind: string; display: string; main_text?: string; code?: string };
const [city, setCity] = useState("Napoli");
const [items, setItems] = useState<Item[]>([]);
const timer = useRef<ReturnType<typeof setTimeout> | null>(null);

async function onType(value: string) {
  if (timer.current) clearTimeout(timer.current);
  timer.current = setTimeout(async () => {
    if (value.trim().length < 3) return setItems([]);
    const r = await fetch(
      `/api/autocomplete?city=${encodeURIComponent(city)}&address=${encodeURIComponent(value)}`
    );
    const body = await r.json();
    setItems(body.results ?? []); // {kind, display, main_text, matches, code}
  }, 250); // debounce: niente raffica di chiamate a ogni tasto
}
// al click su un suggerimento di tipo "civico": usa item.code, poi
// GET /api/coverage?code=<code> e mostra summary.technologies

Il proxy autocomplete (non dimenticarlo)

Il form chiama /api/autocomplete, mai l’API direttamente: stessa chiave server-side, stessa protezione della quota. Al click, invia il code solo se kind === "civico" (una via senza civico non ha codice: lascia digitare il numero).

tsx
// app/api/autocomplete/route.ts — stesso pattern della coverage
import { NextRequest, NextResponse } from "next/server";

export async function GET(req: NextRequest) {
  const q = new URL(req.url).searchParams;
  const params = new URLSearchParams({
    city: q.get("city") ?? "",
    address: q.get("address") ?? "",
  });
  const r = await fetch(
    `https://api.netcov.io/autocomplete?${params}`,
    { headers: { Authorization: `Bearer ${process.env.NETCOV_API_KEY}` } }
  );
  return NextResponse.json(await r.json(), { status: r.status });
}

Domande frequenti

Prova gli endpoint senza scrivere codice con l’API Playground, consulta i codici di errore e la guida generale per sviluppatori.

Dove metto la chiave API in un'app Next.js?

Mai nel JavaScript del browser: la chiave vive in una variabile d'ambiente (NETCOV_API_KEY) letta solo da una Route Handler lato server, che inoltra le chiamate all'API e restituisce al client solo i dati di copertura.

Come gestisco l'autocomplete in React?

Con un campo controllato, debounce di almeno 250 ms, minimo 2-3 caratteri e una cache in memoria per coppia città+query. Mostra main_text con le porzioni matches in grassetto; al click usa il code del suggerimento per la chiamata di copertura.

Server Component o Client Component per la verifica?

Il form è un Client Component (interattività), ma la chiamata all'API passa sempre dalla tua Route Handler server-side: così la chiave non esce mai dal server e puoi aggiungere cache e rate limiting tuoi.

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 Django, Guida WordPress.

Crea la tua chiave gratuitaProva nel Playground