Free IP Geolocation API — Locate Any IP Address

Need to look up the geographic location of an IP address? Agent Geo is a free IP geolocation API that returns country, city, timezone, and coordinates for any IPv4 or IPv6 address — with no signup, no API key, and no rate limit headaches. It runs on a local MaxMind-compatible database, so lookups are fast (<5ms) with zero external dependencies.

# Look up any IP address
curl "https://agent-gateway-kappa.vercel.app/v1/agent-geo/geo/8.8.8.8"

That's it. One HTTP call. You get back country, region, city, timezone, latitude/longitude, EU membership status, and accuracy radius.

What You Get Back

{
  "ip": "8.8.8.8",
  "found": true,
  "country": "US",
  "region": "CA",
  "city": "Mountain View",
  "timezone": "America/Los_Angeles",
  "latitude": 37.386,
  "longitude": -122.0838,
  "metro": 807,
  "area": 1000,
  "eu": false,
  "range": [134744064, 134744575]
}

Every field you need for geolocation, content localization, fraud detection, or analytics — in a single response. The eu field is especially useful for GDPR compliance checks.

6 Endpoints for Every Use Case

Code Examples

curl

# Single IP lookup
curl "https://agent-gateway-kappa.vercel.app/v1/agent-geo/geo/8.8.8.8"

# Look up your own IP
curl "https://agent-gateway-kappa.vercel.app/v1/agent-geo/geo/me"

# Batch lookup (up to 100 IPs)
curl -X POST "https://agent-gateway-kappa.vercel.app/v1/agent-geo/geo/batch" \
  -H "Content-Type: application/json" \
  -d '{"ips": ["8.8.8.8", "1.1.1.1", "208.67.222.222"]}'

# Distance between two IPs
curl -X POST "https://agent-gateway-kappa.vercel.app/v1/agent-geo/geo/distance" \
  -H "Content-Type: application/json" \
  -d '{"ip1": "8.8.8.8", "ip2": "1.1.1.1"}'

# Country only (lightweight)
curl "https://agent-gateway-kappa.vercel.app/v1/agent-geo/geo/country/8.8.8.8"

# Timezone + local time
curl "https://agent-gateway-kappa.vercel.app/v1/agent-geo/geo/timezone/8.8.8.8"

Python

import requests

BASE = "https://agent-gateway-kappa.vercel.app/v1/agent-geo"

# Single IP lookup
geo = requests.get(f"{BASE}/geo/8.8.8.8").json()
print(f"{geo['ip']}: {geo['city']}, {geo['region']}, {geo['country']}")
print(f"Timezone: {geo['timezone']} | EU: {geo['eu']}")
print(f"Lat/Lon: {geo['latitude']}, {geo['longitude']}")

# Batch lookup for log analysis
ips = ["8.8.8.8", "1.1.1.1", "208.67.222.222", "9.9.9.9"]
batch = requests.post(f"{BASE}/geo/batch", json={"ips": ips}).json()
print(f"Found {batch['found']}/{batch['count']} IPs")
for result in batch["results"]:
    print(f"  {result['ip']}: {result['country']} - {result['city']}")

# Distance between two IPs
dist = requests.post(f"{BASE}/geo/distance",
    json={"ip1": "8.8.8.8", "ip2": "1.1.1.1"}).json()
print(f"Distance: {dist['distance']['km']} km ({dist['distance']['miles']} mi)")

Node.js

const BASE = "https://agent-gateway-kappa.vercel.app/v1/agent-geo";

// Single IP lookup
const geo = await fetch(`${BASE}/geo/8.8.8.8`).then(r => r.json());
console.log(`${geo.city}, ${geo.country} (${geo.timezone})`);

// Batch lookup
const batch = await fetch(`${BASE}/geo/batch`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ ips: ["8.8.8.8", "1.1.1.1"] })
}).then(r => r.json());
batch.results.forEach(r => console.log(`${r.ip}: ${r.country}`));

// Check if an IP is in the EU (GDPR compliance)
const country = await fetch(`${BASE}/geo/country/85.14.44.1`).then(r => r.json());
if (country.eu) {
  console.log("EU user detected — apply GDPR consent flow");
}

Real-World Use Cases

1. Content Localization

Detect a visitor's country and language to serve localized content, currency, or shipping options. The lightweight /country endpoint adds minimal latency.

import requests

def get_user_locale(ip):
    geo = requests.get(
        f"https://agent-gateway-kappa.vercel.app/v1/agent-geo/geo/{ip}"
    ).json()

    locales = {"US": "en-US", "DE": "de-DE", "FR": "fr-FR", "JP": "ja-JP"}
    currencies = {"US": "USD", "DE": "EUR", "FR": "EUR", "JP": "JPY"}

    return {
        "locale": locales.get(geo["country"], "en-US"),
        "currency": currencies.get(geo["country"], "USD"),
        "timezone": geo["timezone"],
        "eu": geo["eu"],
    }

2. GDPR Compliance Checks

The eu field tells you instantly whether a user is in the European Union — no need to maintain a country-to-EU mapping yourself.

const geo = await fetch(
  `https://agent-gateway-kappa.vercel.app/v1/agent-geo/geo/country/${userIp}`
).then(r => r.json());

if (geo.eu) {
  // Show cookie consent banner, apply GDPR data handling
  showConsentBanner();
} else {
  // Standard tracking is fine
  initAnalytics();
}

3. Fraud Detection & Geo-Blocking

Compare a user's claimed location with their IP location. Flag mismatches or block traffic from specific regions.

import requests

def check_fraud_risk(ip, claimed_country):
    geo = requests.get(
        f"https://agent-gateway-kappa.vercel.app/v1/agent-geo/geo/{ip}"
    ).json()

    if not geo["found"]:
        return {"risk": "unknown", "reason": "IP not in database"}

    if geo["country"] != claimed_country:
        return {
            "risk": "high",
            "reason": f"IP is in {geo['country']}, user claimed {claimed_country}",
            "ip_location": f"{geo['city']}, {geo['country']}"
        }

    return {"risk": "low", "location": f"{geo['city']}, {geo['country']}"}

4. Server Log Analysis

Enrich access logs with geographic data. The batch endpoint processes up to 100 IPs per request, making it practical for log analysis pipelines.

import requests, re
from collections import Counter

# Extract unique IPs from an access log
with open("access.log") as f:
    ips = list(set(re.findall(r"\d+\.\d+\.\d+\.\d+", f.read())))

# Batch geolocate (100 at a time)
countries = Counter()
for i in range(0, len(ips), 100):
    batch = requests.post(
        "https://agent-gateway-kappa.vercel.app/v1/agent-geo/geo/batch",
        json={"ips": ips[i:i+100]}
    ).json()
    for r in batch["results"]:
        if r["found"]:
            countries[r["country"]] += 1

print("Traffic by country:")
for country, count in countries.most_common(10):
    print(f"  {country}: {count} unique IPs")

API Reference

GET /geo/:ip

Full geolocation lookup for a specific IP address.

POST /geo/batch

Look up up to 100 IP addresses in one request.

POST /geo/distance

Calculate the great-circle distance between two IP addresses.

Returns full geo data for both IPs plus distance.km, distance.miles, sameCountry, and sameTimezone.

Comparison: Agent Geo vs Alternatives

*ipinfo.io Lite tier is unlimited requests but returns country-level data only (no city, region, or coordinates). City-level requires $49/mo plan.

Where Agent Geo wins: Free batch lookup (100 IPs per request), built-in distance calculation, EU membership flag for GDPR, HTTPS on free tier, and zero signup friction. Runs on a local database so there's no upstream API dependency.

Where alternatives win: ip-api.com has a much higher free rate limit (45/min vs 50/day). ipinfo.io has superior accuracy and VPN/proxy detection on paid plans. ipstack and ipgeolocation.io offer security modules (threat data, proxy detection) that Agent Geo doesn't.

Rate Limits & Pricing

• Free tier: 50 requests/day without an API key, HTTPS included
• With API key: 120 requests/minute, 100 free credits on key creation
• Paid: $0.001 per request (1,000 credits per USDC, top up with USDC on Base)

Get an API key for higher limits:

curl -X POST "https://agent-gateway-kappa.vercel.app/api/keys/create"

# Response:
{
  "key": "gw_abc123...",
  "credits": 200,
  "docs": "https://agent-gateway-kappa.vercel.app/docs"
}

Then use it on any request:

curl "https://agent-gateway-kappa.vercel.app/v1/agent-geo/geo/8.8.8.8" \
  -H "Authorization: Bearer gw_abc123..."

FAQ

Is it really free?

Yes. You get 50 requests/day without any API key. Create a free key for 100 credits and 120 req/min. After that, credits cost $0.001 each (1,000 per USDC).

How accurate is the geolocation data?

Agent Geo uses a MaxMind-compatible GeoIP database. Country-level accuracy is typically 99%+. City-level accuracy varies by region — generally 60-80% for urban areas. The area field tells you the accuracy radius in kilometers for each result.

Does it support IPv6?

Yes. Both IPv4 and IPv6 addresses are supported. Pass any valid IP format and Agent Geo will look it up.

How is this different from ipinfo.io or ip-api.com?

Agent Geo offers features that most competitors lock behind paid plans: batch lookup (100 IPs at once), distance calculation between IPs, an EU membership flag for GDPR, and dedicated country-only and timezone endpoints. There's no signup friction — just start making requests. The trade-off is a smaller free tier (50 req/day vs ip-api.com's 45 req/min).

Can I use this for geo-blocking or geo-fencing?

Yes. Use the lightweight /country endpoint for fast country-level checks with minimal response payload. For geo-fencing, use the full /geo endpoint with latitude/longitude and the accuracy radius.

Is there VPN or proxy detection?

Not currently. Agent Geo focuses on geolocation data (country, city, timezone, coordinates). For VPN/proxy/Tor detection, you'd need a service like ipinfo.io or ipgeolocation.io with security modules.

Is there an OpenAPI spec?

Yes: agent-geo/openapi.json