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 Yahoo DSP supports CONTEXTUALS targeting for lines serving display and video ads.

To learn more, refer to Contextuals.

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 Yahoo DSP resource for targeting consumers based on their profiles, behaviors, and ad content.

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

Parameter

Parameter Type

Definition

Data Type

Required

id

path

Specifies the line ID.

integer

Y

contextuals

body

Specifies contextuals to target or exclude from targeting.

To learn more, refer to Contextuals Payload Object.

array

Y

contextualsIncluded

body

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

For detailed field reference, refer to Contextual.

array

N/A

contextualsExcluded

body

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

For detailed field reference, refer to Contextual.

array

N/A

types

body

Specifies an array of targeting types to update, enable, or disable.

CONTEXTUALS targeting type must be specified to apply the changes.

To learn more, refer to Targeting Types.

array

Y

Note

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

Contextuals Payload Object

Field

Description

Data Type

addedDoubleVerifyAuthenticBrandSafety

Double Verify Authentic Brand Safety Contextual IDs to target.

Note: This type of contextual can only be targeted (included), it can not be blocked (excluded).

array

addedDoubleVerifyBrandSafety

Double Verify Brand Safety Contextual IDs to target.

Note: Specified contextuals are targeted (included) by default. To block (exclude) them instead, set excludeDoubleVerifyBrandSafety to true.

array

excludeDoubleVerifyBrandSafety

Indicates if the added Double Verify Brand Safety Contextual IDs are to be targeted (included) or blocked (excluded).

  • true - All IDs in the addedDoubleVerifyBrandSafety field will be blocked (excluded).

  • false - (Default Value) All IDs in the addedDoubleVerifyBrandSafety field will be targeted (included).

boolean

addedIASBrandSafety

IAS Brand Safety Contextual IDs to target.

Note: This type of contextual can only be targeted (included), it can not be blocked (excluded).

array

addedIASContextual

IAS Contextual IDs to target.

Note: Specified contextuals are targeted (included) by default. To block (exclude) them instead, set excludeIASContextual to true.

array

excludeIASContextual

Indicates if the added IAS Contextual IDs are to be targeted (included) or blocked (excluded).

  • true - All IDs in the addedIASContextual field will be blocked (excluded).

  • false - (Default Value) All IDs in the addedIASContextual field will be targeted (included).

boolean

addedIASMediaQuality

IAS Media Quality Contextual IDs to target.

Note: Specified contextuals are targeted (included) by default. To block (exclude) them instead, set excludeIASMediaQuality to true.

array

excludeIASMediaQuality

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

  • true - All IDs in the addedIASMediaQuality field will be blocked (excluded).

  • false - (Default Value) All IDs in the addedIASMediaQuality field will be targeted (included).

boolean

addedPeer39BrandSafety

Peer39 Brand Safety Contextual IDs to target.

Note: Specified contextuals are targeted (included) by default. To block (exclude) them instead, set excludePeer39BrandSafety to true.

array

excludePeer39BrandSafety

Indicates if the added Peer39 Brand Safety Contextual IDs are to be targeted (included) or blocked (excluded).

  • true - All IDs in the addedPeer39BrandSafety field will be blocked (excluded).

  • false - (Default Value) All IDs in the addedPeer39BrandSafety field will be targeted (included).

boolean

addedPeer39Contextual

Peer39 Content Contextual IDs to target.

Note: Specified contextuals are targeted (included) by default. To block (exclude) them instead, set excludePeer39Contextual to true.

array

excludePeer39Contextual

Indicates if the added Peer39 Content Contextual IDs are to be targeted (included) or blocked (excluded).

  • true - All IDs in the addedPeer39Contextual field will be blocked (excluded).

  • false - (Default Value) All IDs in the addedPeer39Contextual field will be targeted (included).

boolean

addedPeer39PageLanguage

Peer39 Page Language Contextual IDs to target.

Note: Specified contextuals are targeted (included) by default. To block (exclude) them instead, set excludePeer39PageLanguage to true.

array

excludePeer39PageLanguage

Indicates if the added Peer39 Page Language Contextual IDs are to be targeted (included) or blocked (excluded).

  • true - All IDs in the addedPeer39PageLanguage field will be blocked (excluded).

  • false - (Default Value) All IDs in the addedPeer39PageLanguage field will be targeted (included).

boolean

addedPeer39PageQuality

Peer39 Page Quality Contextual IDs to target.

Note: Specified contextuals are targeted (included) by default. To block (exclude) them instead, set excludePeer39PageQuality to true.

array

excludePeer39PageQuality

Indicates if the added Peer39 Page Quality Contextual IDs are to be targeted (included) or blocked (excluded).

  • true - All IDs in the addedPeer39PageQuality field will be blocked (excluded).

  • false - (Default Value) All IDs in the addedPeer39PageQuality field will be targeted (included).

boolean

addedPublisherDeclared

Publisher Declared Contextual IDs to target.

Note: Specified contextuals are targeted (included) by default. To block (exclude) them instead, set excludePublisherDeclared to true.

array

excludePublisherDeclared

Indicates if the added Publisher Declared Contextual IDs are to be targeted (included) or blocked (excluded).

  • true - All IDs in the addedPublisherDeclared field will be blocked (excluded).

  • false - (Default Value) All IDs in the addedPublisherDeclared field will be targeted (included).

boolean

addedOracleAdvertisingContextual

Oracle Advertising Contextual IDs to target.

Note: Specified contextuals are targeted (included) by default. To block (exclude) them instead, set excludeOracleAdvertisingContextual to true.

array

excludeOracleAdvertisingContextual

Indicates if the added Oracle Advertising Contextual IDs are to be targeted (included) or blocked (excluded).

  • true - All IDs in the addedOracleAdvertisingContextual field will be blocked (excluded).

  • false - (Default Value) All IDs in the addedOracleAdvertisingContextual field will be targeted (included).

boolean

addedOracleAdvertisingBrandSafety

Oracle Advertising Brand Safety Contextual IDs to target.

Note: Specified contextuals are targeted (included) by default. To block (exclude) them instead, set excludeOracleAdvertisingBrandSafety to true.

array

excludeOracleAdvertisingBrandSafety

Indicates if the added Oracle Advertising Brand Safety Contextual IDs are to be targeted (included) or blocked (excluded).

  • true - All IDs in the addedOracleAdvertisingBrandSafety field will be blocked (excluded).

  • false - (Default Value) All IDs in the addedOracleAdvertisingBrandSafety field will be targeted (included).

boolean

addedOracleAdvertisingLanguage

Oracle Advertising Language Contextual IDs to target.

Note: Specified contextuals are targeted (included) by default. To block (exclude) them instead, set excludeOracleAdvertisingLanguage to true.

array

excludeOracleAdvertisingLanguage

Indicates if the added Oracle Advertising Language Contextual IDs are to be targeted (included) or blocked (excluded).

  • true - All IDs in the addedOracleAdvertisingLanguage field will be blocked (excluded).

  • false - (Default Value) All IDs in the addedOracleAdvertisingLanguage field will be targeted (included).

boolean

addedOracleAdvertisingCustom

Oracle Advertising Custom Contextual IDs to target.

Note: Specified contextuals are targeted (included) by default. To block (exclude) them instead, set excludeOracleAdvertisingCustom to true.

array

excludeOracleAdvertisingCustom

Indicates if the added Oracle Advertising Custom Contextual IDs are to be targeted (included) or blocked (excluded).

  • true - All IDs in the addedOracleAdvertisingCustom field will be blocked (excluded).

  • false - (Default Value) All IDs in the addedOracleAdvertisingCustom field will be targeted (included).

boolean

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

Get a list of contextuals that are available for targeting.

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

All of the accepted parameters are query parameters.

Parameters

Parameter

Description

Data Type

Required

lineId

Specifies the line ID.

integer

Y

taxonomyType

Specifies the taxonomy type.

  • DOUBLE_VERIFY_AUTHENTIC_BRAND_SAFETY - Specifies a Double Verify Authentic Brand Safety contextual. Requires an additional role.

  • DOUBLE_VERIFY - Specifies a Double Verify Brand Safety contextual. Requires an additional role.

  • IAS_BRAND_SAFETY - Specifies an IAS Brand Safety contextuals. Requires an additional role.

  • IAS_CONTEXTUAL - Specifies an IAS contextual.

  • IAS_MEDIA_QUALITY - Specifies an IAS Media Quality contextual. Requires an additional role.

  • PEER39_BRAND_SAFETY - Specifies a Peer39 Brand Safety contextual. Requires an additional role.

  • PEER39_CONTEXTUAL - Specifies a Peer39 Content contextual. Requires an additional role.

  • PEER39_PAGE_LANGUAGE - Specifies a Peer39 Page Language contextual. Requires an additional role.

  • PEER39_PAGE_QUALITY - Specifies a Peer39 Page Quality contextual. Requires an additional role.

  • PUBLISHER_DECLARED - Specifies a Publisher Declared contextual.

  • ORACLE_ADVERTISING_BRAND_SAFETY - Specifies an Oracle Advertising Brand Safety contextual. Requires an additional role.

  • ORACLE_ADVERTISING_CONTEXTUAL - Specifies an Oracle Advertising Contextual contextual. Requires an additional role.

  • ORACLE_ADVERTISING_LANGUAGE - Specifies an Oracle Advertising Language contextual. Requires an additional role.

  • ORACLE_ADVERTISING_CUSTOM - Specifies an Oracle Advertising Custom contextual. Requires an additional role.

string

Y

query

Specifies the search term.

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

string

Y

Example Request URL

GET https://dspapi.admanagerplus.yahoo.com/traffic/targeting/contextuals?lineId=365277&taxonomyType=PUBLISHER_DECLARED&query=test

Example Response

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

Add/Update Contextuals Targeting

Add or update contextual targets for the specified line.

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.

Example Request URL

POST https://dspapi.admanagerplus.yahoo.com/traffic/lines/365277/targeting/

Example Request Body

{
  "id": 365277,
  "contextuals": {
    "clearAll": false,
    "addedDoubleVerifyAuthenticBrandSafety": [
      65733
    ],
    "removed": []
  },
  "types": [
    {
      "name": "CONTEXTUALS",
      "isTargeted": true
    }
  ]
}

Example Response

{
  "response": {
    "types": [
      {
        "name": "CONTEXTUALS",
        "isTargeted": true
      }
    ],
    "contextualsIncluded": [
      {
        "id": 65733,
        "accountId": 306442,
        "name": "dv-abs",
        "updatedAt": "2019-10-11T23:00:47Z",
        "categories": [
          {
            "id": 184132,
            "categoryId": 50571280
          },
          {
            "id": 184131,
            "categoryId": 50571278
          }
        ],
        "taxonomyType": "DOUBLE_VERIFY_AUTHENTIC_BRAND_SAFETY"
      }
    ]
  },
  "errors": null,
  "timeStamp": "2019-10-15T00:54:14.401Z"
}

Additional Resources