Geolocate Any IP Address

The IP Geolocation service resolves any IPv4 or IPv6 address to its geographic location, ISP, and ASN. Use it for fraud detection, content localization, analytics, or compliance checks.

What You'll Learn

  • How to geolocate a well-known IP (Google DNS 8.8.8.8) and read the response
  • How IPv6 lookups work identically to IPv4
  • How to submit bulk lookups for multiple IPs in one request

Prerequisites

Before you start: You need an API key. Follow the Platform Quick Start to get one.

  • curl (or any HTTP client)
  • A valid API key in the X-API-KEY header

Step 1: Lookup Google DNS (8.8.8.8)

Pass the IP as a query parameter. The response includes country, city, coordinates, and ASN details.

bash
curl -X GET "/api/ip-geolocation/lookup?ip=8.8.8.8" \
  -H "X-API-KEY: your-api-key"
python
import requests

resp = requests.get(
    "/api/ip-geolocation/lookup",
    headers={"X-API-KEY": "your-api-key"},
    params={"ip": "8.8.8.8"}
)
data = resp.json()
print(f"{data['data']['country']} / {data['data']['city']}")
Response — 200 OK
{
  "status": "OK",
  "data": {
    "ip": "8.8.8.8",
    "country": "US",
    "countryName": "United States",
    "region": "California",
    "city": "Mountain View",
    "latitude": 37.386,
    "longitude": -122.0838,
    "timezone": "America/Los_Angeles",
    "isp": "Google LLC",
    "asn": "AS15169",
    "asnOrg": "Google LLC"
  }
}

Step 2: IPv6 Address Lookup

IPv6 works the same way. Pass the full address (no URL-encoding needed for brackets).

bash
curl -X GET "/api/ip-geolocation/lookup?ip=2001:4860:4860::8888" \
  -H "X-API-KEY: your-api-key"
Response — 200 OK
{
  "status": "OK",
  "data": {
    "ip": "2001:4860:4860::8888",
    "country": "US",
    "countryName": "United States",
    "region": "California",
    "city": "Mountain View",
    "latitude": 37.386,
    "longitude": -122.0838,
    "timezone": "America/Los_Angeles",
    "isp": "Google LLC",
    "asn": "AS15169",
    "asnOrg": "Google LLC"
  }
}

Step 3: Bulk Lookup

Submit up to 100 IPs at once with the batch endpoint. Each IP is resolved independently.

bash
curl -X POST /api/ip-geolocation/lookup/batch \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: your-api-key" \
  -d '{
    "ips": ["8.8.8.8", "1.1.1.1", "208.67.222.222"]
  }'
Response — 200 OK
{
  "status": "OK",
  "data": {
    "results": [
      { "ip": "8.8.8.8",        "country": "US", "city": "Mountain View", "asn": "AS15169" },
      { "ip": "1.1.1.1",        "country": "AU", "city": "Sydney",        "asn": "AS13335" },
      { "ip": "208.67.222.222", "country": "US", "city": "San Francisco", "asn": "AS36692" }
    ]
  }
}

Integration Tips

  • Fraud detection: Compare the IP country with the billing country. Mismatches are a strong fraud signal.
  • Content localization: Use the country and timezone fields to serve locale-appropriate content.
  • Cache results: IP-to-location mappings rarely change. Cache for 24–72 hours to reduce API calls.
  • GDPR compliance: IP addresses are personal data in the EU. Log only the country/region when you don't need full precision.

Next Steps