Pesquise um endereço IP a partir do seu back-end

Resolva um endereço IP fornecido para dados disponíveis de país, região, cidade e coordenadas aproximadas. A API de pesquisa de IP do Watch-IP aceita entrada IPv4 e IPv6 e devolve um resultado JSON suportado por uma base de dados de geolocalização de IP de terceiros. Utilize uma chave de API secreta no seu servidor, e construa a sua aplicação em torno de correspondências explícitas, registos em falta e campos de localização que podem ser nulos.

Ver planos de pesquisa Discutir o acesso à pesquisa →

Forneça o endereço que pretende resolver

Chame GET /v1/lookup/{ip} com um endereço IP recolhido pela sua aplicação, autenticado com Authorization: Bearer e uma chave secreta. A pesquisa resolve o endereço no URL, em vez da ligação utilizada para fazer o pedido, o que a torna adequada para fluxos de trabalho de back-end que já contêm endereços IP, incluindo relatórios e enriquecimento regional. Verifique como a sua aplicação obtém o IP de um utilizador final antes de depender de cabeçalhos reencaminhados; confie apenas no percurso de proxy que controla. Para uma integração comum de visitante de website, o endpoint de geolocalização no navegador oferece um percurso diferente, com uma chave publicável e enriquecimento regional.

Passe de um único endereço para um lote

Se o seu fluxo de trabalho contiver vários endereços IP, o endpoint em lote aceita até 100 num único pedido e devolve resultados na mesma ordem. Utiliza a mesma estrutura de resultado de pesquisa e o mesmo modelo de autenticação com chave secreta no lado do servidor. O agrupamento em lote altera a forma como envia os pedidos — a utilização de pesquisa continua a ser medida por IP, pelo que um lote não é uma única unidade de utilização de pesquisa.

Construa em torno de dados aproximados

Um IP pode representar uma porta de ligação partilhada, uma rede de alojamento, uma saída de VPN, ou uma ligação de operador móvel. Os registos de localização podem estar incompletos ou diferir entre fornecedores de dados. Utilize a pesquisa como contexto para o endereço que forneceu, não como prova da residência ou identidade de uma pessoa.

Campos de resposta

ip: O endereço de entrada associado a este resultado.
found: Se foi encontrado um registo correspondente na base de dados. False também pode significar que a base de dados está indisponível ou não foi carregada — não prova que o endereço não tem dados de localização.
country, continent: Códigos de país e continente, quando disponíveis.
region: Um identificador de subdivisão do mapeamento atual, nem sempre um nome de região completo.
city, latitude, longitude: Cidade e coordenadas aproximadas, quando disponíveis na base de dados de origem.
postalCode, timezone: Não preenchidos pela atual base de dados de origem — sempre nulos.

Faça um pedido do lado do servidor

cURL — GET /v1/lookup/{ip}

curl --fail-with-body \
  'https://api.watch-ip.com/v1/lookup/8.8.8.8' \
  --header "Authorization: Bearer ${WATCH_IP_SECRET_KEY}"

Defina primeiro WATCH_IP_SECRET_KEY no ambiente do seu servidor. 8.8.8.8 é um endereço de exemplo sintaticamente válido; este excerto não promete um país, cidade, ou resposta específicos para ele.

Perguntas frequentes

Posso utilizar esta API para pesquisar o endereço IP de outra pessoa?

O endpoint aceita um endereço IP fornecido e devolve dados de localização de base de dados disponíveis, não o nome, endereço exato, ou identidade de uma pessoa. Utilize apenas dados que esteja autorizado a processar.

Suporta IPv6?

O endpoint valida entrada IPv4 e IPv6. Um endereço válido ainda pode não ter um registo na base de dados ou alguns campos de localização.

A pesquisa inclui fuso horário, ASN, ou deteção de VPN?

Não. A atual resposta de pesquisa não inclui ASN nem indicadores de segurança, e a sua fonte de base de dados de terceiros não preenche os campos de fuso horário ou código postal. Reveja separadamente a geolocalização do visitante se o seu modelo de cliente em ligação se adequar à sua aplicação.

Posso enviar o pedido a partir de JavaScript no navegador?

Não — nunca exponha uma chave secreta de pesquisa em código do navegador. Faça as chamadas de pesquisa a partir do seu back-end, e utilize o endpoint de visitante com uma chave publicável para geolocalização direta no navegador.

Isto está incluído numa chave de visitante gratuita?

Não. A pesquisa utiliza uma chave secreta e uma família de planos separadas; o plano gratuito de visitante não concede acesso à pesquisa no lado do servidor.

O que significa found: false?

A pesquisa não devolveu um registo correspondente. Na implementação atual, isto também pode acontecer quando a base de dados está indisponível ou não foi carregada, por isso mostre "Localização indisponível" e mantenha este resultado separado de entradas inválidas, falhas de autenticação e erros de limite de taxa.