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’s account 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 by ID

Retrieves data for the specified contextual.

GET /traffic/contextuals/{id}

Parameters

The API takes the following parameters:

Table 89 Read Contextual Categories by Query Parameters
Parameter Parameter Type Description Data Type Required
id path Specifies the contextual ID. integer Y

The response will be the Contextual associated with the given ID.

Example Request

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

Returns a filtered list of contextuals.

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

The response will be a list of matching contextuals.

Parameters

The API takes the following parameters:

Table 90 Read Contextual Categories by Query Parameters
Parameter Parameter Type Description Data Type Required
accountId query Specifies the advertiser account ID. integer Y
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. Valid values: asc, desc string N
query query Specifies a search term. Use URL encoding conventions (i.e. a space should be replaced with a + or %20). string N

Example Request

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

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 Contextuals

Updates the specified contextual as identified by its ID.

PUT /traffic/contextuals/{id}

Parameters

The API takes the following parameters:

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’s account 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

The contextuals ID is specified in the endpoint path.

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

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

{
  "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 Contextuals

Creates a new contextual.

POST /traffic/contextuals

Parameters

The API takes the following parameters:

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’s account 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

POST /traffic/contextuals

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

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

Contextual deletion is not supported by the API.

Read Contextual Categories

Retrieves categories of taxonomy providers for the specified taxonomyType.

GET /traffic/contextuals/categories/{taxonomyType}

Parameters

The API takes a single parameter:

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

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