OpenRTB output: API v4

If you are populating a bid request, you do not want to map our category paths onto AdCOM identifiers yourself. Ask for the projection.

Add output_format=openrtb:

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

The response gains an openrtb object. Without the parameter it is null.

{
  "domain": "stackoverflow.com",
  "primary_category": {
    "id": "IAB-631",
    "iab_id": "IAB-631",
    "name": "Programming Languages",
    "tier1": "Technology & Computing",
    "tier2": "Computing",
    "tier3": "Programming Languages",
    "tier4": null,
    "confidence": 0.99,
    "path": "Technology & Computing > Computing > Programming Languages"
  },
  "openrtb": {
    "cattax": 9,
    "cat": ["596", "599", "631"]
  }
}

The two fields

Field Type Description
cattax integer The AdCOM 1.0 "List: Category Taxonomies" enumeration value for the ids in cat.
cat array of string Raw IAB v3.1 identifiers — no IAB- prefix.

cattax is always 9

9 is IAB Tech Lab Content Taxonomy 3.1. It does not vary.

If your integration currently sends 7, that is Content Taxonomy 3.0 — a different taxonomy with different identifiers. Sending 7 alongside 3.1 ids misdescribes your inventory to every bidder downstream. Take the cattax we give you rather than carrying a constant of your own.

cat carries the full path, not just the leaf

cat lists every node on each predicted category path, root to leaf, in candidate rank order, deduplicated. For Technology & Computing > Computing > Programming Languages you get the tier-1, tier-2 and tier-3 ids.

That is deliberate. Buyers target at different depths: one wants everything under Technology & Computing, another wants Computing specifically. Because the whole path is present, a consumer matches at whatever tier granularity they target without having to walk the taxonomy themselves.

Note the identifiers are raw — "596", not "IAB-596". Elsewhere in the API, id and iab_id carry the prefixed form. OpenRTB wants them bare, so that is what cat holds.

Lifting it into a bid request

The object is shaped to be used verbatim:

{
  "site": {
    "domain": "stackoverflow.com",
    "cattax": 9,
    "cat": ["596", "599", "631"]
  }
}
result = categorize("stackoverflow.com", output_format="openrtb")
rtb = result["openrtb"]

bid_request["site"]["cattax"] = rtb["cattax"]
bid_request["site"]["cat"] = rtb["cat"]

The same projection populates app.cattax / app.cat for app inventory.

What it does not change

openrtb is a pure projection of categories[]. Requesting it does not affect classification, caching or billing, and credits_charged is unchanged. primary_category and categories[] keep exactly the same values they would have had without the parameter.

It is also orthogonal to the other opt-ins — you can combine output_format=openrtb with include=policy, include_status=true and output_mode=set on one request.

OpenRTB output is available on the single-domain endpoint only.

When there is no category

A domain with no classifiable content returns no categories, so there is nothing to project. Handle openrtb.cat being an empty array before you write to a bid request — sending an empty cat is better than sending a stale one from a previous lookup.