cipawebfiltering

A production-ready Python client for the CIPA web filtering domain classification database — 120 million domains classified across 57+ content categories, purpose-built for K-12 school districts, public libraries, and any organization that must comply with the Children's Internet Protection Act. The package wraps the REST API in a small, typed, dependency-light interface so IT administrators, network engineers, and compliance teams can look up, filter, and synchronize domain intelligence directly from Python.

---

What is CIPA and why does it matter?

The Children's Internet Protection Act (CIPA) is a United States federal law enacted in 2000 that requires schools and libraries receiving E-Rate funding or LSTA grants to implement internet safety policies and technology protection measures. In practice, this means deploying a web filtering solution that blocks access to content that is obscene, contains child sexual abuse material (CSAM), or is harmful to minors. Districts must also adopt and enforce an acceptable-use policy that covers student activity on and off campus, including 1:1 device programs.

Compliance is not optional: failure to meet CIPA requirements puts E-Rate funding at risk, which for many districts represents hundreds of thousands of dollars annually. Beyond the legal obligation, schools and libraries have a duty of care to protect minors from harmful material while preserving access to educational resources. Over-blocking legitimate content is almost as damaging as under-blocking, because it frustrates teachers, disrupts lesson plans, and erodes trust in the filtering system.

The CIPA web filtering database addresses both sides of this challenge. Every domain receives multi-label classification rather than a single verdict, so a domain that hosts both educational and social-media content is tagged with both categories. Policy engines can then make precise blocking decisions per category instead of relying on a blunt allow-or-deny list, dramatically reducing false positives while maintaining full coverage of CIPA-mandated content types.

---

Installation

pip install cipawebfiltering

The only runtime dependency is requests. Python 3.7 and newer are supported.

---

Quick start

from cipawebfiltering import CIPAWebFilteringClient

client = CIPAWebFilteringClient("your_api_key_here")

# Check a single domain
result = client.lookup("example-games-site.com")
print(result["categories"])       # ["Gaming", "Gambling"]
print(result["should_block"])     # True
print(result["confidence"])       # 0.97

# Convenience boolean for inline policy decisions
if client.is_blocked("unknown-domain.net"):
    enforce_block("unknown-domain.net")

An API key is required and can be obtained from the account dashboard at cipawebfiltering.com after subscribing to a plan. Keys are passed automatically as a Bearer token on every request.

---

Configuration

client = CIPAWebFilteringClient(
    api_key="your_api_key_here",
    base_url="https://www.cipawebfiltering.com/api/v1",   # override for testing
    timeout=30,        # per-request timeout in seconds
    max_retries=3,     # automatic backoff on 429 and 5xx
)

Transient failures — HTTP 429 rate limits and 5xx server errors — are retried automatically with exponential backoff, honoring the Retry-After header when present. Authentication errors raise immediately.

---

API methods

Single domain lookup

result = client.lookup("social-media-site.com")

Response:

{
  "domain": "social-media-site.com",
  "categories": ["Social Media", "User-Generated Content"],
  "should_block": true,
  "confidence": 0.95,
  "last_seen": "2026-07-22T08:00:00Z",
  "dns_active": true
}

Pass a bare domain — example.com, not https://example.com/page. Subdomains resolve to their registrable domain automatically. The response includes multi-label categories, a block recommendation based on your policy tier, and a confidence score. Both found and not-found domains return HTTP 200; check the should_block boolean or the categories array.

Bulk lookup

Classify up to 1,000 domains in a single request:

report = client.bulk_lookup(["tiktok.com", "khanacademy.org", "steam-community.ru"])
for row in report["results"]:
    print(row["domain"], row["categories"], row["should_block"])

For arbitrarily large inputs, chunking is handled automatically:

all_results = client.bulk_lookup_all(my_50000_domains)
blocked = [r for r in all_results if r["should_block"]]

List categories

Retrieve the full taxonomy of 57+ content categories with descriptions:

cats = client.categories()
for cat in cats["categories"]:
    print(cat["name"], "-", cat["description"])

Categories include CIPA-mandated types such as Adult Content, Violence, Weapons, Drugs, Gambling, and Malware, as well as productivity-relevant categories like Social Media, Streaming, Gaming, and Shopping.

Sync the full database

For DNS-level filtering, firewall External Dynamic Lists (EDLs), or local proxy caches, stream the entire classified domain list:

with open("blocked_domains.txt", "w") as fh:
    for record in client.iter_domains(category="Adult Content"):
        fh.write(record["domain"] + "\n")

Then keep it current with daily delta syncs instead of re-downloading everything:

changes = client.delta(since="2026-07-21T00:00:00Z")
for added in changes["added"]:
    local_blocklist.add(added["domain"])
for removed in changes["removed"]:
    local_blocklist.discard(removed["domain"])

This "full load once, delta forever" pattern lets a modest API quota support millions of local lookups, because the actual matching happens in your own DNS resolver, Redis, SQLite, or flat file.

Database statistics

stats = client.stats()
print(stats["total_domains"])     # 120000000+
print(stats["last_updated"])      # "2026-07-22T06:00:00Z"
print(stats["new_today"])         # ~300000

---

Error handling

The client raises a small, specific exception hierarchy:

from cipawebfiltering import (
    CIPAWebFilteringError,
    AuthenticationError,
    RateLimitError,
    NotFoundError,
)

try:
    result = client.lookup("example.com")
except AuthenticationError:
    # 401/403 — renew or rotate the key
    ...
except RateLimitError:
    # 429 after retries — back off or upgrade the plan
    ...
except CIPAWebFilteringError:
    # any other API or network failure
    ...

The client is also a context manager, so the underlying HTTP session is cleaned up automatically:

with CIPAWebFilteringClient("your_api_key_here") as client:
    print(client.stats())

---

Use cases

District-wide filtering: Apply consistent content policies across every building in a district. Import the database into your DNS resolver or secure web gateway and enforce category-based rules that distinguish between a blocked gaming site and a permitted educational game.

1:1 Chromebook and laptop programs: Students take devices home, outside the school firewall. Feed the domain list into a DNS-over-HTTPS resolver or endpoint agent to maintain CIPA compliance on and off campus.

Public library internet access: Libraries must filter content on public terminals while respecting patron privacy and intellectual freedom. Multi-label classification lets librarians allow research resources that a single-category system would wrongly block.

DNS and RPZ filtering: Export the database as a Response Policy Zone (RPZ) file and load it into BIND, Unbound, or any RPZ-capable resolver. Blocking happens at the DNS layer with zero latency overhead on permitted traffic.

Firewall EDL integration: Generate External Dynamic Lists for Palo Alto, Fortinet, or Cisco firewalls. The delta sync endpoint keeps the list current without manual intervention.

AI tool governance in schools: The database includes a dedicated AI Tools subcategory covering 16,000+ domains — chatbots, essay writers, homework solvers, deepfake tools, and voice cloning services. Districts can permit approved AI tutoring tools while blocking services that undermine academic integrity.

---

How the database is built

The classification pipeline processes approximately 300,000 newly discovered domains every day. Each domain is fetched, its content extracted and analyzed through a multi-stage machine learning pipeline that assigns one or more of 57+ content categories. Unlike single-label classifiers that force every domain into exactly one bucket, the multi-label approach recognizes that real-world websites often span multiple topics. A domain hosting both educational math content and an unmoderated chat forum receives both the Education and the Chat/Messaging labels, allowing the policy engine to make a nuanced decision rather than defaulting to a blanket block or allow.

Every classification is verified against a confidence threshold before entering the production database. Domains whose content changes significantly between crawls are re-evaluated and re-labeled automatically. The result is a living dataset that reflects the current state of the web rather than a static snapshot that grows stale within weeks.

All content categories required by CIPA — obscene material, CSAM, and content harmful to minors — are maintained as top-level categories with the highest screening priority. Additional categories cover productivity concerns (Social Media, Streaming, Gaming, Shopping), security threats (Malware, Phishing, Command and Control), and emerging risks (AI Tools, Deepfakes, Cryptocurrency).

Delivery formats

The CIPA web filtering database is available in multiple formats beyond this Python client:

• REST API — real-time lookups with millisecond response times
• CSV downloads — daily-refreshed flat files for offline use
• DNS / RPZ blocklists — ready-to-load zone files
• PAC files — browser-level proxy auto-config
• Hosts files — simple domain-to-localhost mapping
• Firewall EDLs — external dynamic lists for next-gen firewalls

---

Related services

For organizations that need broader domain intelligence beyond CIPA compliance, the following services complement this package:

• Website Categorization API: Real-time URL classification using the IAB taxonomy across 700+ categories, supporting ad-tech, brand safety, and content analytics.

• AI Tools Blocklist: A daily-refreshed database of classified AI-tool domains — chatbots, code assistants, image generators, voice cloners — organized into functional categories for granular acceptable-use policies.

• Web Filtering Database: Enterprise-grade downloadable database of 100 million domains across 59 content categories, designed for DNS-level blocking in firewalls, proxies, and secure web gateways.

• URL Categorization Database: Categorized domains at enterprise scale for contextual targeting, brand safety, and large-scale analytics.

• Phishing Detection API: Real-time phishing domain detection powered by a daily-updated database of 390,000+ DNS-verified active phishing domains, built for cybersecurity teams, email providers, and safe browsing implementations.

• Domain-Level M&A Signal Extraction: The same domain classification infrastructure that powers CIPA filtering also screens business domains for acquisition signals. The platform applies a 15-signal extraction framework to over 100 million domains, identifying companies that match a buyer's thesis based on leadership bench, service mix, compliance readiness, and other operational evidence visible on the public web.

• Cookieless Domain Intelligence Platform: Domain classification serves privacy-first advertising and audience building without cookies. Pre-categorized domain datasets organized under the IAB content taxonomy enable DSPs, SSPs, and publishers to run contextual targeting campaigns that respect user privacy while maintaining the granularity that programmatic buyers require for brand-safe ad placement.

• Resume Reader API: AI resume parsing API — structured JSON from PDF/DOCX resumes. Extracts contact information, work history, education, and skills so school districts and HR teams can feed applicant tracking systems directly from submitted CVs.

---

Links

• Product and documentation: https://www.cipawebfiltering.com
• FCC — Children's Internet Protection Act: https://www.fcc.gov/consumers/guides/childrens-internet-protection-act
• E-Rate program: https://www.fcc.gov/general/e-rate-program

License

MIT