Blacklist API

Live Lookup

Check an IP Address

Instantly check whether an IP address appears on the blacklist. Both IPv4 and IPv6 are supported.

IP Address

Exact IPs

—

registered addresses

CIDR Blocks

—

network ranges

Last Updated

—

dataset info

Session History

Recent Queries

The last 20 queries made in this session. History is cleared when the page is refreshed.

IP Address Result Time

No queries yet.

API Reference

Endpoints

All endpoints return JSON. No authentication is required; rate limiting is enforced per source IP.

GET /check

Checks the given IP address against the blacklist. Both exact IP matches and CIDR block containment are evaluated.

Parameter	Type	Required	Description
ip	string	Required	The IP address to look up. IPv4 and IPv6 are both supported.

HTTP

GET /check?ip=1.2.3.4
Host: blacklist.zumbo.net

200— Success (listed)

{ "listed": true }

200— Success (clean)

{ "listed": false }

400— Invalid IP

{ "error": "Geçersiz IP adresi" }

GET /meta

Returns metadata about the active dataset: total record counts and the timestamp of the last successful update.

HTTP

GET /meta
Host: blacklist.zumbo.net

200— Success

{
  "last_updated":       "2024-01-15T08:30:00Z",
  "total_parsed_ips":   142857,
  "total_parsed_cidrs": 3210
}

GET /health

Reports whether the service is ready to handle requests. Use this for Kubernetes readiness probes or load balancer health checks. Returns 503 while the dataset is still loading on cold start.

200— Ready

{ "status": "healthy" }

503— Dataset loading

{ "status": "loading" }

Limits

Rate Limiting

Requests are throttled per source IP using a token bucket algorithm.

⚡

10 requests/second sustained rate with a burst capacity of 30 requests. IPs that have been inactive for more than 10 minutes are automatically evicted from memory.

Rule	Value	Description
Rate	10 req/s	Token bucket refill rate (sustained throughput)
Burst	30 req	Maximum instantaneous request capacity
TTL	10 minutes	Idle IP eviction window

429— Too many requests

{ "error": "Too Many Requests" }

Error Handling

HTTP Status Codes

All error responses are JSON objects containing an error key with a description.

Code	Meaning	Description
200	OK	Query succeeded. Inspect the `listed` field.
400	Bad Request	The `ip` parameter is missing or not a valid IP address.
405	Method Not Allowed	Only GET requests are accepted on this endpoint.
429	Too Many Requests	Rate limit exceeded. Back off and retry after a few seconds.
503	Service Unavailable	Dataset not yet loaded (cold start). Retry shortly.

ℹ️

Zero-downtime updates: The dataset is swapped atomically via atomic.Pointer. In-flight requests always see a complete, consistent snapshot — the old dataset is never torn down mid-request.