{
"isBogon": [
{
"ip": "0.0.0.0",
"expect": true,
"why": "this network"
},
{
"ip": "10.0.0.1",
"expect": true,
"why": "RFC 1918"
},
{
"ip": "100.64.0.1",
"expect": true,
"why": "carrier-grade NAT"
},
{
"ip": "127.0.0.1",
"expect": true,
"why": "loopback"
},
{
"ip": "169.254.1.1",
"expect": true,
"why": "link-local"
},
{
"ip": "172.16.5.4",
"expect": true,
"why": "RFC 1918"
},
{
"ip": "192.0.2.1",
"expect": true,
"why": "documentation"
},
{
"ip": "192.168.1.1",
"expect": true,
"why": "RFC 1918"
},
{
"ip": "198.18.0.1",
"expect": true,
"why": "benchmarking"
},
{
"ip": "203.0.113.9",
"expect": true,
"why": "documentation"
},
{
"ip": "224.0.0.1",
"expect": true,
"why": "multicast"
},
{
"ip": "255.255.255.255",
"expect": true,
"why": "broadcast"
},
{
"ip": "1.1.1.1",
"expect": false,
"why": "ordinary public address"
},
{
"ip": "8.8.8.8",
"expect": false,
"why": "ordinary public address"
},
{
"ip": "172.32.0.1",
"expect": false,
"why": "just outside 172.16.0.0/12"
},
{
"ip": "100.128.0.1",
"expect": false,
"why": "just outside 100.64.0.0/10"
},
{
"ip": "::1",
"expect": true,
"why": "v6 loopback"
},
{
"ip": "fe80::1",
"expect": true,
"why": "v6 link-local"
},
{
"ip": "fc00::1",
"expect": true,
"why": "v6 unique local"
},
{
"ip": "2001:db8::1",
"expect": true,
"why": "v6 documentation"
},
{
"ip": "ff02::1",
"expect": true,
"why": "v6 multicast"
},
{
"ip": "2002:a00::1",
"expect": true,
"why": "6to4 wrapping 10.0.0.0/8"
},
{
"ip": "2002:7f00::1",
"expect": true,
"why": "6to4 wrapping 127.0.0.0/8"
},
{
"ip": "2001:0:a00::1",
"expect": true,
"why": "teredo wrapping 10.0.0.0/8"
},
{
"ip": "2606:4700:4700::1111",
"expect": false,
"why": "ordinary public v6"
},
{
"ip": "2400:cb00::1",
"expect": false,
"why": "ordinary public v6"
},
{
"ip": "fdff:ffff:ffff:ffff:ffff:ffff:ffff:ffff",
"expect": true,
"why": "last address inside fc00::/7; pins the /7 mask width"
},
{
"ip": "fe00::",
"expect": false,
"why": "first address past fc00::/7; a mask one bit too wide claims it"
},
{
"ip": "2001:db8:ffff:ffff:ffff:ffff:ffff:ffff",
"expect": true,
"why": "last address inside 2001:db8::/32; pins the /32 mask width"
},
{
"ip": "2001:db9::",
"expect": false,
"why": "first address past 2001:db8::/32; a mask one bit too wide claims it"
},
{
"ip": "2002:a9fe:ffff:ffff:ffff:ffff:ffff:ffff",
"expect": true,
"why": "last address inside 2002:a9fe::/32; pins the /32 mask width"
},
{
"ip": "2002:a9ff::",
"expect": false,
"why": "first address past 2002:a9fe::/32; a mask one bit too wide claims it"
},
{
"ip": "2001:0:c000:2ff:ffff:ffff:ffff:ffff",
"expect": true,
"why": "last address inside 2001:0:c000:200::/56; pins the /56 mask width"
},
{
"ip": "2001:0:c000:300::",
"expect": false,
"why": "first address past 2001:0:c000:200::/56; a mask one bit too wide claims it"
},
{
"ip": "100::ffff:ffff:ffff:ffff",
"expect": true,
"why": "last address inside 100::/64; pins the /64 mask width"
},
{
"ip": "100:0:0:1::",
"expect": false,
"why": "first address past 100::/64; a mask one bit too wide claims it"
},
{
"ip": "10.255.255.255",
"expect": true,
"why": "last address inside 10.0.0.0/8; pins the /8 mask width"
},
{
"ip": "11.0.0.0",
"expect": false,
"why": "first address past 10.0.0.0/8; a mask one bit too wide claims it"
},
{
"ip": "100.127.255.255",
"expect": true,
"why": "last address inside 100.64.0.0/10; pins the /10 mask width"
},
{
"ip": "100.128.0.0",
"expect": false,
"why": "first address past 100.64.0.0/10; a mask one bit too wide claims it"
},
{
"ip": "172.31.255.255",
"expect": true,
"why": "last address inside 172.16.0.0/12; pins the /12 mask width"
},
{
"ip": "172.32.0.0",
"expect": false,
"why": "first address past 172.16.0.0/12; a mask one bit too wide claims it"
},
{
"ip": "198.19.255.255",
"expect": true,
"why": "last address inside 198.18.0.0/15; pins the /15 mask width"
},
{
"ip": "198.20.0.0",
"expect": false,
"why": "first address past 198.18.0.0/15; a mask one bit too wide claims it"
},
{
"ip": "192.0.2.255",
"expect": true,
"why": "last address inside 192.0.2.0/24; pins the /24 mask width"
},
{
"ip": "192.0.3.0",
"expect": false,
"why": "first address past 192.0.2.0/24; a mask one bit too wide claims it"
}
],
"bogonResponse": {
"why": "A bogon is answered locally in the full max shape. Every flag is present and false, every detail object is present and empty, and is_bogon marks it as computed rather than served.",
"flagsFalse": [
"is_vpn",
"is_hosting",
"is_relay",
"is_tor",
"is_cdn",
"is_resproxy",
"is_dcproxy",
"is_mobproxy"
],
"emptyObjects": [
"vpn",
"hosting",
"relay",
"tor",
"cdn",
"resproxy",
"dcproxy",
"mobproxy"
]
},
"lookup": [
{
"name": "free-not-vpn",
"why": "The free shape. Every tier-gated member is absent, which means not-in-your-plan and must not read as false.",
"status": 200,
"body": {
"ip": "1.1.1.1",
"is_vpn": false
},
"expect": {
"ip": "1.1.1.1",
"isBogon": false,
"present": {
"is_vpn": false
},
"absent": [
"is_hosting",
"is_relay",
"is_tor",
"is_cdn",
"is_resproxy",
"is_dcproxy",
"is_mobproxy",
"vpn",
"hosting",
"relay",
"tor",
"cdn",
"resproxy",
"dcproxy",
"mobproxy"
]
}
},
{
"name": "starter-vpn-hit",
"why": "Starter buys the vpn object and the four classification FLAGS, but none of their detail objects.",
"status": 200,
"body": {
"ip": "45.83.91.1",
"is_vpn": true,
"is_hosting": true,
"is_relay": false,
"is_tor": false,
"is_cdn": false,
"vpn": {
"provider": "mullvad",
"last_seen": "2026-09-02"
}
},
"expect": {
"ip": "45.83.91.1",
"isBogon": false,
"present": {
"is_vpn": true,
"is_hosting": true,
"is_relay": false
},
"absent": [
"is_resproxy",
"is_dcproxy",
"is_mobproxy",
"hosting",
"relay",
"tor",
"cdn",
"resproxy",
"dcproxy",
"mobproxy"
],
"vpn": {
"provider": "mullvad",
"last_seen": "2026-09-02"
}
}
},
{
"name": "scale-empty-object-means-flag-false",
"why": "An empty detail object beside a false flag means not-found. It must not be confused with an absent member.",
"status": 200,
"body": {
"ip": "8.8.8.8",
"is_vpn": false,
"is_hosting": true,
"is_relay": false,
"is_tor": false,
"is_cdn": false,
"vpn": {},
"hosting": {
"provider": "Google",
"confidence": "high",
"last_seen": "2026-09-02"
},
"relay": {},
"tor": {},
"cdn": {}
},
"expect": {
"ip": "8.8.8.8",
"isBogon": false,
"present": {
"is_vpn": false,
"is_hosting": true,
"is_tor": false
},
"absent": [
"is_resproxy",
"is_dcproxy",
"is_mobproxy",
"resproxy",
"dcproxy",
"mobproxy"
],
"emptyPresent": [
"vpn",
"relay",
"tor",
"cdn"
],
"hosting": {
"provider": "Google",
"confidence": "high",
"last_seen": "2026-09-02"
}
}
},
{
"name": "max-full-shape",
"why": "Max adds confidence and method on vpn, plus the three proxy families.",
"status": 200,
"body": {
"ip": "45.83.91.1",
"is_vpn": true,
"is_hosting": true,
"is_relay": false,
"is_tor": false,
"is_cdn": false,
"is_resproxy": false,
"is_dcproxy": true,
"is_mobproxy": false,
"vpn": {
"provider": "mullvad",
"last_seen": "2026-09-02",
"confidence": "high",
"method": "openvpn_cert"
},
"hosting": {
"provider": "M247",
"confidence": "high",
"last_seen": "2026-09-02"
},
"relay": {},
"tor": {},
"cdn": {},
"resproxy": {},
"dcproxy": {
"provider": "brightdata",
"first_seen": "2026-06-14",
"last_seen": "2026-09-02",
"hits": 42,
"hits_days_pct": 63,
"providers_num": 2
},
"mobproxy": {}
},
"expect": {
"ip": "45.83.91.1",
"isBogon": false,
"present": {
"is_vpn": true,
"is_dcproxy": true,
"is_resproxy": false
},
"absent": [],
"vpn": {
"provider": "mullvad",
"last_seen": "2026-09-02",
"confidence": "high",
"method": "openvpn_cert"
},
"dcproxy": {
"provider": "brightdata",
"first_seen": "2026-06-14",
"last_seen": "2026-09-02",
"hits": 42,
"hits_days_pct": 63,
"providers_num": 2
}
}
},
{
"name": "unattributed-range-keeps-empty-provider",
"why": "A populated object always carries every key. An unattributed range has an empty provider string, never a missing one.",
"status": 200,
"body": {
"ip": "185.199.1.1",
"is_vpn": true,
"vpn": {
"provider": "",
"last_seen": "2026-08-30"
}
},
"expect": {
"ip": "185.199.1.1",
"isBogon": false,
"present": {
"is_vpn": true
},
"vpn": {
"provider": "",
"last_seen": "2026-08-30"
}
}
},
{
"name": "max-nothing-found",
"why": "A served all-negative Max answer. This is the only case that pins EVERY tier-gated flag as present-and-false, so a per-field slip that maps on truthiness rather than presence cannot hide behind the members other cases happen to set true.",
"status": 200,
"body": {
"ip": "8.8.4.4",
"is_vpn": false,
"is_hosting": false,
"is_relay": false,
"is_tor": false,
"is_cdn": false,
"is_resproxy": false,
"is_dcproxy": false,
"is_mobproxy": false,
"vpn": {},
"hosting": {},
"relay": {},
"tor": {},
"cdn": {},
"resproxy": {},
"dcproxy": {},
"mobproxy": {}
},
"expect": {
"ip": "8.8.4.4",
"isBogon": false,
"present": {
"is_vpn": false,
"is_hosting": false,
"is_relay": false,
"is_tor": false,
"is_cdn": false,
"is_resproxy": false,
"is_dcproxy": false,
"is_mobproxy": false
},
"absent": [],
"emptyPresent": [
"vpn",
"hosting",
"relay",
"tor",
"cdn",
"resproxy",
"dcproxy",
"mobproxy"
]
}
}
],
"errors": [
{
"name": "invalid-ip",
"status": 400,
"headers": {},
"body": {
"error": "not a valid IP address"
},
"expect": {
"kind": "bad_request",
"retryable": false,
"message": "not a valid IP address"
}
},
{
"name": "invalid-key",
"status": 401,
"headers": {},
"body": {
"error": "invalid API key"
},
"expect": {
"kind": "unauthorized",
"retryable": false,
"message": "invalid API key"
}
},
{
"name": "cidr-restricted",
"status": 403,
"headers": {},
"body": {
"error": "source address not allowed for this API key"
},
"expect": {
"kind": "forbidden",
"retryable": false
}
},
{
"name": "not-found-is-not-retryable",
"why": "A 404 is a CLIENT error. Falling through to the server_error default makes it retryable, so a bad dataset id is retried before it fails. Only 5xx and transport failures are retryable.",
"status": 404,
"headers": {},
"body": {
"rc": "NOT_FOUND"
},
"expect": {
"kind": "bad_request",
"retryable": false
}
},
{
"name": "rate-limited-is-retryable",
"why": "Retry-After present. This is the API protecting itself and retrying WILL succeed.",
"status": 429,
"headers": {
"Retry-After": "1"
},
"body": {
"error": "rate limit exceeded"
},
"expect": {
"kind": "rate_limited",
"retryable": true,
"retryAfterSeconds": 1
}
},
{
"name": "keyless-daily-quota-is-not-retryable",
"why": "No Retry-After. The keyless daily allowance is spent and retrying will not help.",
"status": 429,
"headers": {},
"body": {
"error": "daily limit for unauthenticated requests exceeded; use an API key"
},
"expect": {
"kind": "quota_exceeded",
"retryable": false
}
},
{
"name": "plan-quota-is-not-retryable",
"status": 429,
"headers": {},
"body": {
"error": "request allowance exceeded; raise or remove your overage limit"
},
"expect": {
"kind": "quota_exceeded",
"retryable": false
}
},
{
"name": "server-error-is-retryable",
"status": 500,
"headers": {},
"body": {
"error": "lookup failed"
},
"expect": {
"kind": "server_error",
"retryable": true
}
}
],
"batch": [
{
"name": "dedup-bogon-and-order-free-keying",
"why": "Duplicates collapse to one request, bogons never reach the network, and the result is keyed by IP so input order stops mattering.",
"input": [
"1.1.1.1",
"8.8.8.8",
"1.1.1.1",
"10.0.0.1",
"192.168.1.1"
],
"expect": {
"keys": [
"1.1.1.1",
"8.8.8.8",
"10.0.0.1",
"192.168.1.1"
],
"httpRequests": 2,
"bogonKeys": [
"10.0.0.1",
"192.168.1.1"
]
}
},
{
"name": "partial-failure-does-not-fail-the-batch",
"why": "One address erroring must leave the others answered; the failure is carried in that key's value.",
"input": [
"1.1.1.1",
"notanip"
],
"expect": {
"keys": [
"1.1.1.1",
"notanip"
],
"errorKeys": [
"notanip"
]
}
},
{
"name": "cache-hit-issues-no-second-request",
"why": "The second batch over the same address is served entirely from the per-client cache.",
"input": [
"1.1.1.1"
],
"repeat": 2,
"expect": {
"keys": [
"1.1.1.1"
],
"httpRequests": 1
}
}
],
"bogons": {
"v4": [
"0.0.0.0/8",
"10.0.0.0/8",
"100.64.0.0/10",
"127.0.0.0/8",
"169.254.0.0/16",
"172.16.0.0/12",
"192.0.0.0/24",
"192.0.2.0/24",
"192.168.0.0/16",
"198.18.0.0/15",
"198.51.100.0/24",
"203.0.113.0/24",
"224.0.0.0/4",
"240.0.0.0/4",
"255.255.255.255/32"
],
"v6": [
"::/128",
"::1/128",
"::ffff:0:0/96",
"::/96",
"100::/64",
"2001:10::/28",
"2001:db8::/32",
"fc00::/7",
"fe80::/10",
"fec0::/10",
"ff00::/8",
"2002::/24",
"2002:a00::/24",
"2002:7f00::/24",
"2002:a9fe::/32",
"2002:ac10::/28",
"2002:c000::/40",
"2002:c000:200::/40",
"2002:c0a8::/32",
"2002:c612::/31",
"2002:c633:6400::/40",
"2002:cb00:7100::/40",
"2002:e000::/20",
"2002:f000::/20",
"2002:ffff:ffff::/48",
"2001::/40",
"2001:0:a00::/40",
"2001:0:7f00::/40",
"2001:0:a9fe::/48",
"2001:0:ac10::/44",
"2001:0:c000::/56",
"2001:0:c000:200::/56",
"2001:0:c0a8::/48",
"2001:0:c612::/47",
"2001:0:c633:6400::/56",
"2001:0:cb00:7100::/56",
"2001:0:e000::/36",
"2001:0:f000::/36",
"2001:0:ffff:ffff::/64"
]
}
}