Recommended Keywords
Introduction
The Recommended Keywords endpoint helps to discover the most relevant keywords for your advertising campaigns by leveraging Criteo's advanced Keyword Service technology. This is the same algorithm used to generate keywords for Sponsored Products line items that serve on search pages across retail environments.
When you provide product IDs
, this endpoint analyzes your products and returns the top 100 keywords that your Sponsored Product and Onsite Display line items would serve on when shoppers search for related terms. This data-driven approach ensures your campaigns target the most effective keywords based on actual search behavior and product relevance.
The Recommended Keywords are particularly valuable for campaign optimization, keyword expansion strategies, and understanding how your products align with shopper search intent. By using these recommendations, you can improve campaign performance and reach more qualified shoppers who are actively searching for products like yours.
Endpoints
Method | Endpoint | Description |
---|---|---|
POST | /preview/retail-media/retailers/{retailerId}/recommend-keywords | Gets the top 100 recommended keywords for specified products |
Attributes table
Attribute | Data Type | Description |
---|---|---|
retailerId | string | Unique identifier for the retailer. Found using the GET retailers endpoint.Required in URL path. Writable? N / Nullable? N |
productIds | array | Array of product ID strings for keyword recommendations. Min: 1 item, Max: 1000 items. Required field. Writable? Y / Nullable? N |
Field Definitions
- Writeable (Y/N): Indicates if the field can be modified in requests.
- Nullable (Y/N): Indicates if the field can accept null/empty values.
- Primary Key: The main identifier field required for the endpoint to function correctly. Primary keys are typically ID fields (e.g.,
retailerId
,campaignId
,lineItemId
) and are usually required in the URL path.
Get Recommended Keywords
This endpoint retrieves the top 100 recommended keywords for specified products using Criteo's Keyword Service technology. The recommendations are based on the same algorithms used for Sponsored Products line items serving on search pages.

https://api.criteo.com/preview/retail-media/retailers/{retailerId}/recommend-keywords
Sample Request
curl -L -X POST 'https://api.criteo.com/preview/retail-media/retailers/12345/recommend-keywords' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <MY_ACCESS_TOKEN>' \
-d '{
"data": {
"attributes": {
"productIds": [
"PROD123",
"PROD456",
"PROD789"
]
},
"type": "RecommendedKeywordsRequestV1"
}
}'
Sample Response
{
"data": {
"type": "RecommendedKeywordsResponseV1",
"attributes": {
"recommendedKeywords": [
"wireless headphones",
"bluetooth earbuds",
"noise cancelling headphones",
"gaming headset",
"wireless earbuds",
"bluetooth headphones",
"over ear headphones",
"sports headphones",
"true wireless earbuds",
"active noise cancellation"
]
}
},
"warnings": [],
"errors": []
}
Responses
Code | Meaning | Troubleshooting Hint |
---|---|---|
🟢 200 | Success | Request processed successfully, returns up to 100 recommended keywords |
🔴 400 | Bad Request | Check if productIds array is provided with 1-1000 items, and retailerId is valid in URL path |
🔴 403 | Forbidden | Verify authorization and retailer access permissions |
Common Error Scenarios
Missing or Empty Product IDs
{
"errors": {
"Data.Attributes.ProductIds": [
"The field ProductIds must be a string or array type with a minimum length of '1'."
]
},
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
"title": "One or more validation errors occurred.",
"status": 400,
"traceId": "00-e03b1ec1e478d6ac2b6645102df581b0-770e081f98eea942-01"
}
Invalid Retailer ID
{
"errors": {
"retailerId": [
"The value ':retailerId' is not valid."
]
},
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
"title": "One or more validation errors occurred.",
"status": 400,
"traceId": "00-2674ea556f336eb5d84536b5674db671-99e929542eda8eff-01"
}
Updated about 6 hours ago