Skip to main content

​
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

/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 theGETretailers 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

*Required
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. Sample Request 
curl -L -X POST 'https://api.criteo.com/{version}/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 ifproductIdsarray is provided with 1-1000 items, andretailerIdis 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"
}