Guia de Integração da API de Rastreamento Geográfico Python com o Zyla API Hub

Você precisa resolver a localização de um usuário a partir de um endereço IP, restringir recursos por região e sinalizar tráfego arriscado—esta semana. Ao final deste guia, você irá consultar o endpoint de Geolocalização da API de Rastreamento Geográfico a partir do Python, analisar a resposta que você realmente precisa (lat/lon, cidade, ISP, sinais de ameaça) e implementar com autenticação e faturamento funcionando no Zyla API Hub.

O que a API de Rastreamento Geográfico fornece

A API de Rastreamento Geográfico retorna detalhes de geolocalização para um endereço IP específico. Inclui:

Ilustração: Guia de Integração da API de Rastreamento Geográfico Python com o Zyla API Hub

País, região, cidade, fuso horário
Latitude e longitude
ISP, organização e nome do host
Continente e contexto da moeda
Sinais de segurança (presença de proxy/VPN/Tor, nível de ameaça)

Implementações comuns: controles de conteúdo regionais, triagem de fraudes, UX ciente da localidade (fuso horário e moeda), avaliação de risco de pedidos e registro ou análise baseados em localização.

Autenticação e faturamento no Zyla API Hub

O Zyla API Hub utiliza um modelo de assinatura + cota em seu catálogo de mais de 10.000 APIs públicas. A autenticação é feita através de uma única chave de API enviada como um cabeçalho Authorization: Bearer. Para sua primeira API no Zyla, você pode começar com um teste de 7 dias ou 50 solicitações (sem plano gratuito além disso). Verifique a página da API para opções de acesso e preços atuais.

Pontos-chave:

Uma conta e uma chave de API para cada API no Zyla.
Sem pagamento por chamada; os planos são de assinatura + cota.
Aplique o mesmo cabeçalho Authorization: Bearer YOUR_API_KEY para cada solicitação.

Você pode navegar pelo marketplace em zylalabs.com ou ir diretamente para a lista da API de Rastreamento Geográfico para se inscrever.

Começando no Zyla API Hub

Abra a página da API de Rastreamento Geográfico.
Clique em Inscrever-se (ou Começar Teste Gratuito, se disponível) para ativar o acesso.
Copie sua chave de API do seu painel.

Quando você estiver pronto para implementar, passe sua chave como Authorization: Bearer YOUR_API_KEY em cada solicitação.

Endpoint: Geolocalização

A API de Rastreamento Geográfico expõe um único endpoint de Geolocalização para resolução de IP para geolocalização.

Método: GET
URL: https://zylalabs.com/api/2556/geo-tracking-api/6048/geolocation
Parâmetro de consulta obrigatório:
- ip (string): o endereço IP a ser resolvido

Exemplo oficial de cURL

curl -s -X GET "https://zylalabs.com/api/2556/geo-tracking-api/6048/geolocation?ip=181.188.132.167" \
-H "Authorization: Bearer YOUR_API_KEY"

Exemplo de resposta JSON oficial

{
"status": "success",
"country": "BO",
"countryCode": "BO",
"region": "Departamento de La Paz",
"regionName": "Departamento de Santa Cruz",
"city": "La Paz",
"zip": "",
"lat": -17.7834,
"lon": -63.1822,
"timezone": "America/La_Paz",
"isp": "Telefónica Celular de Bolivia S.A.",
"org": "AS27882 Telefónica Celular de Bolivia S.A.",
"as": "AS27882 Telefónica Celular de Bolivia S.A.",
"query": "181.188.132.167",
"areaCode": "",
"dmaCode": "",
"inEU": 0,
"euVATrate": false,
"continentCode": "SA",
"continentName": "América do Sul",
"locationAccuracyRadius": "5",
"currencyCode": "BOB",
"currencySymbol": "$b",
"currencySymbol_UTF8": "$b",
"currencyConverter": 6.9324,
"flag": "🇧🇴",
"callingCode": "591",
"languageCode": null,
"security": {
"is_proxy": false,
"proxy_type": null,
"is_tor": false,
"is_tor_exit": false,
"threat_level": "Baixo",
"threat_score": "0",
"is_abuser": false,
"is_attacker": false,
"is_bogon": false,
"is_cloud_provider": false,
"is_relay": false,
"is_vpn": false,
"is_anonymous": false,
"is_threat": false
},
"hostname": "scz-181-188-132-00167.tigo.bo",
"classType": "classe B",
"application": "Redes médias"
}

Destaques dos campos que você provavelmente usará:

lat, lon: coordenadas em graus decimais.
country, countryCode, region, regionName, city: geodados textuais para políticas e personalização.
timezone: string de fuso horário IANA para agendamento e formatação cientes da localidade.
isp, org, as, hostname: propriedade e contexto de roteamento da rede.
security.*: flags booleanos e metadados de ameaça para pontuação de risco.
currencyCode e currencyConverter: contexto de moeda, útil para exibição e conversões.

Integração com Python

O seguinte exemplo em Python chama o endpoint de Geolocalização, lida com a autenticação, verifica o campo de status da API e extrai os campos mais práticos para restrição de recursos e registro.

import os
import requests

API_KEY = os.getenv("ZYLA_API_KEY", "YOUR_API_KEY")
BASE_URL = "https://zylalabs.com/api/2556/geo-tracking-api/6048/geolocation"

def geolocate_ip(ip: str) -> dict:
headers = {
"Authorization": f"Bearer {API_KEY}"
}
params = {"ip": ip}

# Ajuste os timeouts para o seu ambiente; usando (conectar, ler)
resp = requests.get(BASE_URL, headers=headers, params=params, timeout=(5, 10))
resp.raise_for_status()
data = resp.json()

# A API retorna um campo "status"; verifique-o antes de confiar nos campos
if data.get("status") != "success":
raise RuntimeError(f"Falha na busca geográfica para {ip}: {data}")

return {
"ip": data.get("query"),
"country": data.get("country"),
"countryCode": data.get("countryCode"),
"region": data.get("region"),
"regionName": data.get("regionName"),
"city": data.get("city"),
"lat": data.get("lat"),
"lon": data.get("lon"),
"timezone": data.get("timezone"),
"isp": data.get("isp"),
"org": data.get("org"),
"as": data.get("as"),
"hostname": data.get("hostname"),
"security": data.get("security", {}),
"currencyCode": data.get("currencyCode"),
"currencyConverter": data.get("currencyConverter"),
}

if __name__ == "__main__":
target_ip = "181.188.132.167"
try:
result = geolocate_ip(target_ip)
print("Geodados resolvidos:")
for k, v in result.items():
print(f" {k}: {v}")
# Exemplo de uso:
# if result["security"].get("is_proxy") or result["security"].get("is_vpn"):
# sinalizar usuário/sessão para verificação adicional.
except Exception as e:
# Produção: integre com seu registro/alerta
print(f"Erro de geolocalização: {e}")

Notas de produção que economizarão seu tempo

Cabeçalho de autenticação: Sempre envie Authorization: Bearer YOUR_API_KEY. Não anexe a chave como um parâmetro de consulta ao endpoint de Geolocalização.
Timeouts: Chamadas de rede para serviços externos podem travar; defina timeouts de conexão/leitura razoáveis. No requests do Python, passe timeout=(conectar, ler).
Cache: Muitos IPs se repetem em sessões. Armazene em cache as buscas por IP (por exemplo, no Redis) com um TTL apropriado para sua postura de risco. Isso reduz a latência e preserva a cota.
Fuso horário: timezone retorna uma string IANA (por exemplo, America/La_Paz). Use-a diretamente com bibliotecas como zoneinfo do Python para cálculos e formatação de tempo.
Coordenadas: lat/lon são graus decimais. Se você exibi-los em um mapa, projete de acordo e trate campos ausentes defensivamente.
Flags de segurança: Trate is_proxy, is_vpn, is_tor e threat_level como sinal, não como prova única. Combine com suas próprias heurísticas antes da aplicação.
Completude dos dados: Alguns campos (zip, areaCode, dmaCode, languageCode) podem estar vazios ou nulos. Sempre verifique nulos antes do uso.
Planejamento de uso: O Zyla utiliza assinatura + cota. Para sua primeira API no Zyla, você pode começar com um teste de 7 dias ou 50 solicitações. Acompanhe seu uso e escale seu plano conforme necessário.

Casos de uso comuns de geolocalização que você pode implementar esta semana

Verificações de fraude e abuso:
- Bloquear ou desafiar inscrições quando security.is_proxy, security.is_vpn ou security.is_tor for verdadeiro.
- Aumentar a pontuação de logins de maior risco quando a região não corresponder ao comportamento passado.
Restrições de recursos regionais:
- Ativar/desativar recursos por countryCode ou continentName.
- Redirecionar para conteúdo localizado por cidade/região para mercados de alto tráfego.
Localidade e moeda:
- Aplicar fuso horário para notificações programadas e formatação de datas.
- Usar currencyCode e currencyConverter para exibir preços locais aproximados (marcar claramente como taxas indicativas).
Análise operacional:
- Aumentar logs com country, regionName, isp para relatórios de tráfego e planejamento de capacidade.

Chamando a API de agentes de IA via MCP

Toda API no Zyla também pode ser chamada de ferramentas compatíveis com MCP (por exemplo, Claude Code, Cursor, Windsurf). Use o endpoint MCP em: MCP.

Passos de alto nível:

Configure seu cliente MCP com o endpoint MCP do Zyla: https://mcp.zylalabs.com/mcp?apikey=YOUR_API_KEY
Autorize usando sua chave de API do Zyla.
Do seu ambiente compatível com MCP, chame o endpoint de Geolocalização da API de Rastreamento Geográfico especificando o mesmo caminho de solicitação e parâmetros descritos acima.

Isso permite que agentes de codificação de IA orquestrem chamadas ao endpoint de Geolocalização dentro do seu fluxo de trabalho de desenvolvimento, reutilizando a mesma chave de API.

Lista de verificação de solução de problemas

Erros 401/403: Verifique se você se inscreveu na página da API de Rastreamento Geográfico e está enviando Authorization: Bearer YOUR_API_KEY.
Campos inesperados: Nem todas as propriedades são garantidas. Proteja-se contra nulos ou strings vazias, especialmente para zip, areaCode, dmaCode, languageCode.
Tratamento de resposta: Verifique data["status"] == "success" antes de consumir campos.
Taxa de transferência: Adicione cache por IP e lógica de retrocesso/repetição para problemas de rede transitórios. Monitore seu uso de assinatura para evitar atingir a cota.

Referência rápida

Marketplace: zylalabs.com
Página da API de Rastreamento Geográfico: API de Rastreamento Geográfico
Autenticação: Authorization: Bearer YOUR_API_KEY
Endpoint (GET): https://zylalabs.com/api/2556/geo-tracking-api/6048/geolocation?ip=YOUR_IP
Acesso à primeira API: teste de 7 dias ou 50 solicitações (sem plano gratuito). Veja a página da API para detalhes.

FAQ

Como eu me autentico?
Envie Authorization: Bearer YOUR_API_KEY com cada solicitação. Obtenha sua chave após se inscrever na página da API.

Qual é o endpoint exato para geolocalização de IP?
GET https://zylalabs.com/api/2556/geo-tracking-api/6048/geolocation com o parâmetro de consulta ip obrigatório.

Quais campos indicam tráfego arriscado?
Use o objeto de segurança: is_proxy, is_vpn, is_tor, is_tor_exit e threat_level. Combine esses com suas próprias regras de risco antes da aplicação.

Quais unidades e formatos devo esperar?
lat/lon são graus decimais; timezone é uma string IANA (por exemplo, America/La_Paz). Alguns campos textuais podem estar vazios ou nulos—verifique antes do uso.

Há um plano gratuito?
Não há plano gratuito. Para sua primeira API no Zyla, você pode começar com um teste de 7 dias ou 50 solicitações. Veja a página da API para opções atuais.

Pronto para integrar? Crie sua conta, inscreva-se na API de Rastreamento Geográfico e obtenha sua chave de API agora: Registrar.