Necesitas resolver la ubicación de un usuario a partir de una dirección IP, restringir funciones por región y marcar tráfico riesgoso—esta semana. Al final de esta guía, consultarás el endpoint de Geolocalización de la API de Seguimiento Geográfico desde Python, analizarás la respuesta que realmente necesitas (lat/lon, ciudad, ISP, señales de amenaza) y enviarás con autenticación y facturación funcional en Zyla API Hub.
Lo que proporciona la API de Seguimiento Geográfico
La API de Seguimiento Geográfico devuelve detalles de geolocalización para una dirección IP dada. Incluye:
- País, región, ciudad, zona horaria
- Latitud y longitud
- ISP, organización y nombre de host
- Continente y contexto de moneda
- Señales de seguridad (presencia de proxy/VPN/Tor, nivel de amenaza)
Implementaciones comunes: controles de contenido regional, detección de fraude, UX consciente de la localidad (zona horaria y moneda), evaluación de riesgo de pedidos y registro o análisis basado en la ubicación.
Autenticación y facturación en Zyla API Hub
Zyla API Hub utiliza un modelo de suscripción + cuota en su catálogo de más de 10,000 APIs públicas. La autenticación se realiza a través de una única clave API enviada como un encabezado Authorization: Bearer. Para tu primera API en Zyla, puedes comenzar con una prueba de 7 días o 50 solicitudes (sin plan gratuito más allá de eso). Consulta la página de la API para las opciones de acceso y precios actuales.
Puntos clave:
- Una cuenta y una clave API para cada API en Zyla.
- No hay pago por llamada; los planes son de suscripción + cuota.
- Aplica el mismo encabezado Authorization: Bearer YOUR_API_KEY para cada solicitud.
Puedes navegar por el mercado en zylalabs.com o ir directamente a la lista de la API de Seguimiento Geográfico para suscribirte.
Comenzando en Zyla API Hub
- Abre la página de la API de Seguimiento Geográfico.
- Haz clic en Suscribirse (o Comenzar Prueba Gratuita si está disponible) para activar el acceso.
- Copia tu clave API desde tu panel de control.
Cuando estés listo para implementar, pasa tu clave como Authorization: Bearer YOUR_API_KEY en cada solicitud.
Endpoint: Geolocalización
La API de Seguimiento Geográfico expone un único endpoint de Geolocalización para la resolución de IP a geo.
- Método: GET
- URL: https://zylalabs.com/api/2556/geo-tracking-api/6048/geolocation
- Parámetro de consulta requerido:
- ip (string): la dirección IP a resolver
Ejemplo oficial de cURL
curl -s -X GET "https://zylalabs.com/api/2556/geo-tracking-api/6048/geolocation?ip=181.188.132.167" \
-H "Authorization: Bearer YOUR_API_KEY"Ejemplo de respuesta JSON oficial
{
"status": "success",
"country": "BO",
"countryCode": "BO",
"region": "Departamento de La Paz",
"regionName": "Departamento de Santa Cruz",
"city": "La Paz",
"zip": "",
"lat": -17.7834,
"lon": -63.1822,
"timezone": "America/La_Paz",
"isp": "Telefónica Celular de Bolivia S.A.",
"org": "AS27882 Telefónica Celular de Bolivia S.A.",
"as": "AS27882 Telefónica Celular de Bolivia S.A.",
"query": "181.188.132.167",
"areaCode": "",
"dmaCode": "",
"inEU": 0,
"euVATrate": false,
"continentCode": "SA",
"continentName": "América del Sur",
"locationAccuracyRadius": "5",
"currencyCode": "BOB",
"currencySymbol": "$b",
"currencySymbol_UTF8": "$b",
"currencyConverter": 6.9324,
"flag": "🇧🇴",
"callingCode": "591",
"languageCode": null,
"security": {
"is_proxy": false,
"proxy_type": null,
"is_tor": false,
"is_tor_exit": false,
"threat_level": "Bajo",
"threat_score": "0",
"is_abuser": false,
"is_attacker": false,
"is_bogon": false,
"is_cloud_provider": false,
"is_relay": false,
"is_vpn": false,
"is_anonymous": false,
"is_threat": false
},
"hostname": "scz-181-188-132-00167.tigo.bo",
"classType": "clase B",
"application": "Redes medianas"
}Aspectos destacados de los campos que probablemente usarás:
- lat, lon: coordenadas en grados decimales.
- country, countryCode, region, regionName, city: geodatos textuales para políticas y personalización.
- timezone: cadena de zona horaria IANA para programación y formateo consciente de la localidad.
- isp, org, as, hostname: propiedad y contexto de enrutamiento de la red.
- security.*: indicadores booleanos y metadatos de amenaza para la puntuación de riesgo.
- currencyCode y currencyConverter: contexto de moneda, útil para visualización y conversiones.
Integración con Python
El siguiente ejemplo en Python llama al endpoint de Geolocalización, maneja la autenticación, verifica el campo de estado de la API y extrae los campos más prácticos para la restricción de funciones y el registro.
import os
import requests
API_KEY = os.getenv("ZYLA_API_KEY", "YOUR_API_KEY")
BASE_URL = "https://zylalabs.com/api/2556/geo-tracking-api/6048/geolocation"
def geolocate_ip(ip: str) -> dict:
headers = {
"Authorization": f"Bearer {API_KEY}"
}
params = {"ip": ip}
# Ajusta los tiempos de espera a tu entorno; usando (conectar, leer)
resp = requests.get(BASE_URL, headers=headers, params=params, timeout=(5, 10))
resp.raise_for_status()
data = resp.json()
# La API devuelve un campo "status"; verifícalo antes de confiar en los campos
if data.get("status") != "success":
raise RuntimeError(f"La búsqueda geográfica falló para {ip}: {data}")
return {
"ip": data.get("query"),
"country": data.get("country"),
"countryCode": data.get("countryCode"),
"region": data.get("region"),
"regionName": data.get("regionName"),
"city": data.get("city"),
"lat": data.get("lat"),
"lon": data.get("lon"),
"timezone": data.get("timezone"),
"isp": data.get("isp"),
"org": data.get("org"),
"as": data.get("as"),
"hostname": data.get("hostname"),
"security": data.get("security", {}),
"currencyCode": data.get("currencyCode"),
"currencyConverter": data.get("currencyConverter"),
}
if __name__ == "__main__":
target_ip = "181.188.132.167"
try:
result = geolocate_ip(target_ip)
print("Geodatos resueltos:")
for k, v in result.items():
print(f" {k}: {v}")
# Ejemplo de uso:
# if result["security"].get("is_proxy") or result["security"].get("is_vpn"):
# marcar usuario/sesión para verificación adicional.
except Exception as e:
# Producción: integra con tu registro/alerta
print(f"Error de geolocalización: {e}")Notas de producción que te ahorrarán tiempo
- Encabezado de autenticación: Siempre envía Authorization: Bearer YOUR_API_KEY. No agregues la clave como un parámetro de consulta al endpoint de Geolocalización.
- Tiempos de espera: Las llamadas de red a servicios externos pueden detenerse; establece tiempos de espera razonables para conectar/leerse. En las solicitudes de Python, pasa timeout=(conectar, leer).
- Cacheo: Muchas IPs se repiten a través de sesiones. Cachea las búsquedas por IP (por ejemplo, en Redis) con un TTL apropiado para tu postura de riesgo. Esto reduce la latencia y preserva la cuota.
- Zona horaria: timezone devuelve una cadena IANA (por ejemplo, America/La_Paz). Úsala directamente con bibliotecas como zoneinfo de Python para cálculos y formateo de tiempo.
- Coordenadas: lat/lon son grados decimales. Si los muestras en un mapa, proyecta de acuerdo y maneja los campos faltantes de manera defensiva.
- Indicadores de seguridad: Trata is_proxy, is_vpn, is_tor y threat_level como señales, no como prueba única. Combínalos con tus propias heurísticas antes de hacer cumplir.
- Completitud de datos: Algunos campos (zip, areaCode, dmaCode, languageCode) pueden estar vacíos o nulos. Siempre verifica nulos antes de usarlos.
- Planificación de uso: Zyla utiliza suscripción + cuota. Para tu primera API en Zyla, puedes comenzar con una prueba de 7 días o 50 solicitudes. Realiza un seguimiento de tu uso y escala tu plan según sea necesario.
Casos de uso comunes de geolocalización que puedes implementar esta semana
- Verificaciones de fraude y abuso:
- Bloquear o desafiar registros cuando security.is_proxy, security.is_vpn o security.is_tor sea verdadero.
- Calificar inicios de sesión de mayor riesgo cuando la región no coincida con el comportamiento pasado.
- Restricción de funciones regionales:
- Habilitar/deshabilitar funciones por countryCode o continentName.
- Redirigir a contenido localizado por ciudad/región para mercados de alto tráfico.
- Localidad y moneda:
- Aplicar timezone para notificaciones programadas y formateo de fechas.
- Usar currencyCode y currencyConverter para mostrar precios locales aproximados (marcar claramente como tarifas indicativas).
- Análisis operativo:
- Aumentar registros con country, regionName, isp para informes de tráfico y planificación de capacidad.
Llamando a la API desde agentes de IA a través de MCP
Cada API en Zyla también puede ser llamada desde herramientas compatibles con MCP (por ejemplo, Claude Code, Cursor, Windsurf). Usa el endpoint MCP en: MCP.
Pasos generales:
- Configura tu cliente MCP con el endpoint MCP de Zyla: https://mcp.zylalabs.com/mcp?apikey=YOUR_API_KEY
- Autoriza usando tu clave API de Zyla.
- Desde tu entorno compatible con MCP, llama al endpoint de Geolocalización de la API de Seguimiento Geográfico especificando la misma ruta de solicitud y parámetros descritos anteriormente.
Esto permite que los agentes de codificación de IA organicen llamadas al endpoint de Geolocalización dentro de tu flujo de trabajo de desarrollo mientras reutilizan la misma clave API.
Lista de verificación de solución de problemas
- Errores 401/403: Verifica que te hayas suscrito en la página de la API de Seguimiento Geográfico y que estés enviando Authorization: Bearer YOUR_API_KEY.
- Campos inesperados: No todas las propiedades están garantizadas. Protege contra nulos o cadenas vacías, especialmente para zip, areaCode, dmaCode, languageCode.
- Manejo de respuestas: Verifica data["status"] == "success" antes de consumir campos.
- Rendimiento: Agrega cacheo por IP y lógica de retroceso/reintento para problemas de red transitorios. Monitorea tu uso de suscripción para evitar alcanzar la cuota.
Referencia rápida
- Mercado: zylalabs.com
- Página de la API de Seguimiento Geográfico: API de Seguimiento Geográfico
- Autenticación: Authorization: Bearer YOUR_API_KEY
- Endpoint (GET): https://zylalabs.com/api/2556/geo-tracking-api/6048/geolocation?ip=YOUR_IP
- Acceso a la primera API: prueba de 7 días o 50 solicitudes (sin plan gratuito). Consulta la página de la API para más detalles.
Preguntas Frecuentes
¿Cómo me autentico?
Envía Authorization: Bearer YOUR_API_KEY con cada solicitud. Obtén tu clave después de suscribirte en la página de la API.
¿Cuál es el endpoint exacto para la geolocalización de IP?
GET https://zylalabs.com/api/2556/geo-tracking-api/6048/geolocation con el parámetro de consulta ip requerido.
¿Qué campos indican tráfico riesgoso?
Usa el objeto de seguridad: is_proxy, is_vpn, is_tor, is_tor_exit y threat_level. Combina estos con tus propias reglas de riesgo antes de hacer cumplir.
¿Qué unidades y formatos debo esperar?
lat/lon son grados decimales; timezone es una cadena IANA (por ejemplo, America/La_Paz). Algunos campos textuales pueden estar vacíos o nulos—verifica antes de usarlos.
¿Hay un plan gratuito?
No hay plan gratuito. Para tu primera API en Zyla, puedes comenzar con una prueba de 7 días o 50 solicitudes. Consulta la página de la API para las opciones actuales.
¿Listo para integrar? Crea tu cuenta, suscríbete a la API de Seguimiento Geográfico y obtén tu clave API ahora: Registrarse.
