🚧

New categories

This page is about standalone category objects, introduced in broadpeak.io on December 14th. Previously, categories where indirectly defined within slots.

Personalizing content with broadpeak.io requires adding query parameters to manifest requests, so that the platform knows the "audience" or "category" of the request.

"Audience" is the SCTE-224 terminology, while "category" is the broadpeak.io terminology, but this represents the same concept, i.e. a group of end-users who is watching the content and who should have it personalized the same way.

In the case of Dynamic Ad Insertion, the query parameters are specified by the Ad Server. This is the Ad Server that will decide which ads must be inserted, based on the query parameters that it understands. Please refer to this page for more information.

But for the Content Replacement and Virtual Channel applications, it is broadpeak.io that will decide which content must be inserted. This is where categories come into play.

The REST API

You may define a category with the following endpoint: https://api.broadpeak.io/v1/categories, documented in our API reference.

In broadpeak.io, categories are defined by their name and their id. Both must be unique.

A subcategory is a key/value pair. At this time the only supported key is "zip", which represents a US postal zip code or any country's postal code.

A category may be empty or contain a list of subcategories.

Here is an example of an empty category:

{
    "name": "teenagers"
}

Here is an example of a category with two zip codes

{
    "name": "arlington-va",
    "subcategories": [
        {
            "key": "zip",
            "value": "20301"
        },
        {
            "key": "zip",
            "value": "22207"
        }
    ]
}

🚧

Warning

The same zip value cannot be included in two different categories.

A category is a convenient way to define a static mapping between many zip codes and their geographical area. For example, in the US, there are more than 40,000 zip codes. By contrast, there are just a little over 200 Designated Market Areas. A DMA includes an average of 200 zip codes, sometimes many more. A blackout slot typically targets just one, or a few DMAs. Listing all the zip codes of a DMA in every blackout slot would be tedious. Instead, you can create as many categories as there are DMAs in your geographical footprint, assign the zip codes once and for all, then only specify which DMA is targeted by a slot, thanks to its associated category.

To specify a category in a slot, you first need to define it as explained above. Then you need to obtain its id from the response of the creation request or of a get request. And then you create a Content Replacement or Virtual Channel slot that references this id.

Please see our API reference for more information.

The ESNI API

It is also possible to use the ESNI API to manage categories.

To create or edit a category, use the "Audience" element with an "id" attribute which corresponds to the category name.

For example:

<Media href="YourServiceName">
    <MediaPoint id="YourMediaPointName" matchTime="2022-11-18T16:00:00Z" expectedDuration="PT0H1M">
        <Apply>
            <Policy id="1">
                <ViewingPolicy id="1">
                   <Audience id="arlington-va">
                        <audience:zip>20301</audience:zip>
                        <audience:zip>22207</audience:zip>
                        <audience:zip>22350</audience:zip>                     
                    </Audience>
                    <action:Content>ESPN_Alt_1</action:Content>
                </ViewingPolicy>
            </Policy>
        </Apply>
    </MediaPoint>
</Media>

This will create or update a category named "arlington-va" containing 3 zip codes.

At this time it is not possible to simply reference an existing category. Stay tuned for this feature.

Please see this page for more information about the ESNI API.

Using categories in manifest requests

Specifying the category in a manifest request can be done in one of two ways:

• Directly with the category name, for example in

https://stream.broadpeak.io/<service_id>/path/index.mpd?category=arlington-va

• Using one of the category's zip codes, such as

https://stream.broadpeak.io/<service_id>/path/index.mpd?zip=22207

In this second example, broadpeak.io will find the category that includes this zip code, then apply the slot(s) that target this category.

🚧

Warning

Both category names and zip codes are standard character strings. When using them as query parameters you must URL-encode them so that they only contain "safe" ASCII characters. To avoid issues with URL encoding and decoding it is safer to use only URL-allowed characters in category names and zip codes.