Geolocalizzazione del visitatore per il tuo sito web

Chiama GET /v1/geo direttamente dal browser di un visitatore per ottenere paese, città, fuso orario e contesto regionale disponibili per quella connessione. Configura la tua origine consentita, aggiungi la tua chiave pubblicabile e decidi come la tua applicazione deve gestire la risposta.

Ottieni una chiave API visitatore gratuita Leggi la guida rapida →

La richiesta proviene dal browser del visitatore

GET /v1/geo descrive sempre il client che si connette a esso. Chiamalo dal browser del visitatore per ricevere i dati di localizzazione di quella connessione; una richiesta inviata dal server della tua applicazione descrive la connessione del server stesso, non quella del visitatore. Se hai già l'indirizzo IP di un utente finale e devi risolverlo dal tuo backend, usa invece l'API di ricerca IP separata. La chiave del visitatore è pubblicabile — è pensata per comparire nel codice del browser — quindi il vero controllo è l'elenco di origini consentite configurato per essa, non la segretezza della chiave stessa.

Progetta per un suggerimento, non un reindirizzamento forzato

Un viaggiatore potrebbe usare una rete in un paese pur preferendo un'altra lingua, e una VPN può collocare una connessione altrove del tutto. Offri ai visitatori un modo visibile per cambiare la lingua, il paese o la valuta suggeriti, e conserva questa scelta invece di ricalcolarla dalla posizione a ogni visita.

Contesto di sicurezza solo sui piani idonei

Sui piani che lo includono, la risposta può contenere indicatori VPN/Tor/minaccia basati su liste. Un oggetto security omesso significa che il campo non è incluso nel tuo piano, non che la rete sia stata verificata e giudicata sicura; un valore false significa nessuna corrispondenza nei dati di origine disponibili, il che non equivale a un attestato di sicurezza. La copertura varia per indicatore e versione IP — il rilevamento di Tor su IPv6, ad esempio, non è attualmente implementato.

Contesto utile nella risposta

country, region, city, latitude, longitude: Posizione approssimativa per la richiesta in connessione. Non è una posizione del dispositivo o GPS, né una prova di dove si trovi una persona specifica.
timezone, currency, callingCode: Contesto regionale derivato dalla posizione risolta, utile come suggerimento di partenza.
asn, asOrganization: La rete in connessione e il suo operatore, quando disponibili. Un nome di organizzazione non è l'identità di una persona.
security: Omesso interamente a meno che il tuo piano non lo includa. Quando presente: isVpn, isTor, isDatacenter, isThreat, isSanctionedNetwork — indicatori basati su liste, non una garanzia di sicurezza.

Aggiungi la prima richiesta

JavaScript da browser

async function loadVisitorLocation() {
  const response = await fetch('https://api.watch-ip.com/v1/geo', {
    headers: { 'X-Api-Key': 'YOUR_PUBLISHABLE_KEY' },
  });

  if (!response.ok) {
    throw new Error(`Visitor geolocation failed (${response.status})`);
  }

  const geo = await response.json();
  return { country: geo.country ?? null, city: geo.city ?? null, timezone: geo.timezone ?? null };
}

Sostituisci il segnaposto con la tua chiave visitatore ed esegui la pagina da un'origine consentita per quella chiave. Mantieni disponibile l'esperienza predefinita del tuo sito se la richiesta fallisce o manca un campo.

Domande frequenti

Questa richiesta chiede il permesso di posizione del dispositivo?

No. La richiesta basata su IP non usa l'API Geolocation del dispositivo del browser — stima la posizione dalla connessione anziché richiedere le coordinate fornite dal dispositivo. I tuoi obblighi di privacy e consenso dipendono comunque da come la tua applicazione utilizza il risultato.

Posso passare un indirizzo IP a /v1/geo?

No. L'endpoint descrive sempre il client in connessione. Usa /v1/lookup/{ip} dal tuo backend quando vuoi fornire un indirizzo.

Perché una richiesta renderizzata lato server mostra la posizione del mio provider di hosting?

Il server è il client in connessione per quella richiesta. Sposta la richiesta del visitatore nel codice del browser, oppure usa l'endpoint di ricerca IP dal tuo backend con una fonte affidabile dell'IP dell'utente finale.

La città o le coordinate sono esatte?

No. La geolocalizzazione IP è una stima associata alla connessione, non la posizione precisa di una persona.

Posso usare una chiave segreta nel browser?

No. Usa una chiave visitatore pubblicabile per questo endpoint e mantieni le chiavi segrete di ricerca solo nell'ambiente del tuo backend.