Contextuals Targeting

This article describes resources that enable you to read and define contextual targeting.

Overview

If you have created contextuals for an advertiser, you can set up targeting to serve or exclude ads based on the contextual.

The Oath Ad Platforms DSP supports CONTEXTUALS targeting for lines serving display and video ads.

To learn more, see /traffic/contextual.

Endpoint

/traffic/lines/{id}/targeting
  • A GET request enables you to view contextuals targeted by the specified line.
  • A POST request enables you to target contextuals with the specified line.

Resources

Targeting

The targeting resource is the standard Oath Ad Platforms DSP resource for targeting consumers based on their profiles, behaviors, and ad content.

This resource comprises multiple fields that enable you to specify line targeting across many types of targets including the SEGMENT, EXCHANGES, and CONTEXTUALS target types.

The targeting resource is defined by the following CONTEXTUALS targeting type-specific fields:

Field Description Data Type
contextuals

Specifies contextuals to target or exclude from targeting.

To learn more, see Contextuals Payload Object.

array
contextualsIncluded A read-only array that identifies contextuals targeted by the line. array
contextualsExcluded A read-only array that identifies contextuals not targeted by the line. array

Note

For a complete list of targeting resource fields, see Targeting Object.

Contextuals Payload Object

Field Description Data Type
contextualsIncluded Targeted contextuals which are marked as Included. Refer to Contextuals. array
contextualsExcluded Targeted contextuals which are marked as Excluded. Refer to Contextuals. array
addedDoubleVerify Double Verify Contextual IDs to target. array
addedIAB

IAB Contextual IDs to target.

Note: Must provide a value for excludeIAB to indicate if the contextuals should be included or excluded.

array
excludeIAB

Indicates if the added IAB Contextual IDs are to be excluded or included.

  • true - All IDs in the addedIAB field will be excluded from targeting.
  • false - All IDs in the addedIAB field will be included in targeting.
boolean
addedIASBrandSafety IAS Brand Safety Contextual IDs to target. array
addedIASMediaQuality

IAS Media Quality Contextual IDs to target.

Note: Must provide a value for excludeIASMediQuality to indicate if the contextuals should be included or excluded.

array
excludeIASMediaQuality

Indicates if the added IAS Media Quality Contextual IDs are to be excluded or included.

  • If true, all IDs in the addedIASMediaQuality field will be excluded from targeting.
  • If``false``, all IDs in the addedIASMediaQuality field will be included in targeting.
boolean
excludeIASContextual

Indicates if the added IAS Contextual IDs are to be excluded or included.

  • If true, all IDs in the addedIASContextual field will be excluded from targeting.
  • If false, all IDs in the addedIASContextual field will be included in targeting.
boolean
addedIASContextual

IAS Contextual IDs to target.

Note: Must provide a value for excludeIASContextual to indicate if the contextuals should be included or excluded.

array
excludeIASContextual

Indicates if the added IAS Contextual IDs are to be excluded or included.

  • If true, all IDs in the addedIASContextual field will be excluded from targeting.
  • If false, all IDs in the addedIASContextual field will be included in targeting.
boolean
removed Contextual IDs to be removed from targeting. array
clearAll

Indicates if all existing targeted contextuals should be removed. By default, false.

  • If true, remove all targeted Contextuals. This will disable CONTEXTUALS targeting.
  • If false, do not remove any targeted Contextuals.
boolean
removed Contextual IDs to be removed from targeting. array

Read Targeting Contextuals

Returns list of contextuals that are available for targeting.

GET /traffic/targeting/contextuals?lineId={lineId}&taxonomyType={taxonomyType}&query={query}

Parameters

The resource accepts the following parameters:

Parameter Parameter Type Description Data Type Required?
lineId query Specifies the line ID. integer Y
taxonomyType query

Specifies the taxonomy type.

  • IAB - IAB Contextual.

  • DOUBLE_VERIFY - Double Verify Brand Safety.

    Note: Requires additonal role.

  • IAS_BRAND_SAFETY - IAS Brand Safety.

    Note: Requires additonal role.

  • IAS_MEDIA_QUALITY - IAS Media Quality.

    Note: Requires additonal role.

  • IAS_CONTEXTUAL - IAS Contextual.

    Note: Requires additonal role.

string Y
query query

Specifies the search term.

Use URL encoding conventions (i.e. a space should be replaced should be replaced with a + or %20).

string Y

Example Request

The response will be a list of matching contextuals.

Example Response

{
  "response": [
    {
      "taxonomyType": "IAB",
      "id": "43188",
      "name": "contextual_update_test"
    },
    {
      "taxonomyType": "IAB",
      "id": "41843",
      "name": "test-iab"
    }
  ],
  "errors": null,
  "timeStamp": "2017-07-27T21:30:07Z"
}

Add/Update Target Contextuals

Adds or updates contextual to the line for targeting.

POST traffic/lines/{id}/targeting/

Parameters

The line ID is specified in the path of the URL. All other parameters are specified in the body of the application/json payload.

Parameter Parameter Type Description Data Type Required?
id path Specifies the line ID. integer Y
contextuals body

Specifies an array of contexutals to target or exclude from targeting.

To learn more, see Contextuals Payload Object.

array Y
types body

Specifies an array of targeting types to target.

To target contextuals, the CONTEXTUALS targeting type must be enabled.

To learn more, see Targeting Types.

array Y

Example Request

The line ID is specified in the path of the resource endpoint:

POST traffic/lines/365277/targeting/

All other parameters are specified in the body of the application/json payload.

{
  "contextuals": {
    "clearAll": false,
    "excludeIAB": false,
    "addedDoubleVerify": [
      41842
    ],
    "addedIAB": [
      41848,
      41843
    ],
    "removed": []
  },
  "types": [
    {
      "name": "CONTEXTUALS",
      "isTargeted": true
    }
  ]
}