Docs / Website Category API
v3

Website Category API

Classify any URL, domain name, or IP address into industry-standard categories using machine learning. Supports both the IAB Tech Lab taxonomy (400+ categories) and Webshrinker's own 40-category taxonomy.

1 Authentication

Every request to the Category API must be authenticated. Webshrinker supports two methods — Basic HTTP Authentication for server-side calls, and Pre-signed URLs for embedding directly in front-end applications.

Basic HTTP Authentication

Encode your access key and secret key as access-key:secret-key in base64 and pass it in the Authorization header. Always use HTTPS. 

# Basic HTTP Authentication via curl -u flag
curl -u "access-key:secret-key" \
  "https://api.webshrinker.com/categories/v3/d2Vic2hyaW5rZXIuY29t"
<?php

$access_key = "your access key";
$secret_key = "your secret key";

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.webshrinker.com/categories/v3");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_USERPWD, $access_key . ":" . $secret_key);

$response = curl_exec($ch);
?>
import requests

access_key = "your access key"
secret_key = "your secret key"

response = requests.get(
    "https://api.webshrinker.com/categories/v3",
    auth=(access_key, secret_key)
)
data = response.json()
using System;
using System.Text;
using System.Net;
using System.IO;

string apiKey    = "your access key";
string apiSecret = "your secret key";
string apiUrl    = "https://api.webshrinker.com/categories/v3";

HttpWebRequest request = (HttpWebRequest)WebRequest.Create(apiUrl);
request.ContentType = "application/json; charset=utf-8";
request.Headers["Authorization"] = "Basic " +
    Convert.ToBase64String(
        Encoding.GetEncoding("ISO-8859-1")
                .GetBytes(apiKey + ":" + apiSecret)
    );
request.PreAuthenticate = true;

HttpWebResponse resp = request.GetResponse() as HttpWebResponse;
using (Stream s = resp.GetResponseStream())
{
    StreamReader reader = new StreamReader(s, Encoding.UTF8);
    Console.WriteLine(reader.ReadToEnd());
}

Pre-signed URLs

Pre-signed URLs let you make requests without exposing your secret key. The URL is signed using an MD5 hash of secret-key:request-path-with-params. You can optionally include an expires Unix timestamp to limit URL validity.

FORMULA hash = MD5(secret-key:request-url-with-params) 
WS_ACCESS_KEY="your access key"
WS_SECRET_KEY="your secret key"

# Base64-encode the target URL
URL=$(echo -n "https://www.webshrinker.com" | base64)

REQUEST="categories/v3/$URL?key=$WS_ACCESS_KEY"
HASH=$(echo -n "$WS_SECRET_KEY:$REQUEST" | (md5sum || md5))

echo "https://api.webshrinker.com/$REQUEST&hash=$HASH"
<?php

function webshrinker_categories_v3($access_key, $secret_key, $url="", $options=array()) {
    $options['key'] = $access_key;

    $parameters = http_build_query($options);
    $request    = sprintf("categories/v3/%s?%s", base64_encode($url), $parameters);
    $hash       = md5(sprintf("%s:%s", $secret_key, $request));

    return "https://api.webshrinker.com/{$request}&hash={$hash}";
}

$access_key = "your access key";
$secret_key = "your secret key";
$url        = "https://www.webshrinker.com/";

$signedUrl  = webshrinker_categories_v3($access_key, $secret_key, $url);
echo "$signedUrl\n";
?>
try:
    from urllib import urlencode
except ImportError:
    from urllib.parse import urlencode

from base64 import urlsafe_b64encode
import hashlib

def webshrinker_categories_v3(access_key, secret_key, url=b"", params={}):
    params['key'] = access_key

    request = "categories/v3/{}?{}".format(
        urlsafe_b64encode(url).decode('utf-8'),
        urlencode(params, True)
    )
    request_to_sign = "{}:{}".format(secret_key, request).encode('utf-8')
    signed_request  = hashlib.md5(request_to_sign).hexdigest()

    return "https://api.webshrinker.com/{}&hash={}".format(request, signed_request)

access_key = "your access key"
secret_key = "your secret key"
url        = b"https://www.webshrinker.com/"

print(webshrinker_categories_v3(access_key, secret_key, url))

2 Category Taxonomies

The Category API supports two taxonomies, selected via the taxonomy query parameter:

iabv1 default
IAB Tech Lab Content Taxonomy — Over 400 granular categories organized into a two-level hierarchy. Each category includes a confidence score and parent reference.
webshrinker string
Webshrinker Taxonomy — 40 top-level categories optimized for web filtering and content policy use cases. Returns up to 3 of the most relevant categories.

3 List All Categories

Retrieve the complete set of available categories for a given taxonomy. Useful for building category filters or understanding the classification space.

GET https://api.webshrinker.com/categories/v3

Query Parameters

ParameterRequiredDefaultDescription
key Required* — Your access key. Required only when using pre-signed URLs.
expires Optional 0 Unix timestamp after which the pre-signed URL expires.
taxonomy Optional iabv1 Taxonomy to use: iabv1 or webshrinker.
_ Optional — Cache buster — any value to bypass CDN caching.

Example Request

# Using Basic Authentication
curl -u "access-key:secret-key" \
  "https://api.webshrinker.com/categories/v3"

# Using a pre-signed URL
curl "https://api.webshrinker.com/categories/v3/?key=TvQu6ARhl2Zs7BVV1plU&hash=0f41d9264f05b2aeb0064fc6d7114cbc"
<?php

function webshrinker_categories_v3($access_key, $secret_key, $url="", $options=array()) {
    $options['key'] = $access_key;
    $parameters    = http_build_query($options);
    $request       = sprintf("categories/v3/%s?%s", base64_encode($url), $parameters);
    $hash          = md5(sprintf("%s:%s", $secret_key, $request));
    return "https://api.webshrinker.com/{$request}&hash={$hash}";
}

$access_key = "your access key";
$secret_key = "your secret key";

$request = webshrinker_categories_v3($access_key, $secret_key);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $request);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

$response    = curl_exec($ch);
$status_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);

print_r(json_decode($response));
?>
try:
    from urllib import urlencode
except ImportError:
    from urllib.parse import urlencode

from base64 import urlsafe_b64encode
import hashlib, requests, json

def webshrinker_categories_v3(access_key, secret_key, url=b"", params={}):
    params['key'] = access_key
    request = "categories/v3/{}?{}".format(
        urlsafe_b64encode(url).decode('utf-8'), urlencode(params, True))
    signed = hashlib.md5("{}:{}".format(secret_key, request).encode()).hexdigest()
    return "https://api.webshrinker.com/{}&hash={}".format(request, signed)

access_key = "your access key"
secret_key = "your secret key"

api_url  = webshrinker_categories_v3(access_key, secret_key)
response = requests.get(api_url)
data     = response.json()

if response.status_code == 200:
    print(json.dumps(data, indent=4, sort_keys=True))
using System;
using System.Text;
using System.Net;
using System.IO;

string apiKey    = "your access key";
string apiSecret = "your secret key";
string apiUrl    = "https://api.webshrinker.com/categories/v3";

HttpWebRequest request = (HttpWebRequest)WebRequest.Create(apiUrl);
request.ContentType = "application/json; charset=utf-8";
request.Headers["Authorization"] = "Basic " +
    Convert.ToBase64String(
        Encoding.GetEncoding("ISO-8859-1").GetBytes(apiKey + ":" + apiSecret));
request.PreAuthenticate = true;

HttpWebResponse resp = request.GetResponse() as HttpWebResponse;
using (Stream s = resp.GetResponseStream())
{
    var reader = new StreamReader(s, Encoding.UTF8);
    Console.WriteLine(reader.ReadToEnd());
}

Response

200 OK application/json
JSON 
{
    "data": [
        {
            "categories": {
                "IAB1": {
                    "IAB1":   "Arts & Entertainment",
                    "IAB1-1": "Books & Literature",
                    "IAB1-2": "Celebrity Fan/Gossip",
                    "IAB1-3": "Fine Art",
                    "IAB1-4": "Humor",
                    "IAB1-5": "Movies",
                    "IAB1-6": "Music & Audio",
                    "IAB1-7": "Television & Video"
                },
                "IAB10": {
                    "IAB10":   "Home & Garden",
                    "IAB10-1": "Appliances",
                    "IAB10-2": "Entertaining",
                    "IAB10-3": "Environmental Safety",
                    "IAB10-4": "Gardening"
                }
                // ... all categories
            }
        }
    ]
}

4 Category Lookup

Classify a specific URL, domain, or IP address. The target must be Base64-encoded before appending it to the endpoint path.

GET https://api.webshrinker.com/categories/v3/{base64-encoded-url}
Base64 Encoding: Use URL-safe Base64 encoding. For example, https://webshrinker.com encodes to aHR0cHM6Ly93ZWJzaHJpbmtlci5jb20=.

Query Parameters

ParameterRequiredDefaultDescription
key Required* — Access key. Required only for pre-signed URL auth.
expires Optional 0 Unix timestamp for URL expiration.
taxonomy Optional iabv1 iabv1 or webshrinker
_ Optional — Cache buster.

Example Request

# d2Vic2hyaW5rZXIuY29t = base64("webshrinker.com")

# Basic Authentication
curl -u "access-key:secret-key" \
  "https://api.webshrinker.com/categories/v3/d2Vic2hyaW5rZXIuY29t"

# Pre-signed URL
curl "https://api.webshrinker.com/categories/v3/d2Vic2hyaW5rZXIuY29t?key=TvQu6ARhl2Zs7BVV1plU&hash=afe42ba2e8ae6f9d5ec2a0535ab484fe"
<?php

function webshrinker_categories_v3($access_key, $secret_key, $url="", $options=array()) {
    $options['key'] = $access_key;
    $parameters    = http_build_query($options);
    $request       = sprintf("categories/v3/%s?%s", base64_encode($url), $parameters);
    $hash          = md5(sprintf("%s:%s", $secret_key, $request));
    return "https://api.webshrinker.com/{$request}&hash={$hash}";
}

$access_key = "your access key";
$secret_key = "your secret key";
$url        = "https://www.webshrinker.com";
$request    = webshrinker_categories_v3($access_key, $secret_key, $url);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $request);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

$response    = curl_exec($ch);
$status_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);

switch($status_code) {
    case 200: /* Success */ break;
    case 202: /* Categories being calculated, check back */ break;
    case 400: /* Bad request */ break;
    case 401: /* Unauthorized */ break;
    case 402: /* Request limit reached */ break;
}
?>
try:
    from urllib import urlencode
except ImportError:
    from urllib.parse import urlencode

from base64 import urlsafe_b64encode
import hashlib, requests, json

def webshrinker_categories_v3(access_key, secret_key, url=b"", params={}):
    params['key'] = access_key
    request = "categories/v3/{}?{}".format(
        urlsafe_b64encode(url).decode('utf-8'), urlencode(params, True))
    signed = hashlib.md5("{}:{}".format(secret_key, request).encode()).hexdigest()
    return "https://api.webshrinker.com/{}&hash={}".format(request, signed)

access_key = "your access key"
secret_key = "your secret key"
url        = b"https://www.webshrinker.com/"

api_url  = webshrinker_categories_v3(access_key, secret_key, url)
response = requests.get(api_url)
data     = response.json()

if   response.status_code == 200: print(json.dumps(data, indent=4))
elif response.status_code == 202: print("Categories being calculated, check back soon")
elif response.status_code == 400: print("Bad or malformed HTTP request")
elif response.status_code == 401: print("Unauthorized - check your access and secret key")
elif response.status_code == 402: print("Account request limit reached")
else:                                print("A general error occurred, try again")
using System;
using System.Text;
using System.Net;
using System.IO;

string apiKey    = "your access key";
string apiSecret = "your secret key";
string domain    = "example.com";

string apiUrl = "https://api.webshrinker.com/categories/v3/" +
    Convert.ToBase64String(
        Encoding.GetEncoding("ISO-8859-1").GetBytes(domain));

HttpWebRequest request = (HttpWebRequest)WebRequest.Create(apiUrl);
request.ContentType = "application/json; charset=utf-8";
request.Headers["Authorization"] = "Basic " +
    Convert.ToBase64String(
        Encoding.GetEncoding("ISO-8859-1").GetBytes(apiKey + ":" + apiSecret));
request.PreAuthenticate = true;

HttpWebResponse resp = request.GetResponse() as HttpWebResponse;
using (Stream s = resp.GetResponseStream())
{
    Console.WriteLine(new StreamReader(s, Encoding.UTF8).ReadToEnd());
}

5 Response Format

IAB Taxonomy Response

When using the iabv1 taxonomy, each category includes a confidence score and parent reference.

200 OK IAB taxonomy — application/json
JSON 
{
    "data": [
        {
            "categories": [
                {
                    "confident": true,
                    "id":        "IAB19",
                    "label":     "Technology & Computing",
                    "parent":    "IAB19",
                    "score":     "0.855809166500086094"
                },
                {
                    "confident": true,
                    "id":        "IAB19-18",
                    "label":     "Internet Technology",
                    "parent":    "IAB19",
                    "score":     "0.824063117153139624"
                }
            ],
            "url": "webshrinker.com"
        }
    ]
}
FieldTypeDescription
confidentbooleanTrue if the majority of content relates to this category.
idstringIAB category identifier (e.g., IAB19-18).
labelstringHuman-readable category name.
parentstringParent category identifier.
scorestringFloating-point confidence value (0.0 – 1.0).

Webshrinker Taxonomy Response

200 OK Webshrinker taxonomy — application/json
JSON 
{
    "data": [
        {
            "categories": [
                {
                    "id":    "business",
                    "label": "Business"
                },
                {
                    "id":    "informationtech",
                    "label": "Information Technology"
                }
            ],
            "url": "webshrinker.com"
        }
    ]
}

Error Response

401 Unauthorized application/json
JSON 
{
    "error": {
        "message": "Invalid signed hash or no API key/secret given"
    }
}

6 HTTP Status Codes

CodeStatusDescription
200OKCurrent categories returned successfully.
202AcceptedCategories are being calculated. May include partial data — check back shortly.
400Bad RequestMalformed or invalid HTTP request.
401UnauthorizedInvalid API credentials or signature.
402Payment RequiredAccount request limit reached.
412Precondition FailedInsufficient information to classify the target URL.
429Too Many RequestsRate limit exceeded. Reduce request frequency.
500Server ErrorInternal error. Retry the request.