API Reference | Web Filtering Database

Overview

The Web Filtering Database API provides real-time domain classification into over 50 web filtering categories. Each response includes filtering categories, country of origin, and classification confidence.

Base URL:

https://webfilteringdatabase.com/api/v1

All responses are returned in JSON format. The API supports both single and batch lookups — see the bulk domain classification API guide for batch processing details.

Authentication

All API requests require authentication using an API key. You can pass it in two ways:

Header Authentication (Recommended)

X-API-Key: your_api_key_here

Query Parameter

?api_key=your_api_key_here

To obtain an API key, choose a plan or contact our sales team.

Rate Limits

API rate limits depend on your subscription plan. All plans support burst requests. If you exceed your quota, the API returns HTTP 429.

Plan	Monthly Lookups	Batch Size
Starter	5,000	100
Growth	100,000	500
Business	500,000	1,000
Enterprise	2,000,000	1,000

Country Detection

Every API response includes a country field containing the ISO 3166-1 alpha-2 country code associated with the domain. This enables geographic filtering, regional compliance enforcement, and location-based policy decisions.

How It Works

Country data is derived from domain registration records, hosting infrastructure analysis, and traffic patterns. The database covers over 46 million domains with verified country attribution.

Example Response with Country

{
    "domain": "spiegel.de",
    "root_domain": "spiegel.de",
    "web_filtering_category": "News",
    "country": "DE",
    "method": "direct",
    "confidence": 1.0
}

Common Use Cases

Use Case	Description
Geo-blocking	Block or allow domains based on country of origin
Compliance	Enforce data sovereignty and regional regulations (GDPR, CCPA)
Analytics	Analyze traffic patterns by country of destination
Risk scoring	Factor geographic risk into threat assessments

Single Domain Lookup

GET /classify?domain={domain}

Classify a single domain and return its web filtering categories.

Parameters

Parameter	Type	Description
domain	string required	The domain to classify (e.g., github.com)
api_key	string required	Your API key (or use X-API-Key header)

Response

{
    "domain": "github.com",
    "root_domain": "github.com",
    "web_filtering_category": "Developer Tools / Code Hosting|Business|Community Sites",
    "country": "US",
    "method": "direct",
    "confidence": 1.0
}

Batch Domain Lookup

POST /classify

Classify multiple domains in a single request. Maximum 1,000 domains per batch.

Request Body

{
    "domains": ["github.com", "google.com", "bbc.co.uk"]
}

Response

{
    "results": [
        {
            "domain": "github.com",
            "root_domain": "github.com",
            "web_filtering_category": "Developer Tools / Code Hosting|Business|Community Sites",
            "country": "US",
            "method": "direct",
            "confidence": 1.0
        },
        ...
    ],
    "count": 3
}

Health Check

GET /health

Check service status. No authentication required.

{
    "status": "ok",
    "domains_loaded": 103000000,
    "countries_loaded": 98000000
}

Code Examples

cURL

Python

JavaScript

PHP

curl -X GET "https://webfilteringdatabase.com/api/v1/classify?domain=example.com" \
     -H "X-API-Key: your_api_key_here"

import requests

API_KEY = "your_api_key_here"
BASE_URL = "https://webfilteringdatabase.com/api/v1"

# Single lookup
response = requests.get(
    f"{BASE_URL}/classify",
    params={"domain": "example.com"},
    headers={"X-API-Key": API_KEY}
)
data = response.json()
print(f"Category: {data['web_filtering_category']}")
print(f"Country: {data['country']}")

# Batch lookup
response = requests.post(
    f"{BASE_URL}/classify",
    json={"domains": ["github.com", "google.com"]},
    headers={"X-API-Key": API_KEY}
)
for result in response.json()["results"]:
    print(f"{result['domain']}: {result['web_filtering_category']}")

const API_KEY = 'your_api_key_here';
const BASE_URL = 'https://webfilteringdatabase.com/api/v1';

// Single lookup
const res = await fetch(
    `${BASE_URL}/classify?domain=example.com`,
    { headers: { 'X-API-Key': API_KEY } }
);
const data = await res.json();
console.log(`Category: ${data.web_filtering_category}`);
console.log(`Country: ${data.country}`);

// Batch lookup
const batchRes = await fetch(`${BASE_URL}/classify`, {
    method: 'POST',
    headers: {
        'X-API-Key': API_KEY,
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        domains: ['github.com', 'google.com']
    })
});
const batchData = await batchRes.json();
batchData.results.forEach(r =>
    console.log(`${r.domain}: ${r.web_filtering_category}`)
);

<?php
$apiKey = 'your_api_key_here';
$baseUrl = 'https://webfilteringdatabase.com/api/v1';

// Single lookup
$ch = curl_init("$baseUrl/classify?domain=example.com");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ["X-API-Key: $apiKey"],
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

echo "Category: " . $response['web_filtering_category'] . "\n";
echo "Country: " . $response['country'] . "\n";

// Batch lookup
$ch = curl_init("$baseUrl/classify");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "X-API-Key: $apiKey",
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'domains' => ['github.com', 'google.com']
    ]),
]);
$batch = json_decode(curl_exec($ch), true);
curl_close($ch);

foreach ($batch['results'] as $r) {
    echo $r['domain'] . ": " . $r['web_filtering_category'] . "\n";
}
?>

Response Fields

Field	Type	Description
domain	string	The queried domain
root_domain	string	The extracted root domain (e.g., "example.com" from "blog.example.com")
web_filtering_category	string	Pipe-separated list of web filtering categories (e.g., "Business\|Shopping")
country	string	Two-letter ISO country code where the domain is associated (e.g., "US", "DE")
method	string	Classification method used: "direct" (exact match) or "not_found"
confidence	float	Classification confidence score between 0.0 and 1.0

Error Codes

200 Successful response

400 Bad request — missing or invalid domain parameter

401 Unauthorized — missing API key

403 Forbidden — invalid or inactive API key

429 Too many requests — quota or rate limit exceeded

500 Internal server error

502 Classification service temporarily unavailable