Saltar al contenido principal
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

api_key
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.
ip_address
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.
fields
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.
ip_address
String
La dirección IP enviada para geolocalización.
city
String
Nombre de la ciudad.
city_geoname_id
String
ID de geoname de la ciudad.
region
String
Estado o provincia en el que se encuentra la ciudad.
region_iso_code
Char[2]
Código ISO 3166-2 del estado o provincia.
region_geoname_id
String
ID de geoname del estado o provincia.
postal_code
String
Código postal.
country
String
Nombre del país.
country_code
Char[2]
Código ISO 3166-1 alpha-2 del país.
country_geoname_id
String
ID de geoname del país.
country_is_eu
Boolean
Verdadero si el país está en la UE, falso si no lo está.
continent
String
Nombre del continente.
continent_code
Char[2]
Código de continente de 2 letras: AF, AS, EU, NA, OC, SA, AN.
continent_geoname_id
String
ID de geoname del continente.
longitude
Float
Decimal de la longitud.
latitude
Float
Decimal de la latitud.
security.is_vpn
Boolean
true cuando la IP coincide con la base de datos enumerada de nodos de salida VPN (IP-to-VPN MMDB).
security.is_proxy
Boolean
true cuando la IP coincide con la base de datos de proxy (IP-to-VPN MMDB).
security.vpn_provider
String
Nombre del servicio VPN de la MMDB (por ejemplo, NordVPN). Se omite cuando is_vpn es false.
timezone.name
String
Nombre de la zona horaria de la base de datos IANA Time Zone Database.
timezone.abbreviation
String
Abreviatura de la zona horaria, también de la base de datos IANA Time Zone Database.
timezone.gmt_offset
String
Desplazamiento de la zona horaria respecto al horario del meridiano de Greenwich (GMT).
timezone.current_time
String
Hora actual en la zona horaria local.
timezone.is_dst
Boolean
Verdadero si la ubicación está actualmente en horario de verano (DST).
flag.svg
String
Enlace a una versión alojada de la bandera del país en formato SVG.
flag.png
String
Enlace a una versión alojada de la bandera del país en formato PNG.
flag.emoji
String
Bandera del país como emoji.
flag.unicode
String
Bandera del país en unicode.
currency.currency_name
String
Nombre de la moneda.
currency.currency_code
String
Código de la moneda en formato ISO 4217.
connection.connection_type
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í.
connection.autonomous_system_number
Uint32
Número de sistema autónomo.
connection.autonomous_system_organization
String
Nombre de la organización del sistema autónomo.
connection.isp_name
String
Nombre del proveedor de servicios de Internet (ISP).
connection.organization_name
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.