Documentación de la API
Tu primera solicitud API
Sustituye YOUR_API_KEY por tu clave guardada. Consérvala en tu servidor. Crear clave API
curl --get 'https://www.geoipy.com/api/IPsInfo' \
--data-urlencode 'ip=8.8.8.8' \
--header 'X-API-Key: YOUR_API_KEY'
Respuesta y actualidad
HTTP 200 devuelve JSON. Ejemplo abreviado; los campos disponibles dependen del proveedor.
{
"ip": "8.8.8.8",
"type": "ipv4",
"country_code": "US"
}
Uso y reintentos
Usa HTTPS y X-API-Key. Las claves en URL pueden quedar en registros. Claves distintas en cabecera y URL devuelven HTTP 400.
Las solicitudes correctas, incluso de caché, consumen cuota. Las pendientes reservan capacidad; los fallos la liberan. Se reinicia el día 1 a las 00:00 UTC. Cambiar plan o clave no reinicia el uso.
Para HTTP 429 o errores temporales 503/504, respeta Retry-After y limita los reintentos con esperas crecientes. Corrige datos o credenciales inválidos primero.
La caché dura 12 horas por defecto. X-Data-Fetched-At indica la consulta en UTC. Si falla la actualización no se sirven datos caducados; la hora de consulta no es su antigüedad.
X-Request-ID identifica la solicitud para soporte. La geolocalización es aproximada y de la red, no la posición exacta de una persona.
Errores
Los errores devuelven application/json con estado HTTP de error. Los identificadores API y ejemplos mantienen su forma documentada.
{
"success": false,
"error": {
"code": 104,
"type": "usage_limit_reached",
"info": "The monthly API allowance has been reached."
}
}
| Código | Tipo | Significado |
|---|---|---|
| 101 | invalid_access_key | Clave ausente, caducada, revocada o inválida (HTTP 401). |
| 104 | usage_limit_reached | Cuota mensual alcanzada, incluidas solicitudes pendientes (HTTP 429). |
| 105 | rate_limit_reached | Límite de frecuencia alcanzado; respeta Retry-After (HTTP 429). |
| 106 | invalid_ip_address | Indica una IPv4 o IPv6 pública (HTTP 400). |
| 202 | upstream_failure | El proveedor falló o devolvió datos inválidos (HTTP 502). |
| 503 | lookup_unavailable | Servicio, cuotas o actualización no disponibles temporalmente (HTTP 503). |
| 504 | upstream_timeout | El proveedor agotó el tiempo de espera (HTTP 504). |
Ejemplos del servidor
JavaScript · servidor
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.
Descargar especificación OpenAPI
Para ayuda, envía el ID y la hora UTC aproximada por correo. Mantén las claves privadas. support-geoipy@rumex.bh