Name: IAB Content Classification
Brand: quickpod
SKU: api-quickpod-aiquick-classify
Availability: InStock
Author: API Market

Anil Singh

# IAB Content Classification

## Overview

The IAB Content Classification API provides a robust solution for categorizing web content into standard IAB (Interactive Advertising Bureau) taxonomy categories. This API allows you to accurately classify articles, landing pages, and publisher inventory, supporting both granular tiered predictions (Tier 1, Tier 2, Tier 3) and a unified multi-tier approach in a single request.

Optimized for production enrichment pipelines, the IAB Content Classification API takes various input types such as a URL, text, title, domain, or keywords. It returns a ranked list of category predictions with confidence scores, making it simple to integrate into ad targeting rules, content routing, analytics organization, or content ingestion workflows.

## Features

- **Tiered Classification:** Predicts IAB categories at Tier 1, Tier 2, or Tier 3 levels for granular content analysis.
- **Unified Multi-Tier Prediction:** Obtain predictions across multiple IAB tiers (Tier 1, Tier 2, Tier 3) in a single API call for comprehensive categorization.
- **Flexible Input Options:** Classify content using a URL, raw text, content title, website domain, or relevant keywords.
- **Ranked Predictions with Scores:** Receive a sorted list of potential IAB categories, each with an associated confidence score, enabling detailed content understanding.
- **Adjustable Prediction Count (`top_k`):** Control the number of top predictions returned (from 1 to 20) to focus on the strongest matches or explore a wider range of candidates.
- **Simple Output Format:** Easily integrate results with a `tier` field indicating the prediction level and a `predictions` array of `{ label, score }` objects.
- **Fast & Repeatable:** Designed for efficient and consistent category assignment within content pipelines, even with lightweight metadata.

## Use Cases

The IAB Content Classification API is a powerful tool for a variety of industries and applications, enhancing content understanding and monetization strategies.

- **Digital Advertising & Ad Tech:** Improve contextual ad targeting by accurately classifying publisher content, ensuring ads are displayed alongside relevant material and increasing campaign effectiveness. For example, categorize news articles to serve financial ads only on "Business & Finance" content.
- **Content Monetization for Publishers:** Automate the classification of article inventory and website pages into IAB categories, enabling publishers to offer precise audience segments and premium ad placements to advertisers. This maximizes ad revenue and helps sell inventory more efficiently.
- **Content Management & SEO:** Organize large content libraries by automatically assigning IAB labels, making content easier to discover, manage, and optimize for search engines. This helps SEO teams identify content gaps and improve topical authority.
- **Data Analytics & Business Intelligence:** Enrich content data streams with standard IAB taxonomies, providing a consistent framework for analyzing content performance, audience engagement, and market trends across various platforms.
- **Brand Safety & Content Moderation:** Automatically flag content based on IAB categories that might be considered sensitive or unsuitable for certain ad campaigns, helping brands maintain safety and align with their guidelines.

## Pricing

The IAB Content Classification API is priced based on usage volume.
- 1 API unit equals 1 content classification request.
- Different pricing tiers are available based on usage volume.

## API Documentation

### Base URL

All API requests should be made to: `https://prod.api.market/api/v1/quickpod/aiquick-classify`

### Authentication

Authentication is handled via API key. Include your API key in the request header:
```
x-api-market-key: YOUR_API_MARKET_KEY
```

### Endpoints

#### Service health

`GET /api/v1/quickpod/aiquick-classify/health`

**Summary:** Checks the health status of the service.
**Tags:** Health

**Request Example (cURL):**
```bash
curl -X GET "https://prod.api.market/api/v1/quickpod/aiquick-classify/health" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

**Response Example (200 OK):**
```json
{
  "ok": true,
  "service": "api-quickpod-aiquick-classify",
  "max_inflight": 50
}
```

#### Upstream dataset health

`GET /api/v1/quickpod/aiquick-classify/kdb/health`

**Summary:** Checks the health status of the upstream dataset.
**Tags:** Health

**Request Example (cURL):**
```bash
curl -X GET "https://prod.api.market/api/v1/quickpod/aiquick-classify/kdb/health" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

**Response Example (200 OK):**
```json
{}
```
(Response content can vary, indicating upstream system status.)

#### Unified classifier health

`GET /api/v1/quickpod/aiquick-classify/classify/unified/health`

**Summary:** Checks the health status of the unified classifier.
**Tags:** Health

**Request Example (cURL):**
```bash
curl -X GET "https://prod.api.market/api/v1/quickpod/aiquick-classify/classify/unified/health" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

**Response Example (200 OK):**
```json
{}
```
(Response content can vary, indicating upstream system status.)

#### Predict IAB Tier 1 categories

`POST /api/v1/quickpod/aiquick-classify/classify/tier1`

**Summary:** Predicts IAB Tier 1 categories for the provided content.
**Tags:** Classify

**Request Body:** `application/json`
**Schema:**
```json
{
  "type": "object",
  "properties": {
    "text": {
      "type": "string",
      "nullable": true,
      "description": "The text content to classify."
    },
    "url": {
      "type": "string",
      "nullable": true,
      "description": "A URL pointing to the content to classify. The API will fetch content from this URL."
    },
    "domain": {
      "type": "string",
      "nullable": true,
      "description": "The domain of the content, e.g., 'example.com'."
    },
    "title": {
      "type": "string",
      "nullable": true,
      "description": "The title of the content."
    },
    "keywords": {
      "type": "string",
      "nullable": true,
      "description": "Comma-separated keywords describing the content."
    },
    "top_k": {
      "type": "integer",
      "minimum": 1,
      "maximum": 20,
      "default": 3,
      "description": "The maximum number of top predictions to return."
    }
  }
}
```

**Request Example (cURL) - Finance content intent:**
```bash
curl -X POST "https://prod.api.market/api/v1/quickpod/aiquick-classify/classify/tier1" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "url": "https://finance.example.com/retirement-guide",
    "text": "How to build a diversified retirement portfolio for long-term growth.",
    "top_k": 5
  }'
```

**Response Example (200 OK):**
```json
{
  "tier": "tier1",
  "predictions": [
    {
      "label": "Business",
      "score": 0.94
    },
    {
      "label": "Finance",
      "score": 0.71
    }
  ]
}
```

#### Predict IAB Tier 2 categories

`POST /api/v1/quickpod/aiquick-classify/classify/tier2`

**Summary:** Predicts IAB Tier 2 categories for the provided content.
**Tags:** Classify

**Request Body:** `application/json`
**Schema:** (Same as `PredictRequest`)

**Request Example (cURL) - B2B SaaS page:**
```bash
curl -X POST "https://prod.api.market/api/v1/quickpod/aiquick-classify/classify/tier2" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "text": "All-in-one CRM platform for marketing, sales, and customer success teams.",
    "domain": "saas-example.com",
    "top_k": 4
  }'
```

**Response Example (200 OK):**
```json
{
  "tier": "tier2",
  "predictions": [
    {
      "label": "Business Technology",
      "score": 0.92
    },
    {
      "label": "Software",
      "score": 0.88
    },
    {
      "label": "Sales",
      "score": 0.75
    }
  ]
}
```
*(Example response manually generated based on schema for Tier 2)*

#### Predict IAB Tier 3 categories

`POST /api/v1/quickpod/aiquick-classify/classify/tier3`

**Summary:** Predicts IAB Tier 3 categories for the provided content.
**Tags:** Classify

**Request Body:** `application/json`
**Schema:** (Same as `PredictRequest`)

**Request Example (cURL) - Travel itinerary blog:**
```bash
curl -X POST "https://prod.api.market/api/v1/quickpod/aiquick-classify/classify/tier3" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "text": "7-day Tokyo itinerary with food districts, shrines, and subway travel tips.",
    "url": "https://travel.example.com/tokyo-itinerary",
    "top_k": 3
  }'
```

**Response Example (200 OK):**
```json
{
  "tier": "tier3",
  "predictions": [
    {
      "label": "Travel Planning",
      "score": 0.91
    },
    {
      "label": "Asia Travel",
      "score": 0.85
    },
    {
      "label": "Urban Travel",
      "score": 0.78
    }
  ]
}
```
*(Example response manually generated based on schema for Tier 3)*

#### Predict across multiple tiers in one call

`POST /api/v1/quickpod/aiquick-classify/classify/unified`

**Summary:** Predicts IAB categories across multiple tiers (Tier 1, Tier 2, Tier 3) in a single request.
**Tags:** Classify

**Request Body:** `application/json`
**Schema:** (`MultiTierPredictRequest` extends `PredictRequest`)
```json
{
  "type": "object",
  "properties": {
    "text": { "type": "string", "nullable": true },
    "url": { "type": "string", "nullable": true },
    "domain": { "type": "string", "nullable": true },
    "title": { "type": "string", "nullable": true },
    "keywords": { "type": "string", "nullable": true },
    "top_k": { "type": "integer", "minimum": 1, "maximum": 20, "default": 3 },
    "tiers": {
      "type": "array",
      "items": { "type": "string", "enum": ["tier1", "tier2", "tier3"] },
      "nullable": true,
      "description": "Which tiers to predict, e.g. ['tier1', 'tier2']. If omitted, all available tiers will be predicted."
    }
  }
}
```

**Request Example (cURL) - Request all available tiers:**
```bash
curl -X POST "https://prod.api.market/api/v1/quickpod/aiquick-classify/classify/unified" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "text": "Cloud data warehouse platform for analytics and machine learning workloads.",
    "domain": "cloud-analytics.example",
    "top_k": 3
  }'
```

**Response Example (200 OK):**
```json
{
  "tiers": {
    "tier1": [
      {
        "label": "Business",
        "score": 0.89
      }
    ],
    "tier2": [
      {
        "label": "Finance",
        "score": 0.83
      }
    ],
    "tier3": [
      {
        "label": "Personal Finance",
        "score": 0.79
      }
    ]
  }
}
```

## Status Codes

A comprehensive list of HTTP status codes and their meanings for the IAB Content Classification API:

- **200 OK**: The request was successful, and the API returned the expected data. This is the standard success code for GET and POST requests.
- **400 Bad Request**: The request could not be understood or processed due to invalid syntax or parameters. Check your request body and query parameters for correctness.
- **401 Unauthorized**: Authentication failed because the API key (`x-api-market-key`) is either missing or invalid. Ensure you are including a valid API key in your request headers.
- **403 Forbidden**: Your API key is valid, but you do not have the necessary permissions to access the requested resource or perform the action.
- **404 Not Found**: The requested endpoint or resource does not exist. Verify the URL path and make sure it matches the documentation.
- **422 Unprocessable Entity**: The server understands the content type of the request entity, and the syntax of the request entity is correct, but it was unable to process the contained instructions. This often indicates a validation error with the input data.
- **429 Too Many Requests**: You have sent too many requests in a given amount of time. You should implement a retry-after mechanism or exponential backoff.
- **500 Internal Server Error**: An unexpected condition was encountered on the server. This is a generic error response, and the issue might be temporary.
- **503 Service Unavailable**: The service is temporarily unable to handle the request, often due to maintenance or overload. This could also indicate that an upstream classifier is unavailable or timed out. Retry the request after a short delay.

## Rate Limits

The API is subject to rate limits to ensure fair usage and optimal performance for all users. If you exceed the allocated rate limit, you will receive a `429 Too Many Requests` status code. It is recommended to implement exponential backoff and retry mechanisms in your client code to gracefully handle these situations. Contact support if you require higher rate limits for your application.

## Error Handling

Effective error handling is crucial for building robust applications with the IAB Content Classification API.

- **Interpret Error Responses:** Always check the HTTP status code of the API response. For non-200 responses, the API typically returns a JSON payload with more details about the error.
    ```json
    {
      "detail": "Invalid or missing proxy secret"
    }
    ```
    or for validation errors:
    ```json
    {
      "detail": [
        {
          "loc": [
            "body",
            "text"
          ],
          "msg": "field required",
          "type": "value_error.missing"
        }
      ]
    }
    ```
- **Common Errors:**
  - **401 Unauthorized:** Ensure your `x-api-market-key` header is present and contains a valid API key.
    - **422 Unprocessable Entity:** Review the request body against the endpoint's schema. Ensure all required fields are present and data types are correct. For classification requests, make sure at least one content input field (`text`, `url`, `domain`, `title`, `keywords`) is provided.
    - **503 Service Unavailable:** This can be a transient issue.
- **Retry Strategies:** For transient errors like `429 Too Many Requests` or `503 Service Unavailable`, implement an exponential backoff strategy. This involves retrying the request after increasing intervals of time, preventing your application from overwhelming the API during temporary outages or load spikes.

## FAQ

**What are IAB categories?**

IAB categories are a standardized taxonomy for classifying web content, commonly used in digital advertising for contextual targeting, content organization, and audience segmentation. They are structured in tiers, from broad (Tier 1) to more specific (Tier 3).

**What kind of content can I classify?**

You can classify various forms of web content, including articles, blog posts, product pages, news content, and publisher inventory. The API accepts URLs, raw text, titles, domains, or keywords as input.

**How accurate is the classification?**

The IAB Content Classification model is trained to provide high accuracy for web content. Predictions include a confidence score, allowing you to filter or prioritize results based on your required accuracy threshold.

**Does the API support multiple languages?**

The model is primarily optimized for English content. While it may provide predictions for other languages, performance might vary. For best results, provide English content.

**What happens if I provide multiple input types (e.g., both `url` and `text`)?**

The API will use the available information to make the most informed prediction. In cases of conflicting or redundant input, the model prioritizes based on internal heuristics to deliver the best result. Providing a URL allows the API to fetch content, but providing additional `text`, `title`, or `keywords` can augment the classification if the fetched content is minimal or less relevant.

**What is `top_k` and how should I use it?**

`top_k` determines the maximum number of predicted IAB categories returned in the response, ranked by score. If you only need the most relevant category, set `top_k` to 1. If you want to inspect a broader set of possibilities, you can increase it up to 20.

## Contact Us

If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello@magicapi.com.

Classify text into IAB Tier 1, 2 and 3 content categories, or call the unified endpoint for a single result. Built for ad targeting and analytics.

IAB Content Classification