Bezoekersgeolocatie voor je website

Roep GET /v1/geo rechtstreeks aan vanuit de browser van een bezoeker om het beschikbare land, de stad, tijdzone en regionale context van die verbinding te krijgen. Configureer je toegestane origin, voeg je publiceerbare sleutel toe en bepaal hoe je applicatie het antwoord moet verwerken.

Vraag een gratis bezoekers-API-sleutel aan Lees de snelstart →

Het verzoek komt van de browser van de bezoeker

GET /v1/geo beschrijft altijd de client die er verbinding mee maakt. Roep het aan vanuit de browser van de bezoeker om de locatiegegevens van die verbinding te ontvangen; een verzoek dat vanaf je applicatieserver wordt verstuurd, beschrijft de eigen verbinding van de server, niet die van de bezoeker. Als je al een IP-adres van een eindgebruiker hebt en dit in plaats daarvan op je backend wilt opzoeken, gebruik dan de aparte IP-lookup-API. De bezoekerssleutel is publiceerbaar — hij is bedoeld om in browsercode te verschijnen — dus de echte controle is de lijst met toegestane origins die ervoor is geconfigureerd, niet de geheimhouding van de sleutel zelf.

Ontwerp voor een suggestie, geen gedwongen omleiding

Een reiziger kan een netwerk in het ene land gebruiken terwijl hij een andere taal verkiest, en een VPN kan een verbinding ergens totaal anders plaatsen. Geef bezoekers een zichtbare manier om de voorgestelde taal, het land of de valuta te wijzigen, en bewaar die keuze in plaats van deze bij elk bezoek opnieuw uit de locatie af te leiden.

Beveiligingscontext alleen op in aanmerking komende abonnementen

Op abonnementen die het bevatten, kan het antwoord op lijsten gebaseerde VPN-/Tor-/dreigingsindicatoren bevatten. Een weggelaten security-object betekent dat het veld niet is inbegrepen in je abonnement, niet dat het netwerk veilig is bevonden; een waarde false betekent geen match in de beschikbare brongegevens, wat niet hetzelfde is als een schone verklaring. De dekking verschilt per indicator en IP-versie — IPv6-Tor-detectie is bijvoorbeeld momenteel niet geïmplementeerd.

Nuttige context in het antwoord

country, region, city, latitude, longitude: Geschatte locatie voor het binnenkomende verzoek. Geen apparaat- of GPS-positie, en geen bewijs van de verblijfplaats van een specifiek persoon.
timezone, currency, callingCode: Regionale context afgeleid van de opgeloste locatie, nuttig als startpunt voor een suggestie.
asn, asOrganization: Het verbindende netwerk en de exploitant ervan, indien beschikbaar. Een organisatienaam is geen identiteit van een persoon.
security: Volledig weggelaten tenzij je abonnement het bevat. Indien aanwezig: isVpn, isTor, isDatacenter, isThreat, isSanctionedNetwork — op lijsten gebaseerde indicatoren, geen veiligheidsgarantie.

Voeg het eerste verzoek toe

Browser-JavaScript

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 };
}

Vervang de tijdelijke aanduiding door je bezoekerssleutel en voer de pagina uit vanaf een origin die voor die sleutel is toegestaan. Zorg dat de standaardervaring van je site beschikbaar blijft als het verzoek mislukt of een veld ontbreekt.

Veelgestelde vragen

Vraagt dit toestemming voor apparaatlocatie?

Nee. Het IP-gebaseerde verzoek gebruikt de Geolocation API van het apparaat in de browser niet — het schat de locatie op basis van de verbinding in plaats van door het apparaat geleverde coördinaten aan te vragen. Je eigen privacy- en toestemmingsverplichtingen hangen nog steeds af van hoe je applicatie het resultaat gebruikt.

Kan ik een IP-adres doorgeven aan /v1/geo?

Nee. Het endpoint beschrijft altijd de verbindende client. Gebruik /v1/lookup/{ip} vanaf je backend wanneer je een adres wilt opgeven.

Waarom toont een server-gerenderd verzoek de locatie van mijn hostingprovider?

De server is de verbindende client voor dat verzoek. Verplaats het bezoekersverzoek naar browsercode, of gebruik het IP-lookup-endpoint vanaf je backend met een vertrouwde bron voor het IP-adres van de eindgebruiker.

Is de stad of coördinaat exact?

Nee. IP-geolocatie is een schatting die aan de verbinding is gekoppeld, geen exacte positie van een persoon.

Kan ik een geheime sleutel in de browser gebruiken?

Nee. Gebruik voor dit endpoint een publiceerbare bezoekerssleutel, en bewaar geheime lookupsleutels alleen in je backend-omgeving.