Keyword¶
Overview¶
The Keyword object specifies the search keyword phrase that you would like to target. Using this service, you can set and manage keyword match types as well as keyword-level bids. Please note that bids that are set at the keyword level override bids that are set at higher levels.
Fields¶
The Keyword object contains the following fields:
Name |
Description |
Type |
Add |
Update |
---|---|---|---|---|
|
The ID of the advertiser associated with the keyword. This field cannot be updated. |
long |
Required |
Optional (Read-Only) |
|
Keywords can carry bids that override any bids set at the ad group level. See the example representation below for an example on how to set a bid at the keyword level. In order to clear a bid for a given keyword, pass in an empty bid value when updating the keyword. |
|
Optional |
Optional |
|
Specifies whether to exclude ( |
boolean |
Required |
Optional |
|
The ID of the keyword. |
long |
N/A |
Required |
|
The serving matching algorithm. Supported match types: For positive keywords (
For negative keywords (
|
enum |
Required |
Optional. Note that |
|
The ID of the ad group the keyword belongs to. If it is a negative keyword ( |
long |
Required |
Required |
|
The type of parent. For a keyword object, this value is typically ADGROUP. It can also be CAMPAIGN for negative keywords ( |
enum |
Required |
Required |
|
The status of the keyword. Valid input values are:
See keyword level statuses table below for more details on this field. Note that |
enum |
Required |
Optional |
|
The actual keyword. Maximum limit is 255 characters. Please note that value for an existing keyword cannot be updated. In order to update this field, a new keyword must be created. Therefore this field will be ignored if passed when attempting to update a keyword. |
string |
Required |
Optional |
|
The values that are substituted at serve time within the Ad “ |
|
Optional |
Optional |
|
The landing page URL is the web address that a user is sent to after clicking on the ad triggered by the keyword. A URL set at the keyword level overrides the landing URL set at the ad level. Maximum limit is 2048 characters. |
|
Optional |
Optional |
Keyword level statuses¶
Any new keyword undergoes automatic quality review. If no issues are raised, the keyword can start running less than a minute after its creation. A keyword can be in one of the following statuses:
Status |
Description |
---|---|
|
The keyword is running. |
|
The keyword is paused and can be re-activated. |
|
The keyword has been flagged for review and is being reviewed by the editorial team. This can take up to 24 hours. Once the review is complete, the keyword can either become |
|
The keyword was declined due to policy violations; further information is available in the Ad Manager UI. |
|
Set the status of the keyword to |
Important
Any changes to either the landing urls or the text attributes of the following entities – Ad, Keywords and Sitelinks – will result in a state transition to ON_HOLD for the purposes of editorial review. Note that our SLA is 24 hours; however, in practice, most ads are re-activated in 1 to 2 hours. Please plan your edits and sync logic, accordingly.
Endpoint¶
Resource URI
https://api.admanager.yahoo.com/v1/rest/keyword/
Example Representations¶
Keyword
{
"value": "Your keyword 1",
"id": 282782226512,
"status": "ACTIVE",
"advertiserId": 11610,
"parentType": "ADGROUP",
"parentId": 7237162494,
"landingUrl": "https://www.yahoo.com",
"exclude": "FALSE",
"bidSet": {
"id": null,
"bids": [
{
"priceType": "CPC",
"value": 2,
"channel": "SEARCH"
}
]
},
"matchType": "EXACT"
"adParamValues": null
}
Keyword Array
[
{
"value": "Your keyword 1",
"id": 282782226512,
"status": "ACTIVE",
"advertiserId": 11610,
"parentType": "ADGROUP",
"parentId": 7237162494,
"landingUrl": "https://www.yahoo.com",
"exclude": "FALSE",
"bidSet": {
"id": null,
"bids": [
{
"priceType": "CPC",
"value": 2,
"channel": "SEARCH"
}
]
},
"matchType": "EXACT",
"adParamValues": null
},
{
"value": "Your keyword 2",
"id": 282782226513,
"status": "ACTIVE",
"advertiserId": 11610,
"parentType": "ADGROUP",
"parentId": 7237162494,
"landingUrl": "https://www.yahoo.com",
"exclude": "FALSE",
"bidSet": {
"id": null,
"bids": [
{
"priceType": "CPC",
"value": 1.5,
"channel": "SEARCH"
}
]
},
"matchType": "EXACT",
"adParamValues": null
}
]
Keyword Response
{
"errors": null,
"response": {
"value": "Your keyword 1",
"id": 282782226512,
"status": "ACTIVE",
"advertiserId": 11610,
"parentType": "ADGROUP",
"parentId": 7237162494,
"landingUrl": "https://www.yahoo.com",
"exclude": "FALSE",
"bidSet": {
"id": null,
"bids": [
{
"priceType": "CPC",
"value": 2,
"channel": "SEARCH"
}
]
},
"matchType": "EXACT"
"adParamValues": null
}
}
Operations¶
Read specific keyword data
Method: To retrieve data for a specific keyword, make a GET call with the id parameter.
For example:
https://api.admanager.yahoo.com/v1/rest/keyword/282782226512
Response: The keyword associated with the given ID.
{
"errors": null,
"response": {
"value": "Your keyword 1",
"id": 282782226512,
"status": "ACTIVE",
"advertiserId": 11610,
"parentType": "ADGROUP",
"parentId": 7237162494,
"landingUrl": "https://www.yahoo.com",
"exclude": "FALSE",
"bidSet": {
"id": null,
"bids": [
{
"priceType": "CPC",
"value": 2,
"channel": "SEARCH"
}
]
},
"matchType": "EXACT",
"adParamValues": null
}
}
Example: You can also make a GET call and pass in multiple IDs. Please note that when you pass multiple IDs, all other filters besides id will be ignored:
https://api.admanager.yahoo.com/v1/rest/keyword/?id=282782226512&id=282782226513
Response: The keywords associated with the given IDs:
{
"errors": null,
"response": [
{
"value": "Your keyword 1",
"id": 282782226512,
"status": "ACTIVE",
"advertiserId": 11610,
"parentType": "ADGROUP",
"parentId": 7237162494,
"landingUrl": "https://www.yahoo.com",
"exclude": "FALSE",
"bidSet": {
"id": null,
"bids": [
{
"priceType": "CPC",
"value": 2,
"channel": "SEARCH"
}
]
},
"matchType": "EXACT",
"adParamValues": null
},
{
"value": "Your keyword 2",
"id": 282782226513,
"status": "ACTIVE",
"advertiserId": 11610,
"parentType": "ADGROUP",
"parentId": 7237162494,
"landingUrl": "https://www.yahoo.com",
"exclude": "FALSE",
"bidSet": {
"id": null,
"bids": [
{
"priceType": "CPC",
"value": 1.5,
"channel": "SEARCH"
}
]
},
"matchType": "EXACT",
"adParamValues": null
}
}
}
Read data for filtered list of keywords
Method: To retrieve data for a filtered list of keywords, make a GET call with the following parameters:
Name |
Description |
Type |
Required? |
---|---|---|---|
|
The exclude flag. This is either true for negative keywords or false for positive keywords. |
string |
Optional |
|
The maximum number of rows to retrieve. |
int |
Optional |
|
The ID of the parent to filter the keywords by. |
long |
Yes |
|
The type of parent to filter by. Valid values are:
|
enum |
Yes |
|
The start index or the first element to retrieve. |
int |
Optional |
|
The keyword value. |
enum |
Optional |
Example: GET call to fetch negative keywords for a given ad group:
https://api.admanager.yahoo.com/v1/rest/keyword/?parentId=46756&parentType=ADGROUP&exclude=true
Response: The response will be the list of keywords that match the given filter:
{
"errors": null,
"response": {
"value": "Negative keyword",
"id": 282782,
"status": "ACTIVE",
"advertiserId": 11610,
"parentType": "ADGROUP",
"parentId": 46756,
"landingUrl": "https://www.yahoo.com",
"exclude": "TRUE",
"bidSet": null,
"matchType": "EXACT",
"adParamValues": null
}
}
Example: You can also make a GET call to fetch keywords filtered by multiple ad group IDs:
https://api.admanager.yahoo.com/v1/rest/keyword&parentType=ADGROUP&parentId=1&parentId=2
Response: The list of keywords that match the given filter:
{
"errors": null,
"response": [
{
"value": "Keyword from one ad group",
"id": 282782226512,
"status": "ACTIVE",
"advertiserId": 11610,
"parentType": "ADGROUP",
"parentId": 1,
"landingUrl": "https://www.yahoo.com",
"exclude": "FALSE",
"bidSet": {
"id": null,
"bids": [
{
"priceType": "CPC",
"value": 2,
"channel": "SEARCH"
}
]
},
"matchType": "EXACT",
"adParamValues": null
},
{
value": "Another keyword from the ad group",
"id": 282782226513,
"status": "ACTIVE",
"advertiserId": 11610,
"parentType": "ADGROUP",
"parentId": 1,
"landingUrl": "https://www.yahoo.com",
"exclude": "FALSE",
"bidSet": {
"id": null,
"bids": [
{
"priceType": "CPC",
"value": 1.5,
"channel": "SEARCH"
}
]
},
"matchType": "EXACT",
"adParamValues": null
},
{
"value": "Keyword from the other ad group",
"id": 282782226514,
"status": "ACTIVE",
"advertiserId": 11610,
"parentType": "ADGROUP",
"parentId": 2,
"landingUrl": null,
"exclude": "FALSE",
"bidSet": null,
"matchType": "BROAD",
"adParamValues": null
}
]
}
Update existing keywords
Method: To update existing keywords, make a PUT call with one or more keyword objects. The result will be the list of updated keywords. For example, to update a bid for multiple keywords:
PUT https://api.admanager.yahoo.com/v1/rest/keyword/
Data passed
[
{
"id": 282782226512,
"bidSet": {
"bids": [
{
"priceType": "CPC",
"value": 2,
"channel": "SEARCH"
}
]
}
},
{
"id": 282782226513,
"bidSet": {
"bids": [
{
"priceType": "CPC",
"value": 1.5,
"channel": "SEARCH"
}
]
}
}
]
Example response
{
"errors": null,
"response": [
{
"value": "Your keyword 1",
"id": 282782226512,
"status": "ACTIVE",
"advertiserId": 11610,
"parentType": "ADGROUP",
"parentId": 7237162494,
"landingUrl": "https://www.yahoo.com",
"exclude": "FALSE",
"bidSet": {
"id": null,
"bids": [
{
"priceType": "CPC",
"value": 2,
"channel": "SEARCH"
}
]
},
"matchType": "EXACT",
"adParamValues": null
},
{
"value": "Your keyword 2",
"id": 282782226513,
"status": "ACTIVE",
"advertiserId": 11610,
"parentType": "ADGROUP",
"parentId": 7237162494,
"landingUrl": "https://www.yahoo.com",
"exclude": "FALSE",
"bidSet": {
"id": null,
"bids": [
{
"priceType": "CPC",
"value": 1.5,
"channel": "SEARCH"
}
]
},
"matchType": "EXACT",
"adParamValues": null
}
]
}
Create a new keyword
Method: To create new keywords, make a POST call with one or more keyword objects. The response will be the newly created keywords.
For example:
POST https://api.admanager.yahoo.com/v1/rest/keyword/
Data passed
[
{
"advertiserId": 11610,
"parentType": "ADGROUP",
"parentId": 7237162494,
"value": "newkeyword1",
"matchType": "EXACT",
"exclude": "FALSE",
"status": "ACTIVE",
"bidSet": {
"bids": [
{
"priceType": "CPC",
"value": 3,
"channel": "SEARCH"
}
]
}
},
{
"advertiserId": 11610,
"parentType": "ADGROUP",
"parentId": 7237162494,
"value": "newkeyword2",
"matchType": "EXACT",
"exclude": "FALSE",
"status": "ACTIVE",
"bidSet": {
"bids": [
{
"priceType": "CPC",
"value": 2.5,
"channel": "SEARCH"
}
]
}
}
]
Example response
{
"errors": null,
"response": [
{
"value": "newkeyword1",
"id": 289344782063,
"status": "ACTIVE",
"advertiserId": 11610,
"parentType": "ADGROUP",
"parentId": 7237162494,
"landingUrl": null,
"exclude": "FALSE",
"bidSet": {
"id": null,
"bids": [
{
"priceType": "CPC",
"value": 3,
"channel": "SEARCH"
}
]
},
"matchType": "EXACT",
"adParamValues": null
},
{
"value": "newkeyword2",
"id": 289344782064,
"status": "ACTIVE",
"advertiserId": 11610,
"parentType": "ADGROUP",
"parentId": 7237162494,
"landingUrl": null,
"exclude": "FALSE",
"bidSet": {
"id": null,
"bids": [
{
"priceType": "CPC",
"value": 2.5,
"channel": "SEARCH"
}
]
},
"matchType": "EXACT",
"adParamValues": null
}
]
}
Create a new negative keyword
Method: To create a new keyword, make a POST call with the keyword object and set exclude=TRUE. Supported match types for negative keywords are either EXACT or PHRASE. You can set negative keywords at both the ad group and the campaign levels. Indicate the level at which the negative keyword should be set using the parentType attribute:
POST https://api.admanager.yahoo.com/v1/rest/keyword/
Data passed
{
"advertiserId": 11610,
"parentType": "CAMPAIGN",
"parentId": 334418145,
"value": "negativekeywordCampaign",
"matchType": "EXACT",
"exclude": "TRUE",
"status": "ACTIVE"
}
Example response
{
"errors": null,
"response": {
"value": "negativekeywordCampaign",
"id": 289344787160,
"status": "ACTIVE",
"advertiserId": 11610,
"parentType": "CAMPAIGN",
"parentId": 334418145,
"landingUrl": null,
"exclude": "TRUE",
"bidSet": null,
"matchType": "EXACT",
"adParamValues": null
}
}
Delete a keyword
Method: To delete a keyword, make a PUT call with the keyword object. The following parameters are required:
Field |
Description |
---|---|
|
The ID of the keyword to delete. |
|
The status of the keyword set to |
For example:
PUT https://api.admanager.yahoo.com/v1/rest/keyword/
Data passed
{
"id": 289344787160,
"status": "DELETED"
}
Example response
{
"errors": null,
"response": {
"value": "negativekeywordCampaign",
"id": 289344787160,
"status": "DELETED",
"advertiserId": 11610,
"parentType": "CAMPAIGN",
"parentId": 334418145,
"landingUrl": null,
"exclude": "TRUE",
"bidSet": null,
"matchType": "EXACT",
"adParamValues": null
}
}
AdParamValue Object
The following parameters are supported.
Parameter |
Description |
Required? |
---|---|---|
|
The index for params (1, 2, and 3), which identifies which placeholder must use which replacement text. Valid values are 1, 2, and 3. |
Yes |
|
The substitution text to display on the ad. The character limit for the insertionText of paramIndex=1 is 1022. The character limit for the insertionText of paramIndex=2 and paramIndex=3 is 70 each. |
Yes |
Example
This example shows how to set adParam1 and adParam2 when updating a keyword:
PUT https://api.admanager.yahoo.com/v1/rest/keyword/
Data passed
{
"id": 289344782063,
"adParamValues": [
{
"paramIndex": 1,
"insertionText": "dynamic text for param1"
},
{
"paramIndex": 2,
"insertionText": "dynamic text for param2"
}
]
}
Example response
{
"errors": null,
"response": {
"value": "newkeyword1",
"id": 289344782063,
"status": "ACTIVE",
"advertiserId": 11610,
"parentType": "ADGROUP",
"parentId": 7237162494,
"landingUrl": null,
"exclude": "FALSE",
"bidSet": {
"id": null,
"bids": [
{
"priceType": "CPC",
"value": 3,
"channel": "SEARCH"
}
]
},
"matchType": "EXACT",
"adParamValues": [
{
"paramIndex": 2,
"insertionText": "dynamic text for param2"
},
{
"paramIndex": 1,
"insertionText": "dynamic text for param1"
}
]
}
}