API de géolocalisation IP

Une requête. Vous avez une adresse IP, ou vous voulez celle qui fait la requête. La réponse est un pays, une région, une ville et une coordonnée.

Chaque requête a besoin d'une clé d'API ; voir Authentification. Une recherche réussie compte pour un appel normal. Aucun forfait supplémentaire à activer.

résultat en direct

le code qui l'a produit

import { Unmap } from "@unmap/sdk";

const unmap = new Unmap({ key: "um_live_..." });

const here = await unmap.geoip.locate();

if (here.found) console.log(here.city, here.country_code);
// Show here.attribution.text, linked to here.attribution.url.

curl "https://api.unmap.dev/geoip?ip=8.8.8.8&key=um_live_..."

const here = await unmap.geoip.locate("8.8.8.8");

Recherche

GET /geoip

Paramètre	Requis	Description
`ip`	non	Une adresse IPv4 ou IPv6. Omettez-la pour localiser l'adresse qui a fait la requête.

{
  "ip": "8.8.8.8",
  "found": true,
  "country_code": "US",
  "country": "United States",
  "region": "California",
  "city": "Mountain View",
  "coordinates": [-122.085, 37.422],
  "accuracy": "city",
  "release": "2026-11",
  "attribution": { "text": "IP Geolocation by DB-IP", "url": "https://db-ip.com" }
}

coordinates est [longitude, latitude], dans le même ordre que le reste de l'API. ip est la forme canonique de l'adresse recherchée : IPv4 en notation pointée, ou IPv6 en forme la plus courte. Une adresse IPv6 qui enveloppe une IPv4 revient en IPv4. release est le mois de la base qui a répondu. region et city valent null quand la base ne les connaît pas.

Votre propre adresse

const here = await unmap.geoip.locate();

Sans ip, la réponse concerne la machine qui fait la requête. Depuis un navigateur, c'est le visiteur. Depuis un serveur, c'est le serveur. Une requête qui passe par un mandataire est localisée au mandataire : un serveur qui veut la position de son visiteur doit passer l'adresse du visiteur dans ip.

Adresses sans réponse

Une adresse que la base ne connaît pas, comme un espace IPv6 non attribué, donne 200 avec found: false et aucun champ de position.

{ "ip": "1000::1", "found": false, "release": "2026-11", "attribution": { "text": "IP Geolocation by DB-IP", "url": "https://db-ip.com" } }

Les plages privées, de bouclage, de lien local et autres plages réservées ne sont pas recherchées. Elles donnent 400 invalid_ip, car il n'y a rien à trouver. NAT64 (64:ff9b::/96), 6to4 (2002::/16) et les adresses IPv6 enveloppant une IPv4 sont d'abord lues à travers l'adresse IPv4 qu'elles contiennent : ::ffff:10.0.0.1 est donc rejetée comme 10.0.0.1.

Précision

Voyez la réponse comme la zone desservie par un fournisseur d'accès, pas comme un lieu. Souvent, seul le pays est juste, ou une ville voisine, et les réseaux mobiles, les VPN et les réseaux d'entreprise peuvent placer une personne à des centaines de kilomètres d'où elle se trouve. Servez-vous-en pour choisir une langue, une devise ou une vue de départ. Ne l'utilisez pas pour identifier une personne ou une adresse civique.

Erreurs

Statut	Code	Quand
`400`	`invalid_ip`	`ip` n'est pas une adresse IPv4 ou IPv6, ou elle est privée ou réservée. Aussi quand vous l'avez omis et que l'adresse de l'appelant n'a pas pu être lue, ou est privée. Passez `ip`.
`400`	`bad_request`	Vous avez omis `ip` et il n'y a pas d'adresse d'appelant par défaut.
`503`	`service_unavailable`	Le jeu de données est absent, illisible ou invalide. Réessayez plus tard.

{ "error": "ip must be an IPv4 or IPv6 address", "code": "invalid_ip" }

Seul un 200 est facturé. Chaque 400 et 503 est gratuit.

Vie privée

L'adresse que vous recherchez n'est ni journalisée, ni stockée, ni comptée ; la requête elle-même compte pour un appel, comme toute autre. Les lignes d'usage ne portent que le point d'accès, et l'adresse ne fait partie d'aucune clé de cache. Les réponses portent Cache-Control: private, max-age=300 : votre navigateur peut en réutiliser une pendant cinq minutes, et aucun cache partagé ne la conserve.

Attribution

Les données sont la base IP to City Lite de DB-IP, sous CC BY 4.0. Chaque 200 porte attribution. Affichez attribution.text, avec un lien vers attribution.url, partout où votre produit montre ou utilise le résultat. La page d'attribution contient la mention complète.

Couverture et mises à jour

La recherche est mondiale. Toutes les autres API d'unmap sont d'abord canadiennes ; celle-ci ne l'est pas. DB-IP publie un nouveau fichier chaque mois. Il est vérifié chaque semaine, compilé en petits objets immuables et promu par une seule écriture du manifeste : une mauvaise version se retire en pointant vers la précédente. Si une mise à jour échoue, le Worker continue de servir la version précédente jusqu'à une heure avant de répondre 503.