Contextuals

This article describes services for reading, adding, and updating updating the contextuals.

Overview

A contextual is a business object that enables advertisers to target consumers by matching their interests and habits with a publisher’s content–that is, the context of the ad placement. The contextual specifies multiple parameters that identify both the consumer and the ad context.

Every contextual is defined by a taxonomy type that specifies the contextual categories that may define the contextual. A contextual category may specify a special area of interest (Arts and Entertainment, Automotive, Home and Garden), contexts to avoid i.e. brand safety (Alcohol, Drugs, Firearms), or the quality of the context (Home Page, Video Size, Ad Count).

Endpoint

/traffic/contextuals

Resources

Contextual Object

The Contextual object contains the following fields:

Field Description Data Type
id Specifies the contextual ID. integer
name Specifies the name of the contextual. string
taxonomyType

Specifies the taxonomy provider. Valid values include:

  • IAB - Specifies an IAB contextual.
  • 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_MEDIA_QUALITY - Specifies an IAS Media Quality contextual. Requires an additional role.
  • IAS_CONTEXTUAL - Specifies an IAS contextual.
  • PEER39 - Specifies a Peer39 contextual. Requires an additional role.
string
accountId

Specifies the advertiser ID.

To learn more, see Advertisers.

integer
categories

Specifies an array of Category objects identified by categoryId.

To learn more, see Categories Object.

array
updatedAt A read-only field that shows the last updated timestamp. string

Categories Object

The categories array contains the following fields:

Field Description Data Type
categoryId Specifies the category ID. integer

Example Payload

{
  "categories": [
    {
      "categoryId": 2
    },
    {
      "categoryId": 22
    }
  ]
}

Read Contextual

Get data for a specific contextual.

GET /traffic/contextuals/{id}

Parameters

Table 56 Read Contextual Parameters
Parameter Parameter Type Description Data Type Required
id path Specifies the contextual ID. integer Y

Example Request URL

GET https://dspapi.admanagerplus.yahoo.com/traffic/contextuals/45067

Example Response

{
  "response": {
    "taxonomyType": "IAB",
    "id": 45067,
    "accountId": 1356341,
    "name": "contextual_update_test",
    "updatedAt": "2017-09-22T04:25:00Z",
    "categories": [
      {
        "id": 135759,
        "categoryId": 2
      },
      {
        "id": 135760,
        "categoryId": 22
      }
    ]
  },
  "errors": null,
  "timeStamp": "2017-09-22T04:37:53Z"
}

Read Contextuals

Get a filtered list of contextuals.

GET /traffic/contextuals?accountId={accountId}&query={query}&page={page}&limit={limit}&sort={sort}&dir={dir}

The response will be a list of matching contextuals.

Parameters

The API takes the following parameters:

Table 57 Read Contextuals Parameters
Parameter Parameter Type Description Data Type Required
accountId query Specifies the advertiser ID. integer Y
query query

Specifies the search term.

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

string N
page query Specifies the page number. integer N
limit query Specifies the total number of items to return. Maximum allowed value is 100. integer N
sort query Specifies the column to sort by. string N
dir query

Specifies the sort direction. Allowed values:

  • ASC: data is sorted in ascending order.
  • DESC: data is sorted in decending order.
string N

Example Request URL

GET https://dspapi.admanagerplus.yahoo.com/traffic/contextuals?accountId=1356341&query=test&page=1&limit=2

Example Response

{
  "response": [
    {
      "taxonomyType": "IAB",
      "id": 45067,
      "accountId": 1356341,
      "name": "contextual_update_test",
      "updatedAt": "2017-09-22T04:25:00Z",
      "categories": [
        {
          "id": 135759,
          "categoryId": 2
        },
        {
          "id": 135760,
          "categoryId": 22
        }
      ]
    },
    {
      "taxonomyType": "DOUBLE_VERIFY",
      "id": 45068,
      "accountId": 1356341,
      "name": "dv_test_1",
      "updatedAt": "2017-09-22T04:29:24Z",
      "categories": [
        {
          "id": 135762,
          "categoryId": 50260081
        }
      ]
    }
  ],
  "errors": null,
  "timeStamp": "2017-09-22T04:33:26Z"
}

Update Contextual

Update an existing contextual.

PUT /traffic/contextuals/{id}

Parameters

The Contextual id is specified in the url path. All other fields are specified in the body of the application/json payload.

Parameter Parameter Type Description Data Type Required
id path Specifies the contextual ID. integer Y
name body Specifies the name of the contextual. string Y
taxonomyType body

Specifies the taxonomy provider. Valid values include:

  • IAB - Specifies an IAB contextual.
  • 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_MEDIA_QUALITY - Specifies an IAS Media Quality contextual. Requires an additional role.
  • IAS_CONTEXTUAL - Specifies an IAS contextual.
  • PEER39 - Specifies a Peer39 contextual. Requires an additional role.
string Y
accountId body

Specifies the advertiser ID.

To learn more, see Advertisers.

integer Y
categories body

Specifies an array of contexual categories.

To learn more, see Categories Object.

string Y

Example Request URL

PUT https://dspapi.admanagerplus.yahoo.com/traffic/contextuals/45067

Example Request Body

{
  "accountId": 1356341,
  "name": "contextual_update_test",
  "taxonomyType": "IAB",
  "categories": [
    {
      "categoryId": 14
    }
  ]
}

Example Response

{
  "response": {
    "taxonomyType": "IAB",
    "id": 45067,
    "accountId": 1356341,
    "name": "contextual_update_test",
    "updatedAt": "2017-09-22T04:25:00Z",
    "categories": [
      {
        "id": 135759,
        "categoryId": 2
      },
      {
        "id": 135760,
        "categoryId": 22
      },
      {
        "id": 135761,
        "categoryId": 14
      }
    ]
  },
  "errors": null,
  "timeStamp": "2017-09-22T04:24:59Z"
}

Create Contextual

Create a new contextual.

POST /traffic/contextuals

Parameters

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

Parameter Parameter Type Description Data Type Required
name body Specifies the name of the contextual. string Y
taxonomyType body

Specifies the taxonomy provider. Valid values include:

  • IAB - Specifies an IAB contextual.
  • 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_MEDIA_QUALITY - Specifies an IAS Media Quality contextual. Requires an additional role.
  • IAS_CONTEXTUAL - Specifies an IAS contextual.
  • PEER39 - Specifies a Peer39 contextual. Requires an additional role.
string Y
accountId body

Specifies the advertiser ID.

To learn more, see Advertisers.

integer Y
categories body

Specifies an array of contexual categories.

To learn more, see Categories Object.

string Y

Example Request URL

POST /traffic/contextuals

Example Request Body

{
  "accountId": 1356341,
  "name": "iab_test_1",
  "taxonomyType": "IAB",
  "categories": [
    {
      "categoryId": 2
    },
    {
      "categoryId": 22
    }
  ]
}

Example Response

{
  "response": {
    "taxonomyType": "IAB",
    "id": 45067,
    "accountId": 1356341,
    "name": "iab_test_1",
    "updatedAt": "2017-09-22T04:12:01Z",
    "categories": [
      {
        "id": 135757,
        "categoryId": 2
      },
      {
        "id": 135758,
        "categoryId": 22
      }
    ]
  },
  "errors": null,
  "timeStamp": "2017-09-22T04:12:00Z"
}

Delete Contextual

The |traffic| does not support deletion of contextuals.

Read Contextual Categories

Get categories of taxonomy providers for the specified taxonomyType.

GET /traffic/contextuals/categories/{taxonomyType}

Parameters

The API takes a single parameter:

Table 58 Read Contextual Categories Parameters
Parameter Parameter Type Description Data Type Required
taxonomyType path

Specifies the taxonomy provider. Valid values include:

  • IAB - Specifies an IAB contextual.
  • 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_MEDIA_QUALITY - Specifies an IAS Media Quality contextual. Requires an additional role.
  • IAS_CONTEXTUAL - Specifies an IAS contextual.
  • PEER39 - Specifies a Peer39 contextual. Requires an additional role.
string Y

Example Request URL

GET https://dspapi.admanagerplus.yahoo.com/traffic/contextuals/categories/IAB

Example Response (Partial)

{
  "response": [
    {
      "id": 1,
      "description": "Arts & Entertainment",
      "parentCategoryId": 0,
      "level": 1,
      "children": [
        {
          "id": 101,
          "description": "Books & Literature",
          "parentCategoryId": 1,
          "level": 2
        },
        {
          "id": 102,
          "description": "Celebrity Fan/Gossip",
          "parentCategoryId": 1,
          "level": 2
        }
      ]
    },
    {
      "id": 2,
      "description": "Automotive",
      "parentCategoryId": 0,
      "level": 1,
      "children": [
        {
          "id": 201,
          "description": "Auto Parts",
          "parentCategoryId": 2,
          "level": 2
        }
      ]
    }
  ],
  "errors": null,
  "timeStamp": "2017-07-17T18:00:12Z"
}