Documentation de l’API

Votre première requête API

curl --get 'https://www.geoipy.com/api/IPsInfo' \
  --data-urlencode 'ip=8.8.8.8' \
  --header 'X-API-Key: YOUR_API_KEY'

Utilisez HTTPS et X-API-Key. Les clés dans les URL peuvent être journalisées. Des clés différentes dans l’en-tête et l’URL renvoient HTTP 400.

Créez une clé dans le tableau de bord. Elle s’affiche une seule fois. Gardez-la sur le serveur, jamais dans le navigateur ou un dépôt public. Le remplacement invalide l’ancienne clé immédiatement. Révocation ou expiration bloque les nouvelles requêtes ; celles acceptées peuvent finir.

Réponse et fraîcheur

HTTP 200 renvoie du JSON. Exemple abrégé ; les champs disponibles dépendent du fournisseur.

{
  "ip": "8.8.8.8",
  "type": "ipv4",
  "country_code": "US"
}

Le cache est valable 12 heures par défaut. X-Data-Fetched-At indique l’heure UTC de récupération. Un échec n’entraîne pas l’envoi de données expirées ; cette heure n’est pas leur âge.

X-Request-ID identifie la requête pour l’assistance. La géolocalisation est une position réseau approximative, pas la position exacte d’une personne.

Utilisation et nouvelles tentatives

Les requêtes réussies, même en cache, consomment le quota. Celles en cours réservent la capacité ; les échecs la libèrent. Réinitialisation le 1er à 00:00 UTC. Changer d’offre ou de clé ne remet pas l’usage à zéro.

Pour HTTP 429 ou 503/504 temporaires, respectez Retry-After et limitez les tentatives avec délais croissants. Corrigez d’abord les saisies ou identifiants invalides.

Erreurs

Les erreurs renvoient application/json et un statut HTTP d’erreur. Les identifiants API et exemples conservent leur forme documentée.

{
  "success": false,
  "error": {
    "code": 104,
    "type": "usage_limit_reached",
    "info": "The monthly API allowance has been reached."
  }
}

Exemples côté serveur

JavaScript · serveur

const url = new URL('https://www.geoipy.com/api/IPsInfo');
url.searchParams.set('ip', '8.8.8.8');
const response = await fetch(url, {
  headers: { 'X-API-Key': process.env.GEOIPY_API_KEY }
});
const data = await response.json();
if (!response.ok) throw new Error(data.error.info);
console.log(data);

C#

using (var client = new System.Net.Http.HttpClient())
{
    client.DefaultRequestHeaders.Add("X-API-Key",
        System.Environment.GetEnvironmentVariable("GEOIPY_API_KEY"));
    var response = await client.GetAsync(
        "https://www.geoipy.com/api/IPsInfo?ip=8.8.8.8");
    var json = await response.Content.ReadAsStringAsync();
    // Inspect response.StatusCode and parse json before retrying.
}

Python

import os, requests
response = requests.get(
    'https://www.geoipy.com/api/IPsInfo',
    params={'ip': '8.8.8.8'},
    headers={'X-API-Key': os.environ['GEOIPY_API_KEY']},
    timeout=15)
data = response.json()
response.raise_for_status()

PHP

$url = 'https://www.geoipy.com/api/IPsInfo?' . http_build_query(['ip' => '8.8.8.8']);
$ch = curl_init($url);
curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 15,
    CURLOPT_HTTPHEADER => ['X-API-Key: ' . getenv('GEOIPY_API_KEY')]]);
$json = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($json === false) { throw new RuntimeException('The request failed.'); }
curl_close($ch);
$data = json_decode($json, true);
// Inspect $status and $data['error'] when the status is not 200.