Contextuals

This article describes services for reading, adding, and updating 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

Use the following HTTP methods:

  • Use the GET method to view an existing contextual.

  • Use the POST method to create a new contextual.

  • Use the PUT method to update an existing contextual.

Resources

Contextual

The Contextual object contains the following fields:

Field

Description

Data Type

Create

Update

id

Specifies the contextual ID.

integer

N/A

Required

name

Specifies the name of the contextual.

string

Required

Optional

taxonomyType

Specifies the taxonomy provider. Valid values include:

  • 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

Required

Optional

accountId

Specifies the advertiser ID.

To learn more, see Advertisers.

integer

Required

Required

categories

Specifies an array of Category objects identified by categoryId.

To learn more, see Categories Object.

array

Required

Optional

updatedAt

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

string

N/A

N/A

Categories Object

The categories array contains the following fields:

Field

Description

Data Type

categoryId

Specifies the category ID.

integer

Example Request Body

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

Read Contextual Categories

Get categories of taxonomy providers for the specified taxonomyType.

GET /traffic/contextuals/categories/{taxonomyType}

Parameters

The API takes a single parameter:

Parameter

Parameter Type

Description

Data Type

Required

taxonomyType

path

Specifies the taxonomy provider. Valid values include:

  • 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

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

Read Contextual

Read a specific contextual.

GET /traffic/contextuals/{id}

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

Read a filtered list of contextuals.

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

All of the accepted parameters are query parameters.

Parameters

Parameter

Description

Data Type

Required

accountId

Specifies the advertiser ID.

integer

Y

query

Specifies the search term.

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

string

N

page

Specifies the page number.

integer

N

limit

Specifies the total number of items to return. Maximum allowed value is 100.

integer

N

sort

Specifies the column to sort by.

string

N

dir

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

Create Contextual

Create a new contextual.

POST /traffic/contextuals

Parameters

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

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

Update Contextual

Update an existing contextual.

PUT /traffic/contextuals/{id}

Partial updates are supported; values of supported fields that are not in the payload remain unchanged.

Parameters

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

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

Delete Contextual

The DSP Traffic API does not support deletion of contextuals.