Geo-Location Guide

Core Endpoints

• GET /v1/location/ip/{ip}: Get geolocation and ASN data for a single IP.
• GET /v1/location/network/{*network}: Get data for an entire network CIDR range.
• POST /v1/location/ips/bulk: Retrieve data for up to 1000 IPs in a single request.
• GET /v1/location/search: Find all IPs matching specific fields like city or ISP.

Example 1: Geo-locting a Single IP

‍

This is the fastest and most direct way to get location data.‍

‍

curl -H "Authorization: Bearer YOUR_API_KEY" \     
"https://api.whisper.security/v1/location/ip/8.8.8.8"

‍

‍


Understanding the Response

‍

The response is a lean JSON object focused purely on location and network identity.

• ip: The IP that was queried ("8.8.8.8").

• country: isoCode ("US") and name ("United States").

• city: name ("mountain view").

• location: latitude (37.4223) and longitude (-122.085).

• isp: name ("google llc"), organization ("level 3"), and asn (15169).

• traits: Key classification, such as userType ("hosting").

Example 2: Geolocting a Network (CIDR)

‍

You can also get the primary location data for an entire network block.

‍

‍curl -H "Authorization: Bearer YOUR_API_KEY" \
"https://api.whisper.security/v1/location/network/8.8.8.0%2F24"

‍

Understanding the Response

‍

The response is nearly identical to the single IP lookup but includes the queried network range and represents the data for the block as a whole.

• network: "8.8.8.0/24"

• cidr: "8.8.8.0/24"

• (All other fields like country, city, isp are also present ).

Advanced Usage

‍

1. Bulk IP Geolocation

‍

To enrich logs or a large list of IPs, use the bulk endpoint. It accepts a JSON array of up to 1000 IPs.

‍

POST /v1/location/ips/bulk

‍

Request Body:

‍

[
  "8.8.8.8",
  "1.1.1.1",
  "208.67.222.222"
]

‍

Response:The API will return a JSON array containing the full geolocation object for each IP, in the same order as the request.

‍

2. Searching the Geolocation Database

‍

For threat hunting and infrastructure discovery, you can search for all IPs that match a specific field.

‍

Query Examples:

• Find IPs in a city: GET /v1/location/search?field=city&value=London
• Find IPs for an ASN: GET /v1/location/search?field=asn&value=15169
• Find IPs for an ISP: GET /v1/location/search?field=isp_name&value=Google

The test data for field=city&value=San%20Francisco shows a 200 OK response with totalHits: 0 and an empty results array, which is the expected format when no results are found.

‍

API Reference

‍

For full details, see the Location endpoints in the API Reference:

• Get IP Geolocation: GET /v1/location/ip/{ip}
• Get Network Geolocation: GET /v1/location/network/{*network}
• Bulk IP Geolocation: POST /v1/location/ips/bulk
• Search Geolocation: GET /v1/location/search

‍

‍

‍

‍

‍

‍