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:

Read Seat-Level Audiences

Retrieves audience data for a specific seat-level search keyword audience. A seat-level audience is available to every advertiser in a seat.

GET /traffic/audiences/srt/{id}

Parameters

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

Table 66 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": 7
  },
  "errors": null,
  "timeStamp": "2017-08-09T18:06:19Z"
}

Read Advertiser-Level Audiences

Returns data for a single advertiser-level search keyword audience.

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

Parameters

The resource takes two parameters:

Table 67 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": 7
  },
  "errors": null,
  "timeStamp": "2017-08-11T18:08:37Z"
}

Update Search Keyword Audiences

Updates an existing search keyword audience.

PUT /traffic/audiences/srt/{id}

Note

To update an advertiser-level audience, you must provide an accountId query parameter.

The resource supports partial updates for all fields except keywords and excludeKeywords; fields that are either not passed or passed as null will be ignored during update.

Parameters

The resource supports the following parameters:

Table 68 Update 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 N
retentionDays body Specifies the recency of the keywords used to define the search keyword audience measured in days from the current date: 1, 2, 3, 4, 5, 6, 7 (Default Value), 15, 30. integer N
status body

Specifies the status of the search keyword audience.

  • ACTIVE (Default Value)
  • INACTIVE
string N
accountId query

Specifies the advertiser account ID.

[1]Required to update an advertiser-level audience.
integer Y [1]
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_CONVERSIONS: 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 N [2]
keywords body Specifies an array of keywords. Use this to include people who search for specific keywords. array N
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 N

Example Request (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 (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 Audiences

Creates a new advertiser-level or seat-level search keyword audience.

POST /traffic/audiences/srt

Parameters

Table 69 Create Search Keyword Audience Parameters
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
retentionDays body Specifies the recency of the keywords used to define the search keyword audience measured in days from the current date: 1, 2, 3, 4, 5, 6, 7 (Default Value), 15, 30. integer N
status body

Specifies the status of the search keyword audience.

  • ACTIVE (Default Value)
  • INACTIVE
string N
accountId body

Specifies the advertiser/account ID associated with the segment.

[3]Required to create an advertiser-level audience.
integer Y [3]
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_CONVERSIONS: Optimizes for click and conversation performance.
  • REACH: Optimizes for reach by aggressively generating semantically similar keywords.
[4]Required if the matchType value is BROAD.
string Y [4]
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 N

Example Request

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

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

Delete Search Keyword Audiences

Audience deletion is not supported by the API.