Search Keyword Audiences

This article describes resources that enable you to read, create, and update search keyword audiences.

Overview

A search keyword audience is an audience that identifies Yahoo Search users based on their search history.

A search keyword audience is defined by an array of keywords (words and phrases searched) and a set of excludeKeywords (words and keywords not searched). A Yahoo Search user is included in the search audience provided that their search history meets both criteria.

Hierarchy

A Search Keyword audience can be defined at either the seat-level or advertiser-level.

  • Seat-level audiences are shared by every advertiser account in the seat.
  • Advertiser-level audiences are specific to a single advertiser account.

Endpoint

/traffic/audiences/srt
  • Use the GET method to read an existing search keyword audience.
  • Use the POST method to create a new search keyword audience.
  • Use the PUT method to update an existing search keyword audience.

Resource

The Search Keyword audience object contains the following fields:

Read Search Keyword Audience

Get data for a specific search keyword audience.

GET /traffic/audiences/srt/{id}?accountId={accountId}

Parameters

Table 59 Read Search Keyword Audience Parameters
Parameters Parameter Type Description Data Type Required
id path Specifies the audience ID. integer Y
accountId query

Specifies the advertiser ID.

[6]Required for advertiser-level audiences.
integer N [6]

Example Seat-Level Request URL

GET https://dspapi.admanagerplus.yahoo.com/traffic/audiences/srt/50299597

Example Seat-Level Response

{
  "response": {
    "matchType": "EXACT",
    "id": 50299597,
    "name": "TestSegment_TR46",
    "keywords": [
      "keyword1",
      "keyword2"
    ],
    "excludeKeywords": [
      "exclude_keyword1"
    ],
    "createdAt": "2017-08-09",
    "status": "ACTIVE",
    "retentionDays": 7
  },
  "errors": null,
  "timeStamp": "2017-08-09T18:06:19Z"
}

Example Advertiser-Level Request URL

GET https://dspapi.admanagerplus.yahoo.com/traffic/audiences/srt/50301215?accountId=1356341

Example Advertiser-Level Response

{
  "response": {
    "matchType": "EXACT",
    "id": 50301215,
    "name": "TestSegment_TR7507",
    "accountId": 1356341,
    "keywords": [
      "keyword1",
      "keyword2"
    ],
    "excludeKeywords": [
      "exclude_keyword1"
    ],
    "createdAt": "2017-08-11",
    "status": "ACTIVE",
    "retentionDays": 7
  },
  "errors": null,
  "timeStamp": "2017-08-11T18:08:37Z"
}

Update Search Keyword Audience

Update an existing search keyword audience.

PUT /traffic/audiences/srt/{id}

Partial updates are supported for all fields except keywords and excludeKeywords; values of supported fields which are not in the payload will remain unchanged.

Parameters

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

Example Request URL (Seat-Level)

PUT https://dspapi.admanagerplus.yahoo.com/traffic/audiences/srt/50300847

Example Request Body (Seat-Level)

{
  "name": "TestSegment_TR7508",
  "keywords": [
    "keyword124",
    "keyword2"
  ]
}

Example Response (Seat-Level)

{
  "response": {
    "matchType": "EXACT",
    "id": 50300847,
    "name": "TestSegment_TR7508",
    "keywords": [
      "keyword124",
      "keyword2"
    ],
    "excludeKeywords": [
      "exclude_keyword1"
    ],
    "createdAt": "2017-08-10",
    "status": "ACTIVE",
    "retentionDays": 7
  },
  "errors": null,
  "timeStamp": "2017-08-11T06:53:40Z"
}

Example Request URL (Advertiser-Level)

PUT https://dspapi.admanagerplus.yahoo.com/traffic/audiences/srt/50300835?accountId=1356341

Example Request Body (Advertiser-Level)

{
  "name": "TestSegment_TR7507",
  "status": "INACTIVE"
}

Example Response (Advertiser-Level)

{
  "response": {
    "matchType": "EXACT",
    "id": 50300835,
    "name": "TestSegment_TR7507",
    "accountId": 1356341,
    "keywords": [
      "keyword1",
      "keyword2"
    ],
    "createdAt": "2017-08-10",
    "status": "INACTIVE",
    "retentionDays": 7
  },
  "errors": null,
  "timeStamp": "2017-08-11T06:28:54Z"
}

Create Search Keyword Audience

Create a new search keyword audience.

POST /traffic/audiences/srt

Parameters

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

Example Request URL

POST https://dspapi.admanagerplus.yahoo.com/traffic/audiences/srt

Example Request Body (Seat-Level)

{
  "name": "NEW_SRT",
  "keywords": [
    "keyword1",
    "keyword2"
  ],
  "excludeKeywords": [
   "exclude_keyword1"
  ],
  "matchType": "BROAD",
  "broadOptimizationType": "REACH"
}

Example Response (Seat-Level)

{
  "response": {
    "matchType": "BROAD",
    "id": 50299597,
    "name": "NEW_SRT",
    "keywords": [
      "keyword1",
      "keyword2"
    ],
    "excludeKeywords": [
      "exclude_keyword1"
    ],
    "createdAt": "2017-08-09",
    "status": "ACTIVE",
    "broadOptimizationType": "REACH",
    "retentionDays": 7

  },
  "errors": null,
  "timeStamp": "2018-02-20T21:40:16Z"
}

Example Request Body (Advertiser-Level)

{
  "name": "TestSegment_TR52",
  "keywords": [
    "keyword1",
    "keyword2"
  ],
  "excludeKeywords": [
    "exclude_keyword1"
  ],
  "accountId": 1356341
}

Example Response (Advertiser-Level)

{
  "response": {
    "matchType": "EXACT",
    "id": 50300102,
    "name": "TestSegment_TR52",
    "accountId": 1356341,
    "keywords": [
      "keyword1",
      "keyword2"
    ],
    "excludeKeywords": [
      "exclude_keyword1"
    ],
    "createdAt": "2017-08-10",
    "status": "ACTIVE",
    "retentionDays": 7
  },
  "errors": null,
  "timeStamp": "2017-08-10T03:46:38Z"
}

Delete Search Keyword Audience

The DSP Traffic API does not support deletion of search keyword audiences.