Yahoo! Search Marketing

Enterprise Web Services > Version 5.2.0 > Marketing API reference

KeywordService

KeywordService provides operations for creating and managing keywords. A keyword is a search term that you bid on and is associated with an ad group.

Operations

addKeyword

Create a keyword.

Capability required: CampaignWrite
License command group: Marketing
Supported accounts: Web

Parameters

Parameter Data Type Description
keyword Keyword The new keyword.

Response

KeywordResponse - The response, which indicates if the operation succeeded or failed.

addKeywords

Create one or more keywords.

Capability required: CampaignWrite
License command group: Marketing
Supported accounts: Web

Parameters

Parameter Data Type Description
keywords Keyword[] A list of keyword objects.

Response

KeywordResponse[] - A list of responses, which indicate if the operations succeeded or failed.

Sample Code

copyKeyword

Copy the keyword (specified by keywordID) to the ad group (specified by adGroupID).

Capability required: CampaignWrite
License command group: Marketing
Supported accounts: Web

Parameters

Parameter Data Type Description
keywordID long The keyword ID.
destinationAdGroupID long The ad group ID.
newSponsoredSearchMaxBid double The Sponsored Search maximum bid for the keyword. (For this parameter, you may pass in the null value.)

Response

KeywordResponse - The response, which indicates if the operation succeeded or failed.

deleteKeyword

Delete the keyword (specified by keywordID).

Capability required: CampaignWrite
License command group: Marketing
Supported accounts: Web

Parameters

Parameter Data Type Description
keywordID long The keyword ID.

Response

BasicResponse - The response, which indicates if the operation succeeded or failed.

deleteKeywords

Delete one or more keywords (specified by the list of keywordIDs).

Capability required: CampaignWrite
License command group: Marketing
Supported accounts: Web

Parameters

Parameter Data Type Description
keywordIDs long[] A list of keyword IDs.

Response

BasicResponse[] - A list of responses, which indicate if the operations succeeded or failed.

getEditorialReasonsForKeyword

Return the editorial reason code for the keyword or updated keyword (specified by keywordID). Once you have the code, use the getEditorialReasonText operation to return the corresponding text.

Capability required: CampaignRead
License command group: Marketing
Supported accounts: Web

Parameters

Parameter Data Type Description
keywordID long The keyword ID.

Response

KeywordEditorialReasons - The editorial reason codes.

getEditorialReasonText

Return the editorial reason text for the editorial reason code (specified by editorialReasonCode) in a given language (specified by locale). The editorial reason text provides reasons why the keyword was rejected or suspended, and may also provide feedback to improve the quality of the keyword.

See also: Editorial Reason Text and Editorial Suggestion Text

Capability required: CampaignRead
License command group: AdvancedTools
Supported accounts: Web

Parameters

Parameter Data Type Description
editorialReasonCode int The editorial reason code.
locale string The locale is the language code plus the country code, separated by an underscore. The default locale is en_US for US English (see Market-Specific Values). Note that translations for some locales may not be available. (For this parameter, you may pass in the null string.)

Response

string - The editorial reason text.

getKeyword

Return the keyword (specified by keywordID).

Capability required: CampaignRead
License command group: Marketing
Supported accounts: Web

Parameters

Parameter Data Type Description
keywordID long The keyword ID.

Response

Keyword - The keyword.

getKeywordParticipationStatusByAdGroupId

Return the detailed participation status of the keywords for the ad group (specified by adGroupID)

Added in: Version 5.2.0
Capability required: Research
License command group: Marketing
Supported accounts: Web

Parameters

Parameter Data Type Description
adGroupID long The ad group ID.
startElement int The first element to be returned (0-based; if a value <= 0 is entered, will default to 0).
numElements int The number of elements to be returned (1000 maximum; if a value <=0 is entered, will default to 1000).

Response

KeywordParticipationStatus[] - A list of KeywordParticipationStatus for the specified ad group.

getKeywords

Return one or more keywords (specified by the list of keywordIDs).

Capability required: CampaignRead
License command group: Marketing
Supported accounts: Web

Parameters

Parameter Data Type Description
keywordIDs long[] A list of keyword IDs.

Response

Keyword[] - A list of keywords.

getKeywordsByAccountID

Return the keywords for the account (specified by accountID).

Capability required: CampaignRead
License command group: Marketing
Supported accounts: Web

Parameters

Parameter Data Type Description
accountID string The account ID.
includeDeleted boolean If true, include the deleted keywords.
startElement int The first element to be returned (0-based; if a value <= 0 is entered, will default to 0).
numElements int The number of elements to be returned (1000 maximum; if a value <=0 is entered, will default to 1000).

Response

Keyword[] - A list of keywords for the specified account.

getKeywordsByAdGroupByParticipatesInMarketplace

Return the keywords for the ad group (specified by adGroupID) that are or are not participating in the marketplace.

Deprecated: This method has been deprecated since 5.2.0. Use getKeywordParticipationStatusByAdGroupId instead.
Capability required: Research
License command group: Marketing
Supported accounts: Web

Parameters

Parameter Data Type Description
adGroupID long The ad group ID.
participatesInMarketplace boolean If true, return the ads that are participating in the marketplace.
If false, return the ads that are not participating in the marketplace.

Response

Keyword[] - A list of keywords for the specified ad group.

getKeywordsByAdGroupBySponsoredSearchBidStatus

Return the keywords in the ad group (specified by adGroupID) with the Sponsored Search bid status (specified by BidStatus).

Capability required: CampaignRead
License command group: Marketing
Supported accounts: Web

Parameters

Parameter Data Type Description
adGroupID long The ad group ID.
sponsoredSearchBidStatus BidStatus The bid status.

Response

Keyword[] - A list of keywords with the specified Sponsored Search bid status.

getKeywordsByAdGroupID

Return the keywords for the ad group (specified by adGroupID).

Capability required: CampaignRead
License command group: Marketing
Supported accounts: Web

Parameters

Parameter Data Type Description
adGroupID long The ad group ID.
includeDeleted boolean If true, include the deleted keywords.
startElement int The first element to be returned (0-based; if a value <=0 is entered, will default to 0).
numElements int The number of elements to be returned (1000 maximum; if a value <=0 is entered, will default to 1000).

Response

Keyword[] - A list of keywords for the specified ad group.

getKeywordsByAdGroupIDByEditorialStatus

Return the keywords with the indicated editorial status for the ad group (specified by adGroupID). Possible settings for "update" are:

update status Return
true Pending Return all updated keywords that are waiting for editorial review.
true Rejected Return all updated keywords that were rejected editorial review.
false Pending Return all keywords that are waiting for editorial review.
false Approved Return all keywords that are approved.
false Rejected Return all keywords that are rejected.
false Suspended Return all keywords that are suspended.

Capability required: CampaignRead
License command group: Marketing
Supported accounts: Web

Parameters

Parameter Data Type Description
adGroupID long The ad group ID.
update boolean True or false (see the table above).
status EditorialStatus The editorial status.
includeDeleted boolean If true, include the deleted keywords.

Response

Keyword[] - A list of keywords with the indicated editorial status for the specified ad group.

getKeywordsByAdGroupIDByStatus

Return the keywords with the indicated status for the ad group (specified by adGroupID).

Capability required: CampaignRead
License command group: Marketing
Supported accounts: Web

Parameters

Parameter Data Type Description
adGroupID long The ad group ID.
status KeywordStatus The keyword status.
startElement int The first element to be returned (0-based; if a value <=0 is entered, will default to 0).
numElements int The total number of elements to be returned (1000 maximum; if a value <=0 is entered, will default to 1000).

Response

Keyword[] - A list of keywords with the indicated status for the specified ad group.

getKeywordSponsoredSearchMaxBid

Return the maximum bid for Sponsored Search for the keyword (specified by keywordID).

Capability required: CampaignRead
License command group: Marketing
Supported accounts: Web

Parameters

Parameter Data Type Description
keywordID long The keyword ID.

Response

double - maxBid The maximum bid for Sponsored Search.

getOptimizationGuidelinesForKeyword

Return the optimization guidelines for the keyword (specified by keywordID).

Capability required: CampaignRead
License command group: CampaignOptimization
Supported accounts: Web

Parameters

Parameter Data Type Description
keywordID long The keyword ID.

Response

KeywordOptimizationGuidelines - The optimization guidelines for the keyword.

getReasonsForKeywordNotParticipatingInMarketplace

Return the reasons why the keyword (specified by keywordID) is not participating in the marketplace.

Deprecated: This method has been deprecated since 5.2.0. Use getKeywordParticipationStatusByAdGroupId instead.
Capability required: Research
License command group: Marketing
Supported accounts: Web

Parameters

Parameter Data Type Description
keywordID long The keyword ID.

Response

NotParticipatingInMarketplaceReason[] - A list of one or more reasons.

getSponsoredSearchMinBidForKeywordOptimizationGuidelines

Return the Sponsored Search minimum bid for the optimization guidelines and the ad group (specified by adGroupID).

Capability required: CampaignRead
License command group: CampaignOptimization
Supported accounts: Web

Parameters

Parameter Data Type Description
keywordID long The keyword ID.

Response

double - The minimum bid for Sponsored Search.

getSponsoredSearchMinBidForKeywordString

Return the Sponsored Search minimum bid for the keyword string (specified by sponsoredSearchMinBidRequest).

Capability required: CampaignRead
License command group: Marketing
Supported accounts: Web

Parameters

Parameter Data Type Description
sponsoredSearchMinBidRequest SponsoredSearchMinBidRequest The keyword string and ad group ID.

Response

double - The Sponsored Search minimum bid.

getSponsoredSearchMinBidForKeywordStrings

Return the Sponsored Search minimum bids for the keyword strings (specified by sponsoredSearchMinBidRequests).

Capability required: CampaignRead
License command group: Marketing
Supported accounts: Web

Parameters

Parameter Data Type Description
sponsoredSearchMinBidRequests SponsoredSearchMinBidRequest[] A list of keyword strings and ad group IDs.

Response

double[] - A list of Sponsored Search minimum bids.

getSponsoredSearchMinBidUpdatesByAdGroupId

Return the Sponsored Search minimum bid and other information for the keywords in the ad group (specified by AdGroupID). The bid values represent the updates, if any, made on the previous day. Please note that

  • Although there may be updates from the previous day, the BidStatus filter reflects only the current keyword status.
  • If you do not call the API on day 1 and then you call it on day 2, the keywords updated on day 1 would no longer be available.

Capability required: CampaignRead
License command group: Marketing
Supported accounts: Web

Parameters

Parameter Data Type Description
adGroupId long The ad group ID.
bidStatus BidStatus The BidStatus field is an optional filter that narrows down results, returning only the minimum bid updated keywords for which the current BidStatus equals to the filter passed. If the BidStatus is not passed, all minimum bid updated keywords will be returned.

Response

BidUpdateInfo[] - A list of updated bid information for the keywords in the ad group.

getStatusForKeyword

Return the status of the keyword (specified by keywordID).

Capability required: CampaignRead
License command group: AdvancedTools
Supported accounts: Web

Parameters

Parameter Data Type Description
keywordID long The keyword ID.

Response

KeywordStatus - The status of the keyword.

getUpdateForKeyword

Return the update for the keyword (specified by keywordID).

Capability required: CampaignRead
License command group: Marketing
Supported accounts: Web

Parameters

Parameter Data Type Description
keywordID long The keyword ID.

Response

UpdateForKeyword - The update for the keyword.

moveKeyword

Move the keyword (specified by keywordID) to the ad group (specified by adGroupID).

Capability required: CampaignWrite
License command group: Marketing
Supported accounts: Web

Parameters

Parameter Data Type Description
keywordID long The keyword ID.
destinationAdGroupID long The ad group ID.
newSponsoredSearchMaxBid double The Sponsored Search maximum bid for the keyword. (For this parameter, you may pass in the null value.)

Response

BasicResponse - The response, which indicates if the operation succeeded or failed.

setKeywordUrl

Set the URL for the keyword (specified by keywordID).

Capability required: CampaignWrite
License command group: AdvancedTools
Supported accounts: Web

Parameters

Parameter Data Type Description
keywordID long The keyword ID.
url string The keyword URL.

Response

KeywordResponse - The response, which indicates if the operation succeeded or failed.

setOptimizationGuidelinesForKeyword

Set the optimization guidelines for the keyword.

Capability required: CampaignWrite
License command group: CampaignOptimization
Supported accounts: Web

Parameters

Parameter Data Type Description
optimizationGuidelines KeywordOptimizationGuidelines The optimization guidelines for the keyword.

Response

KeywordOptimizationGuidelinesResponse - The response, which indicates if the operation succeeded or failed.

updateKeyword

Update a keyword.

Capability required: CampaignWrite
License command group: Marketing
Supported accounts: Web

Parameters

Parameter Data Type Description
keyword Keyword The keyword.
updateAll boolean If true, the system performs a full update. All elements are updated. If you pass in the null value or omit an element, the current value is cleared.
If false, the system performs a partial update. Only those elements you specify are updated. If you pass in the null value or omit an optional element, the current value is not changed.

Response

KeywordResponse - The response, which indicates if the operation succeeded or failed.

updateKeywords

Update one or more keywords.

Capability required: CampaignWrite
License command group: Marketing
Supported accounts: Web

Parameters

Parameter Data Type Description
keywords Keyword[] A list of keywords.
updateAll boolean If true, the system performs a full update. All elements are updated. If you pass in the null value or omit an element, the current value is cleared.
If false, the system performs a partial update. Only those elements you specify are updated. If you pass in the null value or omit an optional element, the current value is not changed.

Response

KeywordResponse[] - A list of responses, which indicate if the operations succeeded or failed.

updateSponsoredSearchMaxBidForKeyword

Update the Sponsored Search maximum bid for the keyword (specified by keywordID).

Capability required: CampaignWrite
License command group: Marketing
Supported accounts: Web

Parameters

Parameter Data Type Description
keywordID long The keyword ID.
maxBid double The Sponsored Search maximum bid.

Response

KeywordResponse - The response, which indicates if the operation succeeded or failed.

updateSponsoredSearchMaxBidForKeywords

Update the Sponsored Search maximum bid for one or more keywords (specified by the list of keywordIDs).

Capability required: CampaignWrite
License command group: Marketing
Supported accounts: Web

Parameters

Parameter Data Type Description
keywordIDs long[] A list of keyword IDs.
maxBids double[] A list of Sponsored Search maximum bids.

Response

KeywordResponse[] - A list of responses, which indicate if the operations succeeded or failed.

updateStatusForKeyword

Set the status for the keyword (specified by keywordID).

Capability required: CampaignWrite
License command group: AdvancedTools
Supported accounts: Web

Parameters

Parameter Data Type Description
keywordID long The keyword ID.
status KeywordStatus The new keyword status. You can set the status to On or Off, but not Deleted. (To delete a keyword, use the deleteKeyword operation.)

Response

KeywordResponse - The response, which indicates if the operation succeeded or failed.

updateStatusForKeywords

Set the status for one or more keywords (specified by the list of keywordIDs).

Capability required: CampaignWrite
License command group: AdvancedTools
Supported accounts: Web

Parameters

Parameter Data Type Description
keywordIDs long[] A list of keyword IDs.
status KeywordStatus The new keyword status. You can set the status to On or Off, but not Deleted. (To delete one or more keywords, use the deleteKeywords operation.)

Response

KeywordResponse[] - A list of responses, which indicate if the operations succeeded or failed.

Copyright © 2009 Yahoo! Inc. All Rights Reserved | Copyright/IP Policy | Terms of Service | Trademarks | Patents | Help
NOTICE: We collect personal information on this site. To learn more about how we use your information, see our Privacy Policy.