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

addedIAB

IAB Contextual IDs to target.

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

array

excludeIAB

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

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

  • false - (Default Value) All IDs in the addedIAB 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

addedGrapeshotContextual

Grapeshot Contextual IDs to target.

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

array

excludeGrapeshotContextual

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

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

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

boolean

addedGrapeshotBrandSafety

Grapeshot Brand Safety IDs to target.

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

array

excludeGrapeshotBrandSafety

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

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

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

boolean

addedGrapeshotLanguage

Grapeshot Language IDs to target.

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

array

excludeGrapeshotLanguage

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

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

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

boolean

addedGrapeshotCustom

Grapeshot Custom IDs to target.

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

array

excludeGrapeshotCustom

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

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

  • false - (Default Value) All IDs in the addedGrapeshotCustom 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.

  • IAB - Specifies an IAB contextual.

  • 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.

  • GRAPESHOT_BRAND_SAFETY - Specifies a Grapeshot Brand Safety contextual. Requires an additional role.

  • GRAPESHOT_CONTEXTUAL - Specifies a Grapeshot Contextual contextual. Requires an additional role.

  • GRAPESHOT_LANGUAGE - Specifies a Grapeshot Language contextual. Requires an additional role.

  • GRAPESHOT_CUSTOM - Specifies a Grapeshot 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=IAB&query=test

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 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