cloudflare-json-ips

Python library that resolves Cloudflare-published IP ranges from the authoritative JSON source.

It downloads and parses https://api.cloudflare.com/client/v4/ips, extracts all IPv4 and IPv6 CIDRs, and provides helpers for containment and overlap queries.

Why JSON?

Cloudflare publishes an authoritative machine-readable API response with:

• result.ipv4_cidrs
• result.ipv6_cidrs
• result.etag

This package reads that source directly.

Install

From PyPI

pip install cloudflare-json-ips

Local Development

From the project root:

pip install -e .

Library Usage

from cloudflare_json_ips import CloudflareIPQuery, get_cloudflare_ip_cidrs

result = get_cloudflare_ip_cidrs()
query = CloudflareIPQuery.from_cidrs(result.cidrs)

print(result.etag)
print(query.contains("104.16.0.0/13"))
print(query.collides("104.16.0.0-104.23.255.255"))

result is a ResolutionResult with:

• cidrs: sorted tuple of unique CIDR strings
• etag: source etag from Cloudflare's response
• source_url: JSON URL used
• selected_prefix_count: number of selected IPv4 and IPv6 prefix entries

CloudflareIPQuery supports:

• contains(value): full containment for IP, CIDR, or range string (start-end)
• collides(value): any overlap for IP, CIDR, or range string (start-end)
• Specific methods: contains_ip, contains_cidr, contains_range, collides_ip, collides_cidr, collides_range

Example Script

Run:

python examples/print_cloudflare_ips.py

Flask JSON Server Example

Run:

python examples/flask_server.py

All endpoints return JSON.

Examples:

curl "http://127.0.0.1:5003/health"
curl "http://127.0.0.1:5003/metadata"
curl "http://127.0.0.1:5003/cidrs"
curl "http://127.0.0.1:5003/networks"
curl "http://127.0.0.1:5003/check?value=104.16.0.0/13"
curl "http://127.0.0.1:5003/check?value=104.16.0.0-104.23.255.255"
curl "http://127.0.0.1:5003/check/range?start=104.16.0.0&end=104.23.255.255"