Search Keyword Audiences

This article describes resources and services you can use to view, create, and update search keyword audiences.

Overview

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

Yahoo DSP defines a search keyword audience using an array of keywords (words and phrases searched) and excludeKeywords (words and keywords not searched). The search audience includes Yahoo Search users whose search histories meet both criteria.

Hierarchy

You can define a Search Keyword audience at the seat level or the advertiser level.

  • Seat-level audiences are shared by every advertiser in the seat.

  • Advertiser-level audiences are specific to a single advertiser.

Endpoint

/traffic/audiences/srt

Use the following HTTP methods:

  • Use the GET method to view 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.

Resources

The Search Keyword audience object contains the following fields:

Field

Description

Data Type

Create

Update

id

Specifies the audience ID.

integer

N/A

Required

name

Specifies the name of the audience.

string

Required

Optional

status

Specifies the current status of the audience.

Allowed values:

  • ACTIVE: you can target the audience.

  • INACTIVE: you cannot target the audience.

Defaults to ACTIVE if you don’t specify a value.

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

string

Optional

Optional

accountId

Specifies the advertiser ID.

If you specify an advertiser ID, you can only use the audience for that advertiser’s campaigns.

To learn more, refer to Advertisers.

integer

Required for advertiser-level audiences; do not use for seat-level audiences.

Required for advertiser-level audiences; do not use for seat-level audiences.

retentionDays

Specifies the recency of the date a user must have searched for a keyword to be included in the audience (in days, counting back from the current date).

Allowed values: 1, 2, 3, 4, 5, 6, 7, 15, 30.

Defaults to 7 if you don’t specify a value.

integer

Optional

Optional

matchType

Specifies the keyword match type.

Allowed values:

  • EXACT: Match only the keywords that are exactly the same.

  • BROAD: Expands the keyword list by generating additional similar keywords.

Note: For broad matches, if the keyword is treadmill, the expansion algorithm might generate keywords like elliptical trainer and nordic track.

Yahoo DSP supports broad match keywords for U.S. English and Traditional Chinese.

string

Optional

Optional

broadOptimizationType

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

Allowed values:

  • CLICKS_CONVERSIONS: Optimizes for click and conversation performance.

  • REACH: Optimizes for reach by generating semantically similar keywords.

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

string

Required if the matchType is BROAD.

Required if the matchType is BROAD.

keywords

Specifies an array of keywords. Use to include people who search for certain keywords.

array

Required

Optional

excludeKeywords

Specifies an array of keywords. Use to exclude people who search for certain keywords.

To remove existing values, specify an empty array.

array

Optional

Optional

createdAt

A read-only field that specifies when the audience was created.

string

N/A

N/A

Read Audience

Read a specific search keyword audience.

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

Parameters

Parameter

Parameter Type

Description

Data Type

Required/Optional

id

path

Specifies the audience ID.

integer

Required

accountId

query

Specifies the advertiser ID.

integer

Required for advertiser-level audiences. Do not use for seat-level audiences.

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

Create Audience

Create a new search keyword audience.

POST /traffic/audiences/srt

Parameters

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

Update 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 that are not in the payload 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"
}

Delete Audience

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