Guida rapida

Ottieni una chiamata GET /v1/geo funzionante in pochi minuti: crea una chiave, effettua una richiesta e leggi la risposta.

Prima di iniziare

Un account Watch-IP — il piano gratuito è sufficiente per seguire questa guida.
Una pagina o uno script a cui puoi aggiungere una chiamata fetch o curl.

1. Crea un account e ottieni una chiave

Registrati e apri la tua dashboard. Ogni account inizia con una chiave visitatore pubblicabile — configura le sue origini consentite includendo il sito da cui la chiamerai (oppure localhost durante i test).

2. Effettua la tua prima richiesta

Chiama GET /v1/geo con la tua chiave pubblicabile nell'header X-Api-Key. Da un browser, questo risolve la connessione del visitatore stesso; da un server, risolve invece la connessione del server.

curl

curl https://api.watch-ip.com/v1/geo \
  -H "X-Api-Key: YOUR_PUBLISHABLE_KEY"

3. Leggi la risposta

Una chiamata riuscita restituisce 200 con un corpo JSON — country, city e timezone sono i campi da cui partono la maggior parte delle integrazioni, e ogni campo è indipendentemente nullable, quindi verificalo prima di usarlo.

Risposta (abbreviata)

{
  "ip": "203.0.113.1",
  "country": "US",
  "city": "Austin",
  "timezone": "America/Chicago"
}

4. Cerca un IP diverso

Devi risolvere un indirizzo che hai già, anziché il visitatore in connessione? Si tratta di un endpoint separato da server a server autenticato con una chiave segreta, non con la tua chiave pubblicabile — consulta il riferimento della ricerca IP.

Se qualcosa va storto

Un 401 significa che la chiave API è mancante o non valida; un 403 da GET /v1/geo di solito significa che l'origine chiamante non è ancora nell'elenco delle origini consentite della chiave. Consulta errori e limiti di frequenza per l'elenco completo dei codici di stato.

Prossimo passo

Leggi l'autenticazione per capire come funzionano i tipi di chiave e il blocco per origine, oppure vai direttamente al riferimento dell'endpoint per la risposta che stai integrando.