Busca direcciones IP en lotes
Envía una lista de direcciones IP a un solo endpoint y recibe una lista coincidente de resultados de ubicación. La API de búsqueda masiva de IP de Watch-IP acepta hasta 100 direcciones IPv4 e IPv6 por solicitud para flujos de trabajo de enriquecimiento de backend. Mantén tu clave secreta en el servidor, procesa la respuesta en el orden de entrada, y maneja los registros faltantes sin perder la conexión con tus datos originales.
Una solicitud, hasta 100 direcciones
Usa POST /v1/lookup con un objeto JSON que contenga un arreglo ips. Cada lote aceptado contiene al menos una dirección y como máximo 100, y puedes combinar direcciones IPv4 e IPv6 válidas en la misma lista. La respuesta envuelve los resultados de búsqueda ordenados en un arreglo results; cada resultado usa la misma forma que la búsqueda de una sola IP, incluidos found y los campos de ubicación nulos.
Mantén los resultados alineados con tus registros de origen
Para un lote exitoso, la API devuelve un resultado por cada dirección de entrada en el mismo orden. Mantén tus propios identificadores de registro junto con la lista enviada para poder unir los resultados con tus filas originales. Cuando no se encuentra un registro, conserva la fila y marca la ubicación como no disponible; cuando solo falta un campo, conserva el resto del resultado. No reemplaces las coordenadas faltantes con cero, lo cual convertiría una ausencia de datos en una ubicación de mapa engañosa.
Valida antes de enviar
Una lista vacía, una lista con más de 100 direcciones, o una IP mal formada produce un error de solicitud — una dirección mal formada rechaza todo el lote en lugar de producir un resultado de éxito parcial para las demás entradas. Valida la entrada y divide las listas más largas en lotes antes de enviarlas, y lleva un registro de los lotes completados para que un reintento no repita accidentalmente todo un trabajo.
Entiende qué cambia el procesamiento por lotes
El procesamiento por lotes reduce la cantidad de solicitudes HTTP necesarias para enviar una lista. No cambia la fuente de datos, no agrega campos de seguridad, ni convierte 100 búsquedas en una sola unidad de uso — el uso de búsqueda se registra por cada IP enviada en solicitudes aceptadas, así que la elección del plan debe considerar tanto el volumen total de búsqueda como la tasa de solicitudes. El límite de tasa por minuto cuenta llamadas HTTP, no elementos: un lote de hasta 100 IP o direcciones de correo cuenta como una sola solicitud, mientras que cada elemento sigue contando por separado en el límite mensual de solicitudes.
Forma de la solicitud y la respuesta
- ips
- Cuerpo de la solicitud: un arreglo JSON de 1 a 100 direcciones IPv4 o IPv6.
- results
- Respuesta: un arreglo ordenado con una entrada por cada dirección de entrada, en el mismo orden enviado.
- results[].found, results[].country, ...
- Cada resultado usa la misma forma y nulabilidad que la respuesta de búsqueda de una sola IP — consulta la página de producto de búsqueda de IP.
Envía una solicitud por lotes
cURL — POST /v1/lookup
curl --fail-with-body \
'https://api.watch-ip.com/v1/lookup' \
--header "Authorization: Bearer ${WATCH_IP_SECRET_KEY}" \
--header 'Content-Type: application/json' \
--data '{"ips":["8.8.8.8","2001:4860:4860::8888"]}'Estas direcciones de demostración no implican valores de ubicación actuales particulares. Configura WATCH_IP_SECRET_KEY en el entorno de tu servidor primero.
Preguntas frecuentes
¿Cuántas direcciones IP caben en un lote?
El máximo actual es 100. Divide las listas más largas en solicitudes que contengan cada una entre 1 y 100 direcciones.
¿Puede un lote contener tanto IPv4 como IPv6?
Sí. Cada dirección debe ser válida, y la cobertura de la base de datos puede diferir según la dirección.
¿Se devuelven los resultados en el orden de entrada?
Sí. Un lote aceptado exitosamente devuelve un resultado por cada dirección de entrada en el mismo orden.
¿Qué sucede si una IP está mal formada?
Se rechaza toda la solicitud. Valida tu entrada antes de enviarla — este endpoint no ofrece éxito parcial para entradas mal formadas.
¿Se factura un lote como una sola búsqueda?
No. El uso se mide por IP. Revisa los precios actuales de búsqueda y los ejemplos de facturación verificados antes de estimar el costo de un trabajo grande.
¿Puedo subir un archivo CSV?
El endpoint documentado acepta un arreglo JSON de direcciones. Tu aplicación puede leer su propio CSV y enviar lotes; una interfaz de carga de CSV alojada no forma parte de esta API.
¿La búsqueda masiva incluye verificaciones de VPN o Tor?
No. La respuesta masiva actual es el resultado de ubicación de una base de datos de geolocalización de terceros. Los indicadores de seguridad de geolocalización de visitantes son una capacidad separada que no está presente en las respuestas de búsqueda.