Documentation de l’API

Votre première requête API

Remplacez YOUR_API_KEY par votre clé enregistrée. Conservez-la sur votre serveur. Créer une clé API

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

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"
}
Utilisation et nouvelles tentatives

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.

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.

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.

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."
  }
}
Erreurs
CodeTypeSignification
101invalid_access_keyClé absente, expirée, révoquée ou invalide (HTTP 401).
104usage_limit_reachedQuota mensuel atteint, requêtes en cours incluses (HTTP 429).
105rate_limit_reachedLimite à court terme atteinte ; respectez Retry-After (HTTP 429).
106invalid_ip_addressFournissez une adresse IPv4 ou IPv6 publique (HTTP 400).
202upstream_failureÉchec du fournisseur ou données invalides (HTTP 502).
503lookup_unavailableService, quotas ou actualisation temporairement indisponibles (HTTP 503).
504upstream_timeoutDélai du fournisseur dépassé (HTTP 504).
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.

Télécharger la spécification OpenAPI

Pour de l’aide, envoyez l’identifiant et l’heure UTC approximative. Gardez vos clés privées. support-geoipy@rumex.bh