Keyword Recommendations

Keyword Recommendations:

Use this API to help aid in campaign optimization by getting performance-based recommendations for keywords and suggested bids. You can use this API to discover new keyword ideas based on in-flight campaign performance and add to existing campaigns and ad groups. 

Note:

• Keyword recommendations are only available for ad groups that have been live and running for at least 3 days. For newly created ad groups, the recommendations will be available 3 days later after enough performance data has been accumulated
• Up to 40 keyword recommendations can be provided for each eligible ad group
• Keyword recommendations are only available for manual bidding campaigns
• Keyword recommendations are updated every day and the lookback window is 30 days

Match Type Keyword Recommendations:

Use this API to help aid in campaign optimization by getting performance-based recommendations for keywords and suggested bids for all three match types (Exact, Phrase, Broad). You can use this API to discover new keyword ideas based on in-flight campaign performance and add to existing campaigns and ad groups. 

Note:

• Keyword recommendations are only available for ad groups that have been live and running for at least 3 days. For newly created ad groups, the recommendations will be available 3 days later after enough performance data has been accumulated
• Up to 40 keyword recommendations can be provided for each eligible ad group
• Keyword recommendations are only available for manual bidding campaigns
• Keyword recommendations are updated every day and the lookback window is 30 days

Description: You can place a request for item or keyword recommendations by providing advertiser ID, recommendation type and format

URL: ​POST/api/v1/snapshot/recommendations

Query Parameters

Parameter	Notes	Type	Required	Possible Values
auth_token	The token will provide you the access to the API. It is same for all advertisers you access through the API.	string	Y	Please utilize the generated auth_token shared with you at the time of partner onboarding from the Getting Started Guide
advertiserId	The id of advertiser	integer	Y	The advertiser Id for which the recommendation is to be retrieved
recommendationType	The type of the recommendation required	string	Y	Values of recommendation type: 1. keywordRecommendations 2. matchTypeKeywordRecommendations
format	Choose the format type for your snapshot	string	Y	Types of formats: gzip, zip Note: gzip allows decompression while file is being transferred over the network, hence it is a faster and simpler way to download the repors

Headers

Header Name	Description	Required	Values
WM_CONSUMER.ID	We will provide you the consumer ID to access the API. It is same for all advertisers you access through the API.	Y	Please use the generated ConsumerId shared with you at the time of partner onboarding. Refer to the Getting Started Guide for further explanation on this
WM_SEC.AUTH_SIGNATURE	Auth signature as an API key	Y	Use the signature generator code from Getting Started Guide to generate this value
WM_CONSUMER.intimestamp	Timestamp for which the auth signature is generated. Use Unix epoch format for the timestamp	Y	Use the signature generator code (Getting Started Guide) to generate this value

Sample Request for Keyword Recommendations

curl -X POST 
"https://developer.api.stg.walmart.com/api-proxy/service/WPA/Api/v1/api/v1/snapshot/recommendations?auth_token=1234"  
-H "WM_SEC.AUTH_SIGNATURE: ***********" 
-H "WM_CONSUMER.ID: adfwe-v23-faasd2r-afs-asdfqeff" 
-H "WM_CONSUMER.intimestamp: 1565309779"
 -H "Content-Type: application/json" 
 -H "accept: application/json" 
-d "[
{"advertiserId" : "600002",
 "recommendationType": "keywordRecommendations",
"format": "gzip"}
  ]"

Sample Request for Match Type Keyword Recommendations

curl -X POST 
"https://developer.api.stg.walmart.com/api-proxy/service/WPA/Api/v1/api/v1/snapshot/recommendations?auth_token=1234"  
-H "WM_SEC.AUTH_SIGNATURE: ***********" 
-H "WM_CONSUMER.ID: adfwe-v23-faasd2r-afs-asdfqeff" 
-H "WM_CONSUMER.intimestamp: 1565309779"
 -H "Content-Type: application/json" 
 -H "accept: application/json" 
-d "[
{"advertiserId" : "600002",
 "recommendationType": "matchTypeKeywordRecommendations",
"format": "gzip"}
  ]"

Response

Element	Description	Type
code	The response code can have following values:   success failure	string
details	Details of the error if value of response code is failure	string
snapshotId	ID of the snapshot	string
jobStatus	It is an indicator to confirm status of snapshot generation. The possible values of jobStatus are: pending, processing, done, failed, expired	string

Sample Response for Keyword Recommendations

[
  {
      "code": "success",
      "snapshotId": "09815467655-92ef-490d-a2c8-0157990f57f867",
      "details": " ",
     " jobStatus ": "pending"
  }
]

Sample Response for Match Type Keyword Recommendations

[
  {
    "code": "success",
    "snapshotId": "676515467655-89ef-670d-a2c8-0157990f57f854",
    "details": " ",
    " jobStatus ": "pending"
  }
]

Description: You can retrieve keyword recommendations snapshots by providing snapshot id and advertiser id for an advertiser.

Note:

• The output is generated in a “zip/gzip” file depending upon format chosen
• The file type enclosed in zip is CSV. You can request the following type of snapshots:
  • Keyword Recommendations

URL: GET/api/v1/snapshot

Query Parameters

Parameter	Description	Type	Required	Possible Values
auth_token	The token will provide you the access to the API. It is same for all advertisers you access through the API.	string	Y	Please utilize the generated auth_token shared with you at the time of partner onboarding from the Getting Started Guide
advertiserId	The ID of the advertiser	integer	Y	Unique numeric identifier
snapshotId	The ID of the snapshot	string	Y	Unique alpha numeric identifier

Sample Request for Keyword Recommendations snapshot

curl -X GET
"https://developer.api.stg.walmart.com/api-proxy/service/WPA/Api/v1/api/v1/snapshot?advertiserId=600002&snapshotId=09815467655-92ef-490d-a2c8-0157990f57f867&auth_token=1234"  
 -H "accept: application/json" 
-H "WM_SEC.AUTH_SIGNATURE: ***********" 
-H "WM_CONSUMER.ID: adfwe-v23-faasd2r-afs-asdfqeff" 
-H "WM_CONSUMER.intimestamp: 1565309779" 

Sample Request for Match Type Keyword Recommendations snapshot

curl -X GET\
"https://developer.api.stg.walmart.com/api-proxy/service/WPA/Api/v1/api/v1/snapshot?advertiserId=600002&snapshotId=676515467655-89ef-670d-a2c8-0157990f57f854&auth_token=1234"  \
 -H "accept: application/json" \
-H "WM_SEC.AUTH_SIGNATURE: ***********" \
-H "WM_CONSUMER.ID: adfwe-v23-faasd2r-afs-asdfqeff" \
-H "WM_CONSUMER.intimestamp: 1565309779" \

Response

Element	Description	Type
snapshotId	Id of the snapshot to be retrieved	string
jobStatus	It is an indicator to confirm status of snapshot generation. The possible values of jobStatus are: pendingprocessingdonefailedexpired	string
details	Provides download URL when processed (once jobStatus reaches to state “done”)	string
code	The response code can have following values:   success, failure	string

Sample Response for Keyword Recommendations snapshot

[
  {
    "code": "success",
    "snapshotId": "09815467655-92ef-490d-a2c8-0157990f57f867",
    "details": "https://advertising.walmart.com/file/09815467655-92ef-490d-a2c8-0157990f57f867 ",
    " jobStatus ": "done"
  }
]

Example of the Keyword Recommendations snapshot with id “15467655-92ef-490d-a2c8-0157990f57f8”. The file format is “CSV”

reportDate	campaignId	campaignName	adGroupId	adGroupName	keywordText	suggestedBid
5/19/2022	1734290	camp1	1050504	High Chairs	convertible flip chair	0.61
5/19/2022	1632220	camp2	1166084	Furniture – 7	L shaped desk	15.91
5/19/2022	1734290	camp1	1050504	Chairs – Keywords	tri fold sofa beds	0.51

Sample Response for Match Type Keyword Recommendations snapshot

[
  {
    "code": "success",
    "snapshotId": "676515467655-89ef-670d-a2c8-0157990f57f854",
    "details": "https://advertising.walmart.com/file/676515467655-89ef-670d-a2c8-0157990f57f854",
    " jobStatus ": "done"
  }
]

Example of the Match Type Keyword Recommendations snapshot with id “09815467655-92ef-490d-a2c8-0157990f57f867”. The file format is “CSV”:

reportDate	campaignId	campaignName	adGroupId	adGroupName	keywordText	suggestedBid	matchType
5/19/2022	1734290	camp1	1050504	High Chairs	convertible flip chair	0.5	exact
5/19/2022	1734290	camp1	1050504	High Chairs	convertible flip chair	0.4	phrase
5/19/2022	1734290	camp1	1050504	High Chairs	convertible flip chair	0.3	broad
5/19/2022	1632220	camp2	1166084	Furniture – 7	L shaped desk	0.5	exact
5/19/2022	1632220	camp2	1166084	Furniture – 7	L shaped desk	0.4	phrase
5/19/2022	1734290	camp2	1166084	Furniture – 7	L shaped desk	0.3	broad

The snapshot file is zipped CSV file format.

The response would be captured in one zip/gzip file as requested.

Columns in Keyword Recommendations snapshot

Columns	Description	Type
reportDate	The date when the report was generated	date
campaignId	Unique identifier for the campaign	string
campaignName	The unique name of the campaign for the given campaign id	string
adGroupId	Unique identifier for Ad group for the given campaign id	string
adGroupName	Name of the Ad group for the given ad group id	string
keywordText	Text that defines the keyword	string
suggestedBid	Bid suggestion to bid in keyword campaign	double

Columns in Match Type Keyword Recommendations snapshot

Columns	Description	Type
reportDate	The date when the report was generated	date
campaignId	Unique identifier for the campaign	string
campaignName	The unique name of the campaign for the given campaign id	string
adGroupId	Unique identifier for Ad group for the given campaign id	string
adGroupName	Name of the Ad group for the given ad group id	string
keywordText	Text that defines the keyword	string
suggestedBid	Bid suggestion to bid in keyword campaign	double
matchType	Match type for a given keyword and bid Possible values: exact, phrase, broad	string

Q: Why I don’t have any keyword recommendations for an active ad group? 

A: The ad group hasn’t been running for at least 3 days or all recommended keywords have been applied and added to the ad group. Please check back in a few days for new keyword recommendations. 

Q: How do Keyword Recommendations differ from Suggested Keywords? 

A: Keyword Recommendations provide recommendations for keywords based on actual campaign performance and only available for ad groups that have been running for at least 3 days. Up to 40 keyword recommendations can be provided for each eligible ad group, and advertisers can download recommended keywords for all ad groups at once. Suggested Keywords are keywords suggestions provided at the ad group level in the campaign creation and editing process for advertisers to explore new keyword ideas. A maximum of 220 keyword ideas can be suggested for each ad group. The suggested keywords today include suggestions that are most relevant to the items that advertisers have added to their campaigns; at the end of June, the Suggested Keywords API will be upgraded to also include performance-based keywords for eligible ad groups. To optimize in-flight campaign performance, we recommend applying keywords from the Keyword Recommendations endpoint, and explore additional keyword ideas from Suggested Keywords.

There is a rate limit in place on the allowed number of API operations per hour.

Operations per hour are computed as the sum of number of changes requested across all API requests during the hour.

For example, 5 keyword bid changes, creation of an ad group, adding an item, and a snapshot report request in any given hour, would be counted as 8 operations.

You will receive an HTTP 429 status error code and an error message about rule enforced in case of breaking ops limit.

To learn more about current applicable limits specific to your integration, please reach out to the API Partner Enablement team.