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

Attributes table

📘

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

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"
}