Skip to main content
GET
API de geolocalização IP
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

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:
Isto representa um pedido bem-sucedido, devolvendo o endereço IP e os detalhes associados abaixo:

Parâmetros de pedido

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.
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.
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.
String
O endereço IP enviado para geolocalização.
String
Nome da cidade.
String
ID Geoname da cidade.
String
Estado ou província onde a cidade se localiza.
Char[2]
Código ISO 3166-2 do estado ou província.
String
ID Geoname do estado ou província.
String
Código postal.
String
Nome do país.
Char[2]
Código ISO 3166-1 alpha-2 do país.
String
ID Geoname do país.
Boolean
true se o país pertence à UE, false caso contrário.
String
Nome do continente.
Char[2]
Código de continente de 2 letras: AF, AS, EU, NA, OC, SA, AN.
String
ID Geoname do continente.
Float
Decimal da longitude.
Float
Decimal da latitude.
Boolean
true quando o IP corresponde à base de dados enumerada de nós de saída VPN (IP-to-VPN MMDB).
Boolean
true quando o IP corresponde à base de dados de proxy (IP-to-VPN MMDB).
String
Nome do serviço VPN da MMDB (por exemplo, NordVPN). Omitido quando is_vpn é false.
String
Nome do fuso horário da IANA Time Zone Database.
String
Abreviatura do fuso horário, também da IANA Time Zone Database.
String
Offset do fuso horário em relação ao Greenwich Mean Time (GMT).
String
Hora atual no fuso horário local.
Boolean
true se a localização está atualmente em horário de verão (DST).
String
Ligação a uma versão alojada da bandeira do país em formato SVG.
String
Ligação a uma versão alojada da bandeira do país em formato PNG.
String
Bandeira do país como emoji.
String
Bandeira do país em unicode.
String
Nome da moeda.
String
Código da moeda no formato ISO 4217.
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.
Uint32
Número do Autonomous System.
String
Nome da organização do Autonomous System.
String
Nome do Internet Service Provider (ISP).
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:
A resposta terá este aspeto:

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

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.

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.