Géolocalisation du visiteur pour votre site web

Appelez GET /v1/geo directement depuis le navigateur d'un visiteur pour obtenir le pays, la ville, le fuseau horaire et le contexte régional disponibles pour cette connexion. Configurez votre origine autorisée, ajoutez votre clé publiable, et décidez comment votre application doit traiter la réponse.

Obtenir une clé API visiteur gratuite Lire le démarrage rapide →

La requête provient du navigateur du visiteur

GET /v1/geo décrit toujours le client qui s'y connecte, quel qu'il soit. Appelez-le depuis le navigateur du visiteur pour recevoir les données de localisation de cette connexion ; une requête envoyée depuis votre serveur d'application décrit la connexion du serveur lui-même, pas celle du visiteur. Si vous avez déjà l'adresse IP d'un utilisateur final et devez la résoudre depuis votre backend, utilisez l'API de recherche d'IP distincte. La clé visiteur est publiable — elle est conçue pour apparaître dans du code navigateur — le vrai contrôle est donc la liste des origines autorisées configurée pour elle, pas le secret de la clé elle-même.

Concevoir une suggestion, pas une redirection forcée

Un voyageur peut utiliser un réseau dans un pays tout en préférant une autre langue, et un VPN peut placer une connexion ailleurs entièrement. Donnez aux visiteurs un moyen visible de changer la langue, le pays ou la devise suggérés, et conservez ce choix au lieu de le redériver de la localisation à chaque visite.

Contexte de sécurité uniquement sur les forfaits éligibles

Sur les forfaits qui l'incluent, la réponse peut contenir des indicateurs VPN/Tor/menace basés sur des listes. Un objet security absent signifie que le champ n'est pas inclus dans votre forfait, pas que le réseau a été jugé sûr ; une valeur négative signifie l'absence de correspondance dans les données source disponibles, ce qui n'équivaut pas à un certificat de bonne conduite. La couverture diffère selon l'indicateur et la version d'IP — la détection Tor sur IPv6, par exemple, n'est actuellement pas mise en œuvre.

Contexte utile dans la réponse

country, region, city, latitude, longitude: Localisation approximative pour la requête connectée. Ni une position d'appareil ou GPS, ni une preuve de la présence d'une personne précise.
timezone, currency, callingCode: Contexte régional dérivé de la localisation résolue, utile comme suggestion de départ.
asn, asOrganization: Le réseau connecté et son opérateur, lorsque disponible. Un nom d'organisation n'est pas l'identité d'une personne.
security: Entièrement absent sauf si votre forfait l'inclut. Lorsque présent : isVpn, isTor, isDatacenter, isThreat, isSanctionedNetwork — des indicateurs basés sur des listes, pas une garantie de sécurité.

Ajouter la première requête

JavaScript navigateur

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

Remplacez le paramètre par votre clé visiteur et exécutez la page depuis une origine autorisée pour cette clé. Conservez l'expérience par défaut de votre site disponible si la requête échoue ou si un champ est manquant.

Questions fréquentes

Cela demande-t-il la permission de localisation de l'appareil ?

Non. La requête basée sur l'IP n'utilise pas l'API de géolocalisation d'appareil du navigateur — elle estime la localisation à partir de la connexion plutôt que de demander les coordonnées fournies par l'appareil. Vos propres obligations de confidentialité et de consentement dépendent toujours de l'usage que votre application fait du résultat.

Puis-je passer une adresse IP à /v1/geo ?

Non. Le point de terminaison décrit toujours le client connecté. Utilisez /v1/lookup/{ip} depuis votre backend lorsque vous souhaitez fournir une adresse.

Pourquoi une requête rendue côté serveur affiche-t-elle la localisation de mon hébergeur ?

Le serveur est le client connecté pour cette requête. Déplacez la requête visiteur dans du code navigateur, ou utilisez le point de terminaison de recherche d'IP depuis votre backend avec une source fiable de l'IP de l'utilisateur final.

La ville ou les coordonnées sont-elles exactes ?

Non. La géolocalisation IP est une estimation associée à la connexion, pas la position précise d'une personne.

Puis-je utiliser une clé secrète dans le navigateur ?

Non. Utilisez une clé visiteur publiable pour ce point de terminaison, et conservez les clés secrètes de recherche uniquement dans votre environnement backend.