API de geolocalização 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
    }
}

A API funciona com notável simplicidade: basta fornecer a sua chave API juntamente com um endereço IP e receberá dados de localização abrangentes, incluindo códigos postais, nomes de cidades, informações regionais, detalhes do país e coordenadas precisas de latitude/longitude.

Primeiros passos

Arquitetura REST

Tal como todas as APIs Cleariflow, a API de geolocalização IP segue os princípios REST. Utiliza URLs previsíveis e orientadas a recursos e códigos de estado HTTP para indicar erros.

Segurança HTTPS

Todas as comunicações com a API de geolocalização IP devem ser protegidas com TLS 1.2 ou superior.

Versionamento da API

Todas as APIs Cleariflow incorporam versionamento. A API de geolocalização IP opera atualmente na Versão 1.

Autenticação com chave API

A sua chave API serve como credencial de autenticação única para aceder à API de geolocalização IP da Cleariflow. Note que cada API Cleariflow requer uma chave API distinta, pelo que precisará de chaves separadas para geolocalização IP e validação de email. Para autenticar os seus pedidos, anexe a chave API à URL base.

URL base

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

Endpoint de geolocalização

A API de geolocalização IP da Cleariflow requer apenas a sua chave API única e deteta automaticamente o endereço IP do cliente que faz o pedido. Em alternativa, pode incluir o parâmetro ip_address para especificar um IP particular para análise:

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

Isto representa um pedido bem-sucedido, devolvendo o endereço IP e os detalhes associados abaixo:

{
    "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 pedido

api_key

String

obrigatório

A sua chave API única. Note que cada utilizador tem chaves API únicas para cada API Cleariflow — a sua chave da API de geolocalização IP não funcionará para a API de validação de email, por exemplo.

ip_address

String

O endereço IP a geolocalizar. Endereços IPv4 e IPv6 são suportados. Se deixar este parâmetro em branco, o serviço geolocaliza o endereço IP de onde o pedido foi feito.

fields

String

Lista separada por vírgulas de chaves de nível superior a devolver (por exemplo, ?fields=country,security). Para incluir flags VPN/proxy, utilize security — o objeto completo é devolvido (is_vpn, is_proxy e vpn_provider quando presente). Chaves aninhadas como apenas is_vpn não são suportadas.

Parâmetros de resposta

A resposta da API é devolvida num formato JSON universal e leve.

ip_address

String

O endereço IP enviado para geolocalização.

city

String

Nome da cidade.

city_geoname_id

String

ID Geoname da cidade.

region

String

Estado ou província onde a cidade se localiza.

region_iso_code

Char[2]

Código ISO 3166-2 do estado ou província.

region_geoname_id

String

ID Geoname do estado ou província.

postal_code

String

Código postal.

country

String

Nome do país.

country_code

Char[2]

Código ISO 3166-1 alpha-2 do país.

country_geoname_id

String

ID Geoname do país.

country_is_eu

Boolean

true se o país pertence à UE, false caso contrário.

continent

String

Nome do continente.

continent_code

Char[2]

Código de continente de 2 letras: AF, AS, EU, NA, OC, SA, AN.

continent_geoname_id

String

ID Geoname do continente.

longitude

Float

Decimal da longitude.

latitude

Float

Decimal da latitude.

security.is_vpn

Boolean

true quando o IP corresponde à base de dados enumerada de nós de saída VPN (IP-to-VPN MMDB).

security.is_proxy

Boolean

true quando o IP corresponde à base de dados de proxy (IP-to-VPN MMDB).

security.vpn_provider

String

Nome do serviço VPN da MMDB (por exemplo, NordVPN). Omitido quando is_vpn é false.

timezone.name

String

Nome do fuso horário da IANA Time Zone Database.

timezone.abbreviation

String

Abreviatura do fuso horário, também da IANA Time Zone Database.

timezone.gmt_offset

String

Offset do fuso horário em relação ao Greenwich Mean Time (GMT).

timezone.current_time

String

Hora atual no fuso horário local.

timezone.is_dst

Boolean

true se a localização está atualmente em horário de verão (DST).

flag.svg

String

Ligação a uma versão alojada da bandeira do país em formato SVG.

flag.png

String

Ligação a uma versão alojada da bandeira do país em formato PNG.

flag.emoji

String

Bandeira do país como emoji.

flag.unicode

String

Bandeira do país em unicode.

currency.currency_name

String

Nome da moeda.

currency.currency_code

String

Código da moeda no formato ISO 4217.

connection.connection_type

String

Inferido a partir do nome da organização ASN (por exemplo, Cellular, Cable/DSL, Corporate, Cloud, Hosting). VPN e proxy são reportados em security, não aqui.

connection.autonomous_system_number

Uint32

Número do Autonomous System.

connection.autonomous_system_organization

String

Nome da organização do Autonomous System.

connection.isp_name

String

Nome do Internet Service Provider (ISP).

connection.organization_name

String

Nome da organização.

Limitar campos de resposta

Pode optar por receber apenas alguns campos da resposta JSON. Para isso, inclua um valor fields nos parâmetros de consulta com uma lista separada por vírgulas das chaves de nível superior que pretende receber. Por exemplo, um pedido para obter apenas o país e a cidade de um IP terá este aspeto:

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

A resposta terá este aspeto:

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

Casos de uso

Geolocalizar um visitante do website

Para solicitar a geolocalização de um endereço IP, inclua simplesmente a sua chave API única no modelo abaixo. Note que não precisa de conhecer o IP do visitante para fazer o pedido.

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

É tudo o que precisa para obter a geolocalização e outros dados de um visitante! Há apenas um parâmetro obrigatório: a sua chave API única.

Códigos de resposta e erro

Sempre que um pedido falha por algum motivo, é devolvido um erro também em formato JSON. Os erros incluem um código e uma descrição, que pode consultar em detalhe abaixo.

Code	Type	Detalhes
200	OK	Tudo funcionou como esperado.
204	OK	Não existem dados de localização para o IP enviado.
400	Bad request	Pedido inválido.
401	Unauthorized	O pedido não foi aceite — normalmente devido a uma chave API em falta ou incorreta.
422	Quota reached	O pedido foi abortado devido a créditos API insuficientes (planos gratuitos).
429	Too many requests	O pedido foi abortado porque foi atingido o número de pedidos permitidos por segundo. Isto acontece em planos gratuitos, pois os pedidos estão limitados a 1 por segundo.
500	Internal server error	O pedido não pôde ser concluído devido a um erro no servidor.
503	Service unavailable	O servidor estava indisponível.

Códigos de país

Abaixo está uma lista de códigos de país ISO 3166 Alpha 2 de duas letras utilizados na resposta. Consulte esta lista em CSV.

Nome do país	Código do país
Afghanistan	AF
Albania	AL
Algeria	DZ
American Samoa	AS
Andorra	AD
Angola	AO
Anguilla	AI
Antigua and Barbuda	AG
Argentina	AR
Armenia	AM
Aruba	AW
Australia	AU
Austria	AT
Azerbaijan	AZ
Bahrain	BH
Bangladesh	BD
Barbados	BB
Belarus	BY
Belgium	BE
Belize	BZ
Benin	BJ
Bermuda	BM
Bhutan	BT
Bolivia	BO
Bosnia and Herzegovina	BA
Botswana	BW
Brazil	BR
British Virgin Islands	VG
Brunei	BN
Bulgaria	BG
Burkina Faso	BF
Burundi	BI
Cabo Verde	CV
Cambodia	KH
Cameroon	CM
Canada	CA
Cayman Islands	KY
Central African Republic	CF
Chad	TD
Chile	CL
China	CN
Colombia	CO
Comoros	KM
Congo	CG
Congo Democratic Republic	CD
Cook Islands	CK
Costa Rica	CR
Cote d’Ivoire	CI
Croatia	HR
Cuba	CU
Curaçao	CW
Cyprus	CY
Czechia	CZ
Denmark	DK
Djibouti	DJ
Dominica	DM
Dominican Republic	DO
East Timor	TL
Ecuador	EC
Egypt	EG
El Salvador	SV
Equatorial Guinea	GQ
Eritrea	ER
Estonia	EE
eSwatini	SZ
Ethiopia	ET
Falkland Islands	FK
Faroe Islands	FO
Fiji	FJ
Finland	FI
France	FR
French Guiana	GF
French Polynesia	PF
Gabon	GA
Gambia	GM
Georgia	GE
Germany	DE
Ghana	GH
Gibraltar	GI
Greece	GR
Greenland	GL
Grenada	GD
Guadeloupe	GP
Guam	GU
Guatemala	GT
Guernsey	GG
Guinea	GN
Guinea-Bissau	GW
Guyana	GY
Haiti	HT
Honduras	HN
Hong Kong	HK
Hungary	HU
Iceland	IS
India	IN
Indonesia	ID
Iran	IR
Iraq	IQ
Ireland	IE
Isle of Man	IM
Israel	IL
Italy	IT
Jamaica	JM
Japan	JP
Jersey	JE
Jordan	JO
Kazakhstan	KZ
Kenya	KE
Kiribati	KI
Kosovo	XK
Kuwait	KW
Kyrgyzstan	KG
Laos	LA
Latvia	LV
Lebanon	LB
Lesotho	LS
Liberia	LR
Libya	LY
Liechtenstein	LI
Lithuania	LT
Luxembourg	LU
Macau	MO
Madagascar	MG
Malawi	MW
Malaysia	MY
Maldives	MV
Mali	ML
Malta	MT
Marshall Islands	MH
Martinique	MQ
Mauritania	MR
Mauritius	MU
Mayotte	YT
Mexico	MX
Micronesia	FM
Moldova	MD
Monaco	MC
Mongolia	MN
Montenegro	ME
Montserrat	MS
Morocco	MA
Mozambique	MZ
Myanmar	MM
Namibia	NA
Nauru	NR
Nepal	NP
Netherlands	NL
New Caledonia	NC
New Zealand	NZ
Nicaragua	NI
Niger	NE
Nigeria	NG
North Korea	KP
North Macedonia	MK
Northern Mariana Islands	MP
Norway	NO
Oman	OM
Pakistan	PK
Palau	PW
Panama	PA
Papua New Guinea	PG
Paraguay	PY
Peru	PE
Philippines	PH
Poland	PL
Portugal	PT
Puerto Rico	PR
Qatar	QA
Reunion	RE
Romania	RO
Russia	RU
Rwanda	RW
Saint Helena	SH
Saint Kitts and Nevis	KN
Saint Lucia	LC
Saint Martin	MF
Saint Pierre and Miquelon	PM
Saint Vincent and the Grenadines	VC
Samoa	WS
San Marino	SM
Sao Tome and Principe	ST
Saudi Arabia	SA
Senegal	SN
Serbia	RS
Seychelles	SC
Sierra Leone	SL
Singapore	SG
Sint Maarten	SX
Slovakia	SK
Slovenia	SI
Solomon Islands	SB
Somalia	SO
South Africa	ZA
South Korea	KR
South Sudan	SS
Spain	ES
Sri Lanka	LK
St. Barts	BL
Sudan	SD
Suriname	SR
Sweden	SE
Switzerland	CH
Syria	SY
Taiwan	TW
Tajikistan	TJ
Tanzania	TZ
Thailand	TH
The Bahamas	BS
Togo	TG
Tonga	TO
Trinidad and Tobago	TT
Tunisia	TN
Turkey	TR
Turkmenistan	TM
Turks and Caicos Islands	TC
Tuvalu	TV
Uganda	UG
Ukraine	UA
United Arab Emirates	AE
United Kingdom	GB
United States	US
Uruguay	UY
US Virgin Islands	VI
Uzbekistan	UZ
Vanuatu	VU
Vatican City (Holy See)	VA
Venezuela	VE
Vietnam	VN
Wallis and Futuna	WF
Yemen	YE
Zambia	ZM
Zimbabwe	ZW

Outras notas

Informação importante de faturação: cada endereço IP processado consome um crédito. A faturação ocorre por pedido submetido, independentemente de a resposta ser bem-sucedida. Portanto, mesmo submeter um endereço IP inválido como “fda3346ds” deduzirá um crédito da sua conta.

IntroduçãoA API de taxas de câmbio da Cleariflow oferece conversão de moeda em tempo real através de uma interface RESTful JSON moderna — com suporte para mais de 80 moedas globais, taxas ao vivo e conversão instantânea.

API de geolocalização 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
    }
}

​Primeiros passos

​Arquitetura REST

​Segurança HTTPS

​Versionamento da API

​Autenticação com chave API

​URL base

​Endpoint de geolocalização

​Parâmetros de pedido

​Parâmetros de resposta

​Limitar campos de resposta

​Casos de uso

​Geolocalizar um visitante do website

​Códigos de resposta e erro

​Códigos de país

​Outras notas

Primeiros passos

Arquitetura REST

Segurança HTTPS

Versionamento da API

Autenticação com chave API

URL base

Endpoint de geolocalização

Parâmetros de pedido

Parâmetros de resposta

Limitar campos de resposta

Casos de uso

Geolocalizar um visitante do website

Códigos de resposta e erro

Códigos de país

Outras notas