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.

Search keyword audiences can be defined at the seat level or at the advertiser level.

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

Endpoint

You can read, update, and create search keyword audiences using the following endpoint:

/traffic/audiences/srt
  • Use the GET method to read existing search keyword audiences. To retrieve seat-level audiences, you must specify the search keyword audience id in the path of the URL. To retrieve advertiser-level audiences, you must specify both the advertiser’s accountId and the search keyword audience’s id.
  • Use the PUT method to update existing search keyword audiences.
  • Use the POST method to add new search keyword audiences.

Resource

The search keyword audience (srt) object is defined by the following fields:

Table 66 srt Object Fields
Name Description Type
id Specifies the ID of the search keyword audience. integer
name Specifies the name of the search keyword audience. string
accountId

Specifies an advertiser ID.

To learn more, see /traffic/advertiser/index.

If null, the srt is a seat-level search keyword audience.

integer
retentionDays

Specifies the recency of the keywords used to define the search keyword audience measured in days from the current date.

  • ONE
  • TWO
  • THREE
  • FOUR
  • FIVE
  • SIX
  • SEVEN
  • FIFTEEN
  • THIRTY
string
status

Specifies the status of the search keyword audience.

  • ACTIVE (DEFAULT VALUE)

  • INACTIVE

    Note: Oath automatically deactivates Oath Ad Platforms DSP search keyword audiences that have not been used for 90 days.

string
matchType

Specifies the site list type.

  • EXACT (DEFAULT VALUE) - Match only the keywords that are exactly the same.
  • BROAD - Expand the keyword seed list by generating new keyword phrases that are semantically similar. For example, if the keyword is running machine, the expansion algorithm will automatically generate keywords such as elliptical trainer, nordictrack, and treadmill.
string
broadOptimizationType

Specifies the optimization method used to expand the seed list if the matchType value is BROAD.

  • CLICKS_CONVERSATIONS: Optimizes for click and conversation performance.
  • REACH: Optimizes for reach by aggressively generating semantically similar keywords.

By default all new and all existing broad-match audiences optimize for clicks and conversions.

string
keywords

Specifies an array of keywords.

Includes Yahoo Search users who have searched the Internet using the specified keywords.

array
excludeKeywords

Specifies an array of keywords.

Excludes Yahoo Search users who have searched the Internet using the specified keywords.

Note: To remove an existing value, specify an empty array.

array
createdAt (Read-Only) Specifies the time the audience was created. number

Read Seat-Level Search Keyword Audiences

Retrieves audience data for a specific seat-level search keyword audience.

GET /traffic/audiences/srt/{id}

The platform returns the specified search keyword audience.

Parameters

The resource takes a single parameter specified in the path of the endpoint URL:

Table 67 Read Seat-Level Search Keyword Audiences
Name Type Description Data Type Required
id path Specifies the search keyword audience ID. integer Y

Example Request

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

Example Response

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

Read Advertiser-Level Search Keyword Audiences

Retrieves the specified advertiser-level search keyword audience.

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

The response returns audience data for the specified advertiser-level search keyword audience.

Parameters

The resource takes two parameters:

Table 68 Read Advertiser-Level Search Keyword Audiences
Name Type Description Data Type Required
id path Specifies the audience ID. integer Y
accountId query Specifies the advertiser accoun ID. integer Y

Example Request

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

Example Response

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

Update Search Keyword Audiences

Updates an existing search keyword audience.

PUT /traffic/audiences/srt/{id}

The same endpoint enables you to update seat-level and advertiser-level search keyword audiences. To update an advertiser-level search keyword audience, you must specify an advertiser accountId parameter in the payload.

Partial updates are supported; parameters that are not passed or passed as null are ignored.

Table 69 Update Search Keyword Audiences
Name Type Description Data Type Required
id path Specifies the audience ID. integer Y
accountId body

Specifies the advertiser account ID.

[1]Required to update an advertiser-level search keyword audience.
integer Y [1]
name body Specifies the name of the search keyword audience. string N
retentionDays body

Specifies the recency of the keywords used to define the search keyword audience measured in days from the current date.

  • ONE
  • TWO
  • THREE
  • FOUR
  • FIVE
  • SIX
  • SEVEN
  • FIFTEEN
  • THIRTY
string N
status body

Specifies the status of the search keyword audience.

  • ACTIVE (DEFAULT VALUE)
  • INACTIVE
string N
matchType body

Specifies the site list type.

  • EXACT (DEFAULT VALUE) - Match only the keywords that are exactly the same.
  • BROAD - Expand the keyword seed list by generating new keyword phrases that are semantically similar.
string N
broadOptimizationType body

Specifies the optimization method used to expand the seed list if the matchType value is BROAD.

  • CLICKS_CONVERSATIONS: Optimizes for click and conversation performance.
  • REACH: Optimizes for reach by aggressively generating semantically similar keywords.
[2]Required if the matchType value is BROAD.
string Y [2]
keywords body Specifies an array of keywords. Use this to include people who search for specific keywords. array Y
excludeKeywords body Specifies an array of keywords. Use this to exclude people who search for certain keywords. To remove an existing value, specify an empty array. array Y

Example Request (Seat-Level)

Updates are specified in the body of the application/json payload:

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

Example Response (Seat-Level)

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

Example Payload (Advertiser-Level)

{
  "name": "TestSegment_TR7507",
  "retentionDays": "SEVEN",
  "keywords": [
    "keyword1",
    "keyword2"
  ],
  "status": "ACTIVE",
  "accountId": 1356341
}

Example Response (Advertiser-Level)

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

Create Search Keyword Audiences

Creates a new search keyword audience (srt object).

POST /traffic/audiences/srt

Parameters

Table 70 Create Search Keyword Audiences
Name Type Description Data Type Required
id path Specifies the audience ID. integer Y
name body Specifies the name of the search keyword audience. string Y
accountId query

Specifies the advertser ID associated with the search keyword audience. If no accountId is specified, the search keyword audiience is defined at the seat level.

To learn more about advertiser account IDs, see /traffic/advertiser/index.

integer N
retentionDays body

Specifies the recency of the keywords used to define the search keyword audience measured in days from the current date.

  • ONE
  • TWO
  • THREE
  • FOUR
  • FIVE
  • SIX
  • SEVEN
  • FIFTEEN
  • THIRTY
string Y
status body

Specifies the status of the search keyword audience.

  • ACTIVE (DEFAULT VALUE)
  • INACTIVE
string N
matchType body

Specifies the site list type.

  • EXACT (DEFAULT VALUE) - Match only the keywords that are exactly the same.
  • BROAD - Expand the keyword seed list by generating new keyword phrases that are semantically similar.
string N
accountId body

Specifies an advertiser ID.

Note: To create a seat-level audience, set to null.

integer N
keywords body Specifies an array of keywords. Use this to include people who search for specific keywords. array Y
excludeKeywords body Specifies an array of keywords. Use this to exclude people who search for certain keywords. To remove an existing value, specify an empty array. array Y

Example Request

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

Example Payload (Seat-Level)

The payload adds a new srt object that uses BROAD matching optimization to define the search audience list.

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

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

Example Payload (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": "SEVEN"
  },
  "errors": null,
  "timeStamp": "2017-08-10T03:46:38Z"
}

Delete Search Keyword Audiences

Audience deletion is not supported by the API.