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

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

Fields

The Contextual object contains the following fields:

Name Description Type Add Update
id ID of the contextual. integer N/A Required
name Name of the contextual. text Required Required
taxonomyType

Taxonomy provider type.

  • IAB - IAB Contextual.
  • DOUBLE_VERIFY - Double Verify Brand Safety. Note: Requires additonal role.
  • IAS_BRAND_SAFETY - IAS Brand Safety. Note: Requires additonal role.
  • IAS_MEDIA_QUALITY - IAS Media Quality. Note: Requires additonal role.
  • IAS_CONTEXTUAL - IAS Contextual. Note: Requires additonal role.
text Required Required
accountId Advertiser/account ID. Refer to Advertisers. integer Required Required
categories Contextual categories. Refer to categories. array Required Required
updatedAt (Read-Only) Last updated timestamp. datetime N/A N/A

categories object

Each element in the categories object contains the following fields:

Name Description Type Add Update
id ID of the record. integer N/A N/A
categoryId Taxonomy category ID. integer Required Required

Example Payload

{
  "categories": [
    {
      "categoryId": 102
    },
    {
      "categoryId": 105
    }
  ]
}

Read Contextual (Single)

To retrieve data for a specific Contextual, make a GET call with the id parameter.

GET https://dspapi.admanagerplus.yahoo.com/traffic/contextuals/{id}
Name Description Type Required?
id 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": 106
      },
      {
        "id": 135760,
        "categoryId": 102
      },
      {
        "id": 135761,
        "categoryId": 217
      }
    ]
  },
  "errors": null,
  "timeStamp": "2017-09-22T04:37:53Z"
}

Read Contextuals (Filtered)

To retrieve a filtered list of Contextuals, make a GET call with the supported query parameters.

GET https://dspapi.admanagerplus.yahoo.com/traffic/contextuals?accountId={accountId}&page={page}&limit={limit}&sort={sort}&dir={dir}&query={query}
Name Description Type Required?
accountId Account or Advertiser ID integer Y
page Page number integer N
limit Total number of items to return. Maximum allowed value is 100. integer N
sort Column to sort by text N
dir Sort direction. Valid values: asc, desc text N
query Search term. Use url encoding conventions (i.e. a space should be replaced with a + or %20). text N

The response will be a list of matching Contextuals.

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": 106
        },
        {
          "id": 135760,
          "categoryId": 102
        },
        {
          "id": 135761,
          "categoryId": 217
        }
      ]
    },
    {
      "taxonomyType": "DOUBLE_VERIFY",
      "id": 45068,
      "accountId": 1356341,
      "name": "dv_test_1",
      "updatedAt": "2017-09-22T04:29:24Z",
      "categories": [
        {
          "id": 135762,
          "categoryId": 26
        }
      ]
    }
  ],
  "errors": null,
  "timeStamp": "2017-09-22T04:33:26Z"
}

Update Contextual

To update an existing Contextual, make a PUT call with a payload body and id parameter. The response will be the updated Contextual.

PUT https://dspapi.admanagerplus.yahoo.com/traffic/contextuals/{id}
Name Description Type Required?
id Contextual ID integer Y

Example Request

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

Example Payload

{
  "accountId": 1356341,
  "name": "contextual_update_test",
  "taxonomyType": "IAB",
  "categories": [
    {
      "categoryId": 102
    },
    {
      "categoryId": 106
    },
    {
      "categoryId": 217
    }
  ]
}

Example Response

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

Create Contextual

To create a new Contextual, make a POST call with a payload body. The response will be the newly created Contextual.

Example Request

POST https://dspapi.admanagerplus.yahoo.com/traffic/contextuals

Example Payload

{
  "accountId": 1356341,
  "name": "iab_test_1",
  "taxonomyType": "IAB",
  "categories": [
    {
      "categoryId": 102
    },
    {
      "categoryId": 107
    }
  ]
}

Example Response

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

Delete Contextual

Contextual deletion is not supported by the API.

Read Contextual Categories

To retrieve categories of various taxonomy providers, make a GET call with the taxonomyType parameter.

GET https://dspapi.admanagerplus.yahoo.com/traffic/contextuals/categories/{taxonomyType}
Name Description Type Required?
taxonomyType

Taxonomy provider.

  • IAB - IAB Contextual
  • DOUBLE_VERIFY - Double Verify Brand Safety
  • IAS_BRAND_SAFETY - IAS Brand Safety
  • IAS_MEDIA_QUALITY - IAS Media Quality
  • IAS_CONTEXTUAL - IAS Contextual
text 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"
}