API Documentation

The URL Categorization API enables you to classify any domain or URL into IAB taxonomy categories (up to 4-tier hierarchical paths) and Web Filtering categories in a single request. Our database covers 120M+ domains, representing over 99% of active web traffic.

All API requests require an API key. You can pass your key using either method below:

HTTP
GET /api/v1/classify?url=google.com
Host: urlcategorizationdatabase.com
X-API-Key: YOUR_API_KEY

HTTP
GET /api/v1/classify?url=google.com&api_key=YOUR_API_KEY

Get an API key by signing up for a free trial or choosing a plan from our pricing page.

All API endpoints are relative to the following base URL:

URL
https://urlcategorizationdatabase.com/api/v1

All responses are JSON. Each classification result includes the following fields:

The method field indicates how the domain was classified:

API usage is credit-based. Each domain lookup consumes one credit. Your monthly allocation depends on your plan:

Each response includes a credits object showing your remaining balance:

JSON
"credits": {
  "used_this_request": 1,
  "remaining": 9999,
  "total": 10000
}

The API uses standard HTTP status codes. Error responses include a JSON body with a detail field:

Error Response Example

JSON
{
  "detail": "API credit limit exceeded. Please upgrade your plan.",
  "total_credits": 10000,
  "used": 10000,
  "remaining": 0
}

Python

Python
import requests

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://urlcategorizationdatabase.com/api/v1"

# Single domain lookup
response = requests.get(
    f"{BASE_URL}/classify",
    params={"url": "google.com"},
    headers={"X-API-Key": API_KEY}
)
result = response.json()
print(f"IAB Category: {result['category']}")
print(f"Web Filtering: {result['web_filtering_category']}")
print(f"Credits remaining: {result['credits']['remaining']}")

# Batch classification (up to 1,000 domains)
domains = ["google.com", "amazon.com", "bbc.co.uk", "github.com"]
response = requests.post(
    f"{BASE_URL}/classify",
    json={"urls": domains},
    headers={"X-API-Key": API_KEY}
)
for r in response.json()["results"]:
    print(f"{r['sni']}: {r['category']}")

JavaScript / Node.js

JavaScript
const API_KEY = 'YOUR_API_KEY';
const BASE_URL = 'https://urlcategorizationdatabase.com/api/v1';

// Single domain lookup
const response = await fetch(
  `${BASE_URL}/classify?url=google.com`,
  { headers: { 'X-API-Key': API_KEY } }
);
const data = await response.json();
console.log('IAB Category:', data.category);
console.log('Web Filtering:', data.web_filtering_category);

// Batch classification
const batchResponse = await fetch(`${BASE_URL}/classify`, {
  method: 'POST',
  headers: {
    'X-API-Key': API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    urls: ['google.com', 'amazon.com', 'bbc.co.uk']
  })
});
const results = await batchResponse.json();
results.results.forEach(r => console.log(`${r.sni}: ${r.category}`));

PHP

PHP
<?php
$apiKey = 'YOUR_API_KEY';
$baseUrl = 'https://urlcategorizationdatabase.com/api/v1';

// Single domain lookup
$ch = curl_init($baseUrl . '/classify?url=google.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 "IAB Category: " . $response['category'] . "\n";
echo "Web Filtering: " . $response['web_filtering_category'] . "\n";
echo "Credits left: " . $response['credits']['remaining'] . "\n";

cURL

Bash
# Single domain
curl -s "https://urlcategorizationdatabase.com/api/v1/classify?url=google.com" \
  -H "X-API-Key: YOUR_API_KEY" | python3 -m json.tool

# Batch (up to 1,000 domains)
curl -s -X POST "https://urlcategorizationdatabase.com/api/v1/classify" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"urls": ["google.com", "amazon.com"]}' | python3 -m json.tool

The API follows REST conventions and returns JSON, making it compatible with any HTTP client. Here are recommended libraries for popular languages:

Need help integrating? Contact us at [email protected]