IP Geolocation API Docs

Quickstart

• Base URL — https://api.networkdatalabs.com
• Auth — send your key as Authorization: Bearer YOUR_API_KEY. For quick tests you can also pass ?api_key=YOUR_API_KEY; prefer the header in production. Missing or unknown keys return 401 UNAUTHORIZED.
• Format — JSON over HTTPS. All endpoints are versioned under /v0.
• Postman — Run in Postman to try every endpoint from the public collection. Set the apiKey environment variable to your own API key first.

Look up a single IP:

$ curl -s https://api.networkdatalabs.com/v0/ip/8.8.8.8 \
    -H "Authorization: Bearer YOUR_API_KEY"

{
  "ip": "8.8.8.8",
  "location": {
    "continent_code": "NA",
    "country_code": "US",
    "country": "United States",
    "is_eu": false,
    "region": "California",
    "region_code": "CA",
    "city": "Mountain View",
    "postal": null,
    "latitude": 37.422,
    "longitude": -122.085,
    "timezone": "America/Los_Angeles",
    "accuracy_radius_km": 50.0,
    "confidence": "medium"
  },
  "network": {
    "asn": 15169,
    "as_org": "Google LLC",
    "isp": "Google LLC",
    "organization": "Google LLC",
    "network": "8.8.8.0/24"
  },
  "traits": {
    "is_anycast": true,
    "is_hosting": true,
    "is_mobile": false,
    "is_satellite": false,
    "is_bogon": false,
    "is_proxy": false,
    "is_vpn": false,
    "is_tor": false,
    "is_relay": false
  }
}

Note the radius: 8.8.8.8 is anycast, so it is answered from many places at once; the response tells you how precise the location is with accuracy_radius_km: 50.0 and confidence: "medium".

Endpoints

• GET /v0/ip/{ip} — full lookup for one IPv4 or IPv6 address: location, network and traits. Malformed IPs return 400 INVALID_IP.
• GET /v0/ip — the same lookup for your own public IP (the address the request comes from). Counts toward the account quota like any other lookup.
• GET /v0/asn/{asn} — Autonomous System detail (15169 or AS15169): name, org, domain, type (hosting, isp, education, government, business, unknown), country_code, rir and prefixes_sample. Unknown ASNs return 404 NOT_FOUND.
• POST /v0/bulk — look up to 100 IPs in one request with body {"ips": [...]}. Paid plans only (Starter and up); Free keys get 403 PLAN_REQUIRED before the body is read. Returns results keyed by IP; per-IP failures go in errors, so one bad IP doesn’t fail the batch.
• GET /v0/me — your apparent IP plus plan, current-period usage (used, limit, remaining, reset_at) and plan limits (per-second, quota, key cap, bulk). Handy for validating a key.

$ curl -s https://api.networkdatalabs.com/v0/bulk \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"ips": ["8.8.8.8", "1.1.1.1", "9.9.9.9"]}'

{
  "results": { "8.8.8.8": { … }, "1.1.1.1": { … }, "9.9.9.9": { … } },
  "errors": {}
}

Response fields

• location — continent_code, country_code (ISO 3166-1 alpha-2), country, is_eu, region, region_code, city, postal, latitude, longitude, timezone (IANA). For country-only use cases, see the IP to country API.
• location.accuracy_radius_km — estimated accuracy radius in kilometers, always present when geo is returned. A wide radius (e.g. 1000) means the city is a best-effort guess.
• location.confidence — qualitative confidence in the geo estimate: high | medium | low | unknown.
• network — asn, as_org, isp, organization, network (containing CIDR prefix) and rir (ARIN, LACNIC, RIPE, APNIC, AFRINIC).
• traits — booleans for risk and fraud checks. What each one detects: is_tor (the IP is a current Tor exit node; exit nodes only, not guard/middle relays or bridges), is_relay (the IP is a privacy relay egress), is_vpn (the IP belongs to a known VPN network; it catches major commercial VPN providers; whole networks of VPN-heavy hosting providers are flagged, so other servers there are flagged too; privacy relay IPs are is_relay, not is_vpn; overview and limits on the VPN detection API page), is_hosting (hosting/datacenter detection), is_satellite (satellite internet), is_mobile (mobile carrier networks; an estimate that may also flag some business/static or fixed-wireless blocks from those carriers), is_bogon (private / reserved ranges) and is_anycast (true only for a fixed set of well-known anycast DNS resolvers such as 8.8.8.8 and 1.1.1.1).

Errors and rate limits

Errors use one shape: {"error": {"code": "…", "message": "…"}}, with codes such as INVALID_IP, UNAUTHORIZED, PLAN_REQUIRED, KEY_RESTRICTED, NOT_FOUND, RATE_LIMITED and QUOTA_EXCEEDED. Exceeding the rate limit or the account quota returns 429 with limit, reset_at, plan (current plan), and upgrade_url (https://networkdatalabs.com/pricing) on the error object. suggested_plan is the next tier (omitted on Scale). The same plan and upgrade_url fields are on 403 PLAN_REQUIRED (bulk and other paid-only features). 429 responses also include Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset (plus X-RateLimit-Limit-Month / X-RateLimit-Remaining-Month on Free and paid calendar-month plans). Free is 1 request/second with no burst, and a hard 1,000 requests per UTC calendar month (no buffer; resets on the 1st). Paid plans are a strict per-second window with no burst (Starter 10/s, Growth 25/s, Scale 50/s) and allow a 10% buffer over the monthly quota, then QUOTA_EXCEEDED. Quotas reset at the start of the next UTC calendar month. Counters are per account (all keys combined) and live in memory on the API machine (a single Fly VM today), refreshed from stored usage every few minutes. A bulk call counts as 1 request toward the per-second limit and as N (one per IP) toward the quota. If a key has origin or IP allowlists and the request matches neither, the API returns 403 KEY_RESTRICTED (Origin header, else Referer host; client IP from Fly-Client-IP on Fly, else the socket peer — never X-Forwarded-For). After a plan downgrade, extra keys stay valid until revoked and existing allowlists keep being enforced (Free can only clear them).

Free tier and API keys

The Free plan includes 1 request/second and 1,000 requests per UTC calendar month. Free is for personal and non-commercial use; commercial use requires a paid plan. Risk flags (is_hosting, is_proxy, is_vpn, is_tor, is_relay) are omitted on Free keys; bulk lookup is paid-only. See pricing for paid tiers. Sign up below to create a free account and get your API key instantly after email confirmation.