Policy pack: API v4

The IAB taxonomy is built for content classification, not for writing blocking rules. It scatters across the tree what a policy treats as one thing.

Gambling is the clearest case. It lives at Attractions > Casinos & Gambling, at Shopping > Lotteries and Scratchcards, at Sports > Poker and Professional Gambling, and in a Video Gaming genre. An integration that blocks the Sensitive Topics subtree blocks none of them.

The policy pack solves that: it rolls the 704 taxonomy nodes up into 47 stable group ids — the vocabulary DNS-filter, secure web gateway and endpoint policies already use. One equality test per group replaces a hand-maintained tree walk.

Requesting it

Add include=policy:

curl -X POST "https://website-categorization.whoisxmlapi.com/api/v4/categorize?apiKey=YOUR_API_KEY&include=policy" \
     -H "Content-Type: application/json" \
     -d '{"domain": "example-casino.com"}'

The response gains a policy object. It is absent from the default response, not null.

{
  "policy": {
    "pack": "policy_v1",
    "pack_version": "2026.09.2",
    "group": "gambling",
    "basis": "primary",
    "candidate_groups": ["gambling", "sports"],
    "confidence_basis": "model_raw",
    "abstained": false
  }
}

?pack=policy_v1 selects which pack to project through. It defaults to policy_v1; policy_v2 and policy_v3 are also accepted (see Other packs below). It is ignored when include omits policy. An unknown pack returns 422.

The same parameters work on the bulk endpoint, where the block is appended to every result row and built from that row's own result.

The fields

Field Type Description
pack string The pack you selected with ?pack= (default policy_v1).
pack_version string The version of the mapping. Pin against this — see below.
group string / null The single value to write a block or allow rule on.
basis string / null Which signal group came from: primary, content_purpose (policy_v3 only), or null when group is.
candidate_groups array of string The distinct groups of every entry in categories[], in candidate rank order.
confidence_basis string What the row's confidence numbers are: model_raw, filter, rule, curated, carry_over or none.
abstained boolean The same flag as abstain.is_abstain. When true on a row that still has a category, group stays populated but is advisory.

group is what you write the rule on. It is null when there is no primary category, or when the category's path is not one the pack maps. A site we could not read (domain_status blocked, unreachable or error, with include_status=true) comes back with no category: its group is null and its safety.status is not_assessed, which means we did not look, not that the site is clean, and a policy that must block a group should treat such a domain as unknown rather than allow it.

candidate_groups catches near-misses. It carries the groups of every candidate, not just the winner, with unmapped entries skipped and [] when none resolve. Match on it when you would rather catch a site whose second candidate is the one you filter on than miss it. When group is non-null it leads the list.

Group ids are the contract. They are lowercase, stable across pack versions, and matched with a plain equality test.

About basis

basis names the signal a group was derived from. Under policy_v1 and policy_v2 it is always primary — the group of primary_category. Under policy_v3 it can also read content_purpose (see Other packs below). Treat a basis value you do not recognise as non-fatal.

Beyond content_purpose, the field is shaped to allow a further signal later. A site's purpose (site_purpose: what it is for, as distinct from what it is about) is a separate axis that is not populated today. The API exposes no site_purpose block, and the bulk data feed's corresponding columns are reserved: live rows carry site_purpose_status = not_available ("not assessed", not "no purpose"), and parked or dead rows carry undefined. Nothing you build against basis: "primary" breaks when that changes: that axis arrives additively, with a changelog entry, and takes precedence for basis only once it is actually labelled.

Pin the pack version

Group ids are stable. The mapping is not — the same label can roll up to a different group under a later version, which is exactly what happened when simulated-gambling video games moved out of gambling into gambling_games.

So: store pack_version alongside any policy you derive from it. Any mapping change bumps the version and is recorded in a changelog. If your policy depends on exact group membership, pin the version and review a change before you adopt it.

Fetching the whole mapping

You do not have to discover the mapping one call at a time. The annotated taxonomy publishes all of it:

curl "https://website-categorization.whoisxmlapi.com/api/v4/taxonomy?apiKey=YOUR_API_KEY&pack=policy_v1"

Every category node gains policy_group, and the response gains a top-level pack object: id, version, and groups, an object keyed by group id whose value carries block_with (an empty list when the group has no union). Under pack=policy_v3 it also carries purpose_rules (see Other packs below). Both are absent from the default tree. The call charges no credits.

Fetch it once and join client-side against your categorize results.

Cache it differently from the default tree. The default taxonomy changes only on a major taxonomy bump and can be cached indefinitely. The annotated tree changes whenever the mapping version changes, so key your cache on pack.id plus pack.version, and re-fetch when a categorize response carries a policy.pack_version your cached tree does not have.

What a pack cannot do

A pack cannot correct a wrong label. It is a pure function of the stored category (plus, under policy_v3, the row's Content Purpose = News tag) and reads nothing else about the domain. A site misclassified as Entertainment > Movies projects to entertainment even if it is adult content. The group reflects the label we served, not ground truth. Evaluate on your own domains before you block on it.

It expresses only what the taxonomy has nodes for. There is no malware, phishing, botnet or proxy/anonymizer group, because IAB v3.1 has no such category. Threat intelligence is a separate WhoisXML product — do not use a content category as a threat verdict.

Projection does not change anything else. Requesting the block does not affect classification, caching or billing, and never changes credits_charged.

Other packs: policy_v2 and policy_v3

policy_v1 stays the default. Two more packs can be selected with ?pack=:

  • policy_v2 (mapping version 2026.09.1, 47 groups) retires the news group: its three topic roots (Crime, Disasters, War and Conflicts) read current_events, an id that says what they are. Every other node resolves to the same group as in policy_v1. Replace news with current_events in a policy you move to policy_v2.
  • policy_v3 (mapping version 2026.10.1, 48 groups) is policy_v2 plus one group, news_publishers. A row whose primary label is under Politics and that carries Content Purpose = News (the tag the include=content_purpose block serves, read whether or not you request that block) reads group: "news_publishers" with basis: "content_purpose", where policy_v2 reads politics. On any News-tagged row, whatever its primary label, every Politics entry of categories[] contributes news_publishers to candidate_groups where policy_v2 lists politics. Nothing else differs from policy_v2: a Politics row without the tag stays politics, and a news site labelled by another topic keeps that topic's group.

A policy keyed on politics should add news_publishers before it selects policy_v3, and a client that checks group or basis against a fixed list must admit news_publishers and content_purpose. The annotated taxonomy for policy_v3 carries "purpose_rules": [{"purpose": "1020", "path": "Politics", "group": "news_publishers"}], because no taxonomy node maps to news_publishers directly.

To match the bulk data feed, pass ?pack=policy_v2. The feed publishes its groups through policy_v2 (mapping version 2026.09.1), and this API defaults to policy_v1. Even then the two can differ on a row: under policy_v2 this API derives group from the primary label only, while the feed can also derive it from a brand-safety reading.

The 47 groups

Pack policy_v1, mapping version 2026.09.2, taxonomy iab_v3.1.

Sensitive groups

These are the groups a filtering policy most often blocks.

Group id Name Covers
adult Adult Pornography and explicit sexual content, plus adult-only video games. Sex education and sexual health are health; lingerie retail is fashion_beauty; dating is dating.
gambling Gambling Real-money gambling: casinos and betting, lotteries and scratchcards, poker and professional gambling.
gambling_games Gambling Games (simulated) Casino- and gambling-themed video games with no real-money play — social casino, virtual slots, poker simulations.
piracy Piracy & Copyright Infringement Torrents, warez, cracks, illegal streaming. Legitimate freeware portals are software_downloads.
drugs Drugs Illegal and abused drugs, and tobacco, vaping or alcohol treated as sensitive content. Pharmaceuticals, addiction treatment and smoking cessation are health.
alcohol Alcohol Consumer alcohol — brands, breweries, wineries, wine and spirits retail, cocktails. Bars and restaurants are food_drink.
tobacco Tobacco Cigar and tobacco hobby and retail content.
weapons Weapons Firearms, ammunition and weapon sales, reviews or advocacy. Hunting and shooting sports are hunting_fishing.
hate Hate & Discrimination Hate speech, discrimination and acts of aggression against groups.
violence Violence & Gore Graphic violence, death, injury and military conflict as sensitive content.
illegal_activities Illegal Activities Crime and harmful acts against individuals, society and human rights; exploitation and abuse.
terrorism Terrorism & Extremism Terrorist and violent-extremist content, recruitment and propaganda.
harmful_content Spam & Harmful Content Spam, scams and deceptive content — and where unlicensed-gambling markers land. A content label, not a threat verdict.
profanity Profanity & Tasteless Obscene, vulgar or profane content that is not sexual or violent.
social_issues Debated Social Issues Contested social and moral issues. Mainstream political coverage is politics.
sensitive_other Sensitive (unspecified) A label that stopped at the Sensitive Topics tier-1 without naming a theme. Treat as sensitive; the theme is unknown.

General-purpose groups

Group id Name Covers
hunting_fishing Hunting & Fishing Sport hunting, shooting sports, gun clubs, fishing. Separate from weapons — block both to cover everything firearm-related.
dating Dating Online dating, personals and matchmaking.
social_networking Social Networking Social networks and online communities.
search_engines Search Engines & Portals Web search engines and portals.
communication Email, Messaging & Conferencing Web email, web conferencing and online meetings, messaging, telephony and postal services.
software_downloads Software Downloads Freeware and shareware download portals. Pirated software is piracy.
artificial_intelligence Artificial Intelligence AI and generative-AI tools, services and topics — the node a "Generative AI" policy keys on.
technology Technology & Computing Hardware, software, programming, networking, security, cloud, web hosting, consumer electronics.
games Games Video games, esports and non-gambling genres; tabletop, card and role-playing games. No real-money play.
entertainment Entertainment Movies, music, television and radio, celebrity and pop culture, events, nightclubs.
arts_literature Arts & Literature Fine and performing arts; books, comics and poetry. Arts and crafts hobbies are lifestyle.
news News & Media Current-affairs topic roots: crime, disasters, war and conflicts.
politics Politics & Advocacy Politicians, parties, elections, civic affairs, policy and advocacy.
government_legal Government & Legal Legal topics and services.
business Business Companies, industries, B2B services, marketing and advertising, logistics, management.
finance Finance Personal finance, banking, insurance, investing, loans, taxes; the economy, markets and currencies.
careers Jobs & Careers Job search, career advice, vocational training, remote work.
education Education Schools, universities, online learning, homework, language learning.
science Science Natural sciences, space, geography, environment, weather.
health Health & Medicine Conditions, treatments, pharmaceuticals, sexual and reproductive health, mental health, addiction treatment, fitness, nutrition, wellness. Sex education lives here, not in adult.
lifestyle Society & Lifestyle Family and parenting, hobbies, crafts and collecting, pets, celebrations, holidays.
food_drink Food & Dining Cooking, recipes, diets, restaurants, non-alcoholic beverages, bars and restaurants.
travel Travel & Attractions Travel, hotels, transport, destinations; theme parks, museums, parks, zoos, landmarks.
shopping Shopping Retail, marketplaces, coupons, gifts, groceries, malls and shopping centres.
real_estate Real Estate Property listings, buying, selling and renting.
automotive Vehicles Cars, motorcycles, parts, repair, buying and selling.
sports Sports All sports, teams, leagues and equipment, including fantasy sports and horse racing.
fashion_beauty Fashion & Beauty Clothing, accessories, intimates, beauty and personal care.
home_garden Home & Garden Home improvement, décor, gardening, appliances, smart home.
religion Religion Religions, spirituality, atheism and agnosticism.
cults_occult Cults, Occult & Astrology Astrology and horoscopes, paranormal phenomena.

Blocking everything gambling-shaped

Gambling is the case the tree handles worst, so it is worth spelling out. Under mapping 2026.09.2 the concept spans three groups:

Group What it is
gambling Real-money gambling — casinos, betting, lotteries, poker.
gambling_games Simulated gambling — casino-themed video games with no real-money play.
harmful_content Where unlicensed and illegal-gambling markers land.

Block all three to block everything gambling-shaped. Block gambling alone if you draw the line where the market and regulators draw it, at real money — and note that a real-money casino could still be stored under the video-game genre, so gambling_games catches cases gambling alone would miss.