Learn about Curated Packages

The curators.curatedPackages resource lets you programmatically create and manage packages of publisher inventory that you curate on behalf of media planners.

Curated packages let you group select inventory that meets specific targeting criteria — such as device types, geography, and data segments — and assign a curator fee that is charged when buyers win impressions targeted by the curated package.

Understand key concepts

Before starting your integration, review the fields and settings that define how curated packages operate:

Control who can access your curated packages

Your curated packages are only accessible to media planners that you have explicitly granted access using the CuratedPackage.accessSettings field. You must populate the accessSettings field when the curated package is created.

You can use the mediaPlanners.list method to view a list of media planners that are eligible to be specified in the CuratedPackage.accessSettings.allowlistedMediaPlanners field.

Configure the inventory your curated package targets

You can use the CuratedPackage.targeting field to specify the inventory that your curated package targets. The targeting field is populated with the PackageTargeting object, which supports targeting criteria such as device type, creative format, and geographic location.

You can also specify customized targeting with the CuratedPackage.targeting.includedDataSegments field. The includedDataSegments field lets you target data segments that you or other curation partners manage.

Understand targeting logic

Values in repeated fields are processed using a logical OR, meaning that an impression that is applicable to any of the specified values is a match. Each field is processed using a logical AND, meaning that all of the specified fields must match a given impression for the curated package to appear in the corresponding bid request.

The following example creates a curated package with a CuratedPackage.targeting field populated to target a combination of device types and data segments:

{
  "includedDeviceTypes": [
    "DEVICE_TYPE_PHONE",
    "DEVICE_TYPE_PERSONAL_COMPUTER"
  ],
  "includedDataSegments": [
    "curators/123456/dataSegments/8765",
    "curators/123456/dataSegments/8172"
  ]
}

The following table shows whether the curated package from the example targets an impression, where each row is a distinct impression:

Device Type Data Segment IDs Does curated package target?
DEVICE_TYPE_PERSONAL_COMPUTER 8765, 8172 Yes
DEVICE_TYPE_PHONE 8172, 4321 Yes
DEVICE_TYPE_PHONE 9182 No
DEVICE_TYPE_CONNECTED_TV 4321, 9182 No

Signal the value of your curated package

You must set a curation fee using the CuratedPackage.fee union field when creating a curated package, and can only populate one of the fee types supported by the CuratedPackage object—for example, the feeCpm field. The total curation fee for a given impression is the sum of the curated package fee, and the fees of any targeted data segments that are applicable to the impression.

You can also signal the value of impressions that your curated package targets by setting the CuratedPackage.floorPriceCpm field, which can influence the floor specified to bidders in Real-Time Bidding. The floor price sent to bidders is the higher value when comparing the floor price you specify in the floorPriceCpm field, and the sum of the publisher floor price and total curation fee.

The following table provides examples of how the effective floor sent in the bid request for the curated package is calculated:

Publisher floor (CPM) Total curation fee (CPM) Curated package floor (CPM) Effective floor (CPM)
$7 $2 $10 $10
$4 $1 $4 $5

Control serving of your curated package

A curated package can be in one of the following states:

  • ACTIVE: The curated package is active. Subscribed media planners can receive Real-time Bidding bid requests that contain the curated package's ID for the targeted inventory.
  • INACTIVE: The curated package is inactive. The curated package's ID doesn't appear in Real-time bidding bid requests, even for subscribed media planners.

Next steps

To learn more about workflows you can perform with the curatedPackages resource, review the following content: