API de geolocalización IP

GET

curl --request GET \
  --url https://ipgeolocation.cleariflow.com/v1

{
    "ip_address": "80.255.13.30",
    "city": null,
    "city_geoname_id": null,
    "region": null,
    "region_iso_code": null,
    "region_geoname_id": null,
    "postal_code": null,
    "country": "Germany",
    "country_code": "DE",
    "country_geoname_id": 2921044,
    "country_is_eu": true,
    "continent": "Europe",
    "continent_code": "EU",
    "continent_geoname_id": 6255148,
    "longitude": 9.491,
    "latitude": 51.2993,
    "security": {
        "is_vpn": true,
        "is_proxy": false,
        "vpn_provider": "NordVPN"
    },
    "timezone": {
        "name": "Europe/Berlin",
        "abbreviation": "CEST",
        "gmt_offset": 2,
        "current_time": "21:21:22",
        "is_dst": true
    },
    "flag": {
        "emoji": "🇩🇪",
        "unicode": "U+1F1E9 U+1F1EA",
        "png": "https://static.cleariflow.com/country-flags/DE_flag.png",
        "svg": "https://static.cleariflow.com/country-flags/DE_flag.svg"
    },
    "currency": {
        "currency_name": "Euros",
        "currency_code": "EUR"
    },
    "connection": {
        "autonomous_system_number": 201011,
        "autonomous_system_organization": "Core-Backbone GmbH",
        "connection_type": null,
        "isp_name": null,
        "organization_name": null
    }
}

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

https://ipgeolocation.cleariflow.com/v1/

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:

https://ipgeolocation.cleariflow.com/v1/
? api_key = YOUR_UNIQUE_API_KEY
& ip_address = 94.198.41.118 (optional)

Esto representa una solicitud exitosa, que devuelve la dirección IP y los detalles asociados a continuación:

{
    "ip_address": "80.255.13.30",
    "city": null,
    "city_geoname_id": null,
    "region": null,
    "region_iso_code": null,
    "region_geoname_id": null,
    "postal_code": null,
    "country": "Germany",
    "country_code": "DE",
    "country_geoname_id": 2921044,
    "country_is_eu": true,
    "continent": "Europe",
    "continent_code": "EU",
    "continent_geoname_id": 6255148,
    "longitude": 9.491,
    "latitude": 51.2993,
    "security": {
        "is_vpn": true,
        "is_proxy": false,
        "vpn_provider": "NordVPN"
    },
    "timezone": {
        "name": "Europe/Berlin",
        "abbreviation": "CEST",
        "gmt_offset": 2,
        "current_time": "21:21:22",
        "is_dst": true
    },
    "flag": {
        "emoji": "🇩🇪",
        "unicode": "U+1F1E9 U+1F1EA",
        "png": "https://static.cleariflow.com/country-flags/DE_flag.png",
        "svg": "https://static.cleariflow.com/country-flags/DE_flag.svg"
    },
    "currency": {
        "currency_name": "Euros",
        "currency_code": "EUR"
    },
    "connection": {
        "autonomous_system_number": 201011,
        "autonomous_system_organization": "Core-Backbone GmbH",
        "connection_type": null,
        "isp_name": null,
        "organization_name": null
    }
}

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:

https://ipgeolocation.cleariflow.com/v1/
    ? api_key = YOUR_API_KEY
    & ip_address = 94.198.41.122
    & fields = country,city

La respuesta tendría este aspecto:

{
    "city": "Vienna",
    "country": "Austria"
}

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.

$.getJSON("https://ipgeolocation.cleariflow.com/v1/?api_key=YOUR_UNIQUE_API_KEY", function(data) {
   console.log(data.ip_address);
   console.log(data.country);
})

¡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.

Code	Type	Details
200	OK	Todo funcionó como se esperaba.
204	OK	No hay datos de ubicación para la IP enviada.
400	Bad request	Solicitud incorrecta.
401	Unauthorized	La solicitud no fue aceptable. Normalmente debido a que la clave API falta o es incorrecta.
422	Quota reached	La solicitud se abortó por créditos API insuficientes. (Planes gratuitos)
429	Too many requests	La solicitud se abortó porque se alcanzó el número de solicitudes permitidas por segundo. Esto ocurre en planes gratuitos, ya que las solicitudes están limitadas a 1 por segundo.
500	Internal server error	La solicitud no pudo completarse debido a un error en el servidor.
503	Service unavailable	El servidor no estaba disponible.

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.

Nombre del país	Código del país
Afganistán	AF
Albania	AL
Argelia	DZ
Samoa Americana	AS
Andorra	AD
Angola	AO
Anguila	AI
Antigua y Barbuda	AG
Argentina	AR
Armenia	AM
Aruba	AW
Australia	AU
Austria	AT
Azerbaiyán	AZ
Baréin	BH
Bangladesh	BD
Barbados	BB
Bielorrusia	BY
Bélgica	BE
Belice	BZ
Benín	BJ
Bermudas	BM
Bután	BT
Bolivia	BO
Bosnia y Herzegovina	BA
Botsuana	BW
Brasil	BR
Islas Vírgenes Británicas	VG
Brunéi	BN
Bulgaria	BG
Burkina Faso	BF
Burundi	BI
Cabo Verde	CV
Camboya	KH
Camerún	CM
Canadá	CA
Islas Caimán	KY
República Centroafricana	CF
Chad	TD
Chile	CL
China	CN
Colombia	CO
Comoras	KM
Congo	CG
República Democrática del Congo	CD
Islas Cook	CK
Costa Rica	CR
Costa de Marfil	CI
Croacia	HR
Cuba	CU
Curazao	CW
Chipre	CY
Chequia	CZ
Dinamarca	DK
Yibuti	DJ
Dominica	DM
República Dominicana	DO
Timor Oriental	TL
Ecuador	EC
Egipto	EG
El Salvador	SV
Guinea Ecuatorial	GQ
Eritrea	ER
Estonia	EE
Esuatini	SZ
Etiopía	ET
Islas Malvinas	FK
Islas Feroe	FO
Fiyi	FJ
Finlandia	FI
Francia	FR
Guayana Francesa	GF
Polinesia Francesa	PF
Gabón	GA
Gambia	GM
Georgia	GE
Alemania	DE
Ghana	GH
Gibraltar	GI
Grecia	GR
Groenlandia	GL
Granada	GD
Guadalupe	GP
Guam	GU
Guatemala	GT
Guernsey	GG
Guinea	GN
Guinea-Bisáu	GW
Guyana	GY
Haití	HT
Honduras	HN
Hong Kong	HK
Hungría	HU
Islandia	IS
India	IN
Indonesia	ID
Irán	IR
Irak	IQ
Irlanda	IE
Isla de Man	IM
Israel	IL
Italia	IT
Jamaica	JM
Japón	JP
Jersey	JE
Jordania	JO
Kazajistán	KZ
Kenia	KE
Kiribati	KI
Kosovo	XK
Kuwait	KW
Kirguistán	KG
Laos	LA
Letonia	LV
Líbano	LB
Lesoto	LS
Liberia	LR
Libia	LY
Liechtenstein	LI
Lituania	LT
Luxemburgo	LU
Macao	MO
Madagascar	MG
Malaui	MW
Malasia	MY
Maldivas	MV
Malí	ML
Malta	MT
Islas Marshall	MH
Martinica	MQ
Mauritania	MR
Mauricio	MU
Mayotte	YT
México	MX
Micronesia	FM
Moldavia	MD
Mónaco	MC
Mongolia	MN
Montenegro	ME
Montserrat	MS
Marruecos	MA
Mozambique	MZ
Myanmar	MM
Namibia	NA
Nauru	NR
Nepal	NP
Países Bajos	NL
Nueva Caledonia	NC
Nueva Zelanda	NZ
Nicaragua	NI
Níger	NE
Nigeria	NG
Corea del Norte	KP
Macedonia del Norte	MK
Islas Marianas del Norte	MP
Noruega	NO
Omán	OM
Pakistán	PK
Palaos	PW
Panamá	PA
Papúa Nueva Guinea	PG
Paraguay	PY
Perú	PE
Filipinas	PH
Polonia	PL
Portugal	PT
Puerto Rico	PR
Catar	QA
Reunión	RE
Rumanía	RO
Rusia	RU
Ruanda	RW
Santa Elena	SH
San Cristóbal y Nieves	KN
Santa Lucía	LC
San Martín	MF
San Pedro y Miquelón	PM
San Vicente y las Granadinas	VC
Samoa	WS
San Marino	SM
Santo Tomé y Príncipe	ST
Arabia Saudita	SA
Senegal	SN
Serbia	RS
Seychelles	SC
Sierra Leona	SL
Singapur	SG
Sint Maarten	SX
Eslovaquia	SK
Eslovenia	SI
Islas Salomón	SB
Somalia	SO
Sudáfrica	ZA
Corea del Sur	KR
Sudán del Sur	SS
España	ES
Sri Lanka	LK
San Bartolomé	BL
Sudán	SD
Surinam	SR
Suecia	SE
Suiza	CH
Siria	SY
Taiwán	TW
Tayikistán	TJ
Tanzania	TZ
Tailandia	TH
Bahamas	BS
Togo	TG
Tonga	TO
Trinidad y Tobago	TT
Túnez	TN
Turquía	TR
Turkmenistán	TM
Islas Turcas y Caicos	TC
Tuvalu	TV
Uganda	UG
Ucrania	UA
Emiratos Árabes Unidos	AE
Reino Unido	GB
Estados Unidos	US
Uruguay	UY
Islas Vírgenes de EE. UU.	VI
Uzbekistán	UZ
Vanuatu	VU
Ciudad del Vaticano	VA
Venezuela	VE
Vietnam	VN
Wallis y Futuna	WF
Yemen	YE
Zambia	ZM
Zimbabue	ZW

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.

IntroducciónLa API de tipos de cambio de Cleariflow ofrece capacidades de conversión de divisas en tiempo real a través de una interfaz JSON RESTful moderna y simplificada, con soporte para más de 80 divisas globales, tipos en vivo, datos históricos y herramientas de conversión instantánea.

API de geolocalización IP

curl --request GET \
  --url https://ipgeolocation.cleariflow.com/v1

{
    "ip_address": "80.255.13.30",
    "city": null,
    "city_geoname_id": null,
    "region": null,
    "region_iso_code": null,
    "region_geoname_id": null,
    "postal_code": null,
    "country": "Germany",
    "country_code": "DE",
    "country_geoname_id": 2921044,
    "country_is_eu": true,
    "continent": "Europe",
    "continent_code": "EU",
    "continent_geoname_id": 6255148,
    "longitude": 9.491,
    "latitude": 51.2993,
    "security": {
        "is_vpn": true,
        "is_proxy": false,
        "vpn_provider": "NordVPN"
    },
    "timezone": {
        "name": "Europe/Berlin",
        "abbreviation": "CEST",
        "gmt_offset": 2,
        "current_time": "21:21:22",
        "is_dst": true
    },
    "flag": {
        "emoji": "🇩🇪",
        "unicode": "U+1F1E9 U+1F1EA",
        "png": "https://static.cleariflow.com/country-flags/DE_flag.png",
        "svg": "https://static.cleariflow.com/country-flags/DE_flag.svg"
    },
    "currency": {
        "currency_name": "Euros",
        "currency_code": "EUR"
    },
    "connection": {
        "autonomous_system_number": 201011,
        "autonomous_system_organization": "Core-Backbone GmbH",
        "connection_type": null,
        "isp_name": null,
        "organization_name": null
    }
}

​Primeros pasos

​Arquitectura REST

​Seguridad HTTPS

​Versionado de la API

​Autenticación con clave API

​URL base

​Endpoint de geolocalización

​Parámetros de solicitud

​Parámetros de respuesta

​Limitar campos de respuesta

​Casos de uso

​Geolocalizar a un visitante del sitio web

​Códigos de respuesta y error

​Códigos de país

​Otras notas

Primeros pasos

Arquitectura REST

Seguridad HTTPS

Versionado de la API

Autenticación con clave API

URL base

Endpoint de geolocalización

Parámetros de solicitud

Parámetros de respuesta

Limitar campos de respuesta

Casos de uso

Geolocalizar a un visitante del sitio web

Códigos de respuesta y error

Códigos de país

Otras notas