Skip to main content
GET
API de geolocalización IP
La API funciona con notable sencillez: solo proporcione su clave API junto con una dirección IP y recibirá datos de ubicación completos, incluidos códigos postales, nombres de ciudades, información regional, detalles del país y coordenadas precisas de latitud/longitud.

Primeros pasos

Arquitectura REST

Al igual que todas las APIs de Cleariflow, la API de geolocalización IP sigue los principios REST. Emplea URL predecibles orientadas a recursos y utiliza códigos de estado HTTP para indicar errores.

Seguridad HTTPS

Todas las comunicaciones con la API de geolocalización IP deben estar protegidas mediante protocolos TLS 1.2 o superiores.

Versionado de la API

Todas las APIs de Cleariflow incorporan versionado. La API de geolocalización IP opera actualmente en la versión 1.

Autenticación con clave API

Su clave API sirve como credencial de autenticación única para acceder a la API de geolocalización IP de Cleariflow. Es importante tener en cuenta que cada API de Cleariflow requiere una clave API distinta, lo que significa que necesitará claves separadas para distintos servicios como las APIs de geolocalización IP y validación de email. Para autenticar sus solicitudes, añada su clave API a la URL base.

URL base

Endpoint de geolocalización

La API de geolocalización IP de Cleariflow solo requiere su clave API única y detecta automáticamente la dirección IP del cliente que realiza la solicitud. Alternativamente, puede incluir el parámetro “ip_address” para especificar una IP concreta para el análisis:
Esto representa una solicitud exitosa, que devuelve la dirección IP y los detalles asociados a continuación:

Parámetros de solicitud

String
requerido
Su clave API única. Tenga en cuenta que cada usuario tiene claves API únicas para cada una de las APIs de Cleariflow, por lo que su clave de la API de geolocalización IP no funcionará para su API de validación de email, por ejemplo.
String
La dirección IP a geolocalizar. Se admiten direcciones IPv4 e IPv6. Tenga en cuenta que si deja este parámetro en blanco, el servicio geolocalizará la dirección IP desde la que se realizó la solicitud.
String
Lista separada por comas de claves de nivel superior a devolver (por ejemplo, ?fields=country,security). Para incluir indicadores VPN/proxy, use security: se devuelve el objeto completo (is_vpn, is_proxy y vpn_provider cuando esté presente). No se admiten claves anidadas como is_vpn por sí solas.

Parámetros de respuesta

La respuesta de la API se devuelve en un formato JSON universal y ligero.
String
La dirección IP enviada para geolocalización.
String
Nombre de la ciudad.
String
ID de geoname de la ciudad.
String
Estado o provincia en el que se encuentra la ciudad.
Char[2]
Código ISO 3166-2 del estado o provincia.
String
ID de geoname del estado o provincia.
String
Código postal.
String
Nombre del país.
Char[2]
Código ISO 3166-1 alpha-2 del país.
String
ID de geoname del país.
Boolean
Verdadero si el país está en la UE, falso si no lo está.
String
Nombre del continente.
Char[2]
Código de continente de 2 letras: AF, AS, EU, NA, OC, SA, AN.
String
ID de geoname del continente.
Float
Decimal de la longitud.
Float
Decimal de la latitud.
Boolean
true cuando la IP coincide con la base de datos enumerada de nodos de salida VPN (IP-to-VPN MMDB).
Boolean
true cuando la IP coincide con la base de datos de proxy (IP-to-VPN MMDB).
String
Nombre del servicio VPN de la MMDB (por ejemplo, NordVPN). Se omite cuando is_vpn es false.
String
Nombre de la zona horaria de la base de datos IANA Time Zone Database.
String
Abreviatura de la zona horaria, también de la base de datos IANA Time Zone Database.
String
Desplazamiento de la zona horaria respecto al horario del meridiano de Greenwich (GMT).
String
Hora actual en la zona horaria local.
Boolean
Verdadero si la ubicación está actualmente en horario de verano (DST).
String
Enlace a una versión alojada de la bandera del país en formato SVG.
String
Enlace a una versión alojada de la bandera del país en formato PNG.
String
Bandera del país como emoji.
String
Bandera del país en unicode.
String
Nombre de la moneda.
String
Código de la moneda en formato ISO 4217.
String
Inferido del nombre de la organización ASN (por ejemplo, Cellular, Cable/DSL, Corporate, Cloud, Hosting). VPN y proxy se informan en security, no aquí.
Uint32
Número de sistema autónomo.
String
Nombre de la organización del sistema autónomo.
String
Nombre del proveedor de servicios de Internet (ISP).
String
Nombre de la organización.

Limitar campos de respuesta

Puede elegir recibir solo algunos campos de la respuesta JSON. Para ello, puede incluir un valor fields en los parámetros de consulta con una lista separada por comas de las claves de nivel superior que desea que se devuelvan. Por ejemplo, una solicitud para obtener solo el país y la ciudad de una IP tendrá este aspecto:
La respuesta tendría este aspecto:

Casos de uso

Geolocalizar a un visitante del sitio web

Para solicitar la geolocalización de una dirección IP, simplemente incluya su clave API única en la plantilla siguiente. Tenga en cuenta que no necesita conocer la IP del visitante para realizar la solicitud.
¡Eso es todo lo que necesita para obtener la geolocalización y otros datos de un visitante! Solo hay un parámetro obligatorio: su clave API única.

Códigos de respuesta y error

Siempre que realice una solicitud que falle por algún motivo, también se devuelve un error en formato JSON. Los errores incluyen un código y una descripción, que puede encontrar en detalle a continuación.

Códigos de país

A continuación se muestra una lista de códigos de país ISO 3166 Alpha 2 de dos letras que se utilizan en la respuesta. Vea esta lista en un CSV.

Otras notas

Información importante de facturación: cada dirección IP que procese consume un crédito. La facturación se realiza por solicitud enviada, independientemente de si la respuesta es exitosa. Por lo tanto, incluso enviar una dirección IP no válida como “fda3346ds” seguirá descontando un crédito de su cuenta.