Guides

Recommend API Guide

Suggest Edits

The Recommend API endpoint is designed to provide personalized or contextually relevant item recommendations for a pre-configured placement. A placement represents a specific location or scenario within your application (e.g., "homepage_banner", "product_page_alternatives", "checkout_offers") where recommendations are displayed.

Before using this API, ensure the desired placement is configured in the Opti-X platform (or via the Placements API). You'll need the placementKey generated during this setup.

Endpoint

To fetch recommendations, you'll make a request to:

POST https://api.opti-x.optimove.net/recommend/v1/placements/{placementKey}/recommendations

Replace {placementKey} with the unique key of your configured placement.

Headers

The following headers are mandatory for all requests:

  • x-api-key: Your unique API key provided during integration.
  • x-brand-key: The unique reference for your brand.
  • content-type: Must be set to application/json.

Request Body Parameters

The JSON payload of your request provides the context for the recommendation engine. This allows Optimove to tailor the results effectively.

{
  "context": {
    "product": "Gaming",
    "category": "Slots",
    "page": {
      "url": "casino.graphytecasino.com/en",
      "title": "Slots page"
    },
    "channel": "Mobile"
  },
  "userId": "123456",
  "traits": {
    "contextId": "440q6fneh3k-0jot24y2k-76umam8"
  },
  "type": "recommendation",
  "recommendation": {
    "target": {
      "exclusions": {
        "inBetSlip": false,
        "additionalItemList": [
          832831914
        ]
      }
    }
  }
}

Here's a breakdown of the request body parameters:

ParameterTypeMandatory/OptionalDescriptionHow it Affects Results
userIdStringMandatoryThe unique identifier for the end-user.Crucial for personalization. If a known user, their past behavior, preferences, and history will heavily influence the recommendations. For anonymous users, a temporary ID can be used for session-based personalization.
typeStringMandatoryDefines the type of request. For this endpoint, it should generally be "recommendation".Ensures the request is processed by the recommendation engine. Other types might be used for different API functionalities.
contextObjectMandatoryAn object containing contextual information about where the recommendation is being requested.Provides the immediate situation/environment, allowing the API to refine recommendations. E.g., showing "slot games" if the user is in the "Slots" category.
context.productStringOptionalThe product vertical the user is currently interacting with (e.g., "Gaming", "Sports", "Ecommerce").Helps filter recommendations to the relevant product line. Different products might have different item types or recommendation strategies.
context.categoryStringOptionalThe specific category within the product the user is viewing (e.g., "Slots", "Football", "Dresses").Narrows down the recommendations to items within that category. If product is "Gaming", category "Slots" will focus on slot games.
context.pageObjectOptionalDetails about the page where the recommendations will be displayed.Can be used to understand the specific location within your application, potentially influencing recommendations based on page type or content.
context.page.urlStringOptionalThe URL of the page.Provides more specific context.
context.page.titleStringOptionalThe title of the page.Provides more specific context.
context.channelStringOptionalThe channel through which the user is interacting (e.g., "Mobile", "Desktop", "App").May influence the format or type of recommendations if different channels have different display capabilities or user behaviors.
traitsObjectOptionalAn object for additional, often dynamic, contextual attributes.Allows for sending more granular, real-time context that might not fit standard fields.
traits.contextIdStringOptionalA specific identifier for the context, which could be a session ID or a page-specific ID.Can be used for fine-grained contextual filtering or tracking.
recommendationObjectOptionalAn object to include more specific controls over the recommendations, such as exclusions. Often used in specific scenarios like Sports betting.Allows direct manipulation of the recommendation output by specifying items to exclude.
recommendation.targetObjectOptionalContains targeting rules for the recommendation.Defines what items should be considered or explicitly excluded.
recommendation.target.exclusionsObjectOptionalSpecifies items or types of items to exclude from the recommendation results.Ensures that users are not shown irrelevant, already interacted-with, or out-of-context items.
recommendation.target.exclusions.inBetSlipBooleanOptionalSpecific to Sports betting. If true, indicates the recommendation is being displayed on the bet slip.Can trigger rules to avoid recommending markets already in the bet slip or to suggest complementary bets.
recommendation.target.exclusions.additionalItemListArrayOptionalSpecific to Sports betting. A list of selection/item IDs that are already in the user's basket (e.g., bet slip).Prevents the API from recommending items (e.g., specific bets) that the user has already added to their current selection/cart. The API will exclude any selections from events that contain an item in this list.

ℹ️

Note: The availability and behavior of certain optional parameters, especially within the recommendation.target.exclusions object, might be highly dependent on the context.product (e.g., "Sports" vs. "Gaming") and your specific Optimove tenant configuration. Always refer to the full Open API Specification in the Developer Tools section of the Opti-X platform for the most precise details.

How Parameters Influence Results - A Summary

  • userId is key for personalization: It links the request to a user's profile, history, and preferences.
  • context object sets the scene: It tells the API where and what the user is currently doing, ensuring relevance.
    • product and category are strong filters for the type of items to recommend.
  • recommendation.target.exclusions provides fine-grained control: It allows you to explicitly remove certain items, which is particularly useful in dynamic contexts like a sports betting slip or a shopping cart.

By providing as much relevant information as possible in these parameters, you enable the Optimove recommendation engine to deliver more accurate, engaging, and effective recommendations.

Example Request: Gaming Context

This is a typical request for recommendations within a gaming product, specifically on a slots page viewed on a mobile device.

{
  "context": {
    "product": "Gaming",
    "category": "Slots",
    "page": {
      "url": "casino.graphytecasino.com/en",
      "title": "Slots page"
    },
    "channel": "Mobile"
  },
  "userId": "123456",
  "traits": {
    "contextId": "440q6fneh3k-0jot24y2k-76umam8"
  },
  "type": "recommendation"
}

Example Response: Gaming Context

A successful request will return a list of recommended items.

{
  "recommendation": {
    "result": [
      {
        "game": {
          "game_code": "gameiomslingorainbowriches",
          "score": 0.6708955335834027,
          "rank": 1
        }
      }
      // ... other recommended items
    ],
    "recId": "1326e3b1-0ecc-4baf-9714-ff2ad4f1ebab",
    "recDateTime": "2020-02-26T21:08:57.767Z",
    "explanation": {
      "reason": "tagged games",
      "tag_type": "portlet",
      "tag": "MOST POPULAR"
    }
  }
}

Key Response Fields:

  • recommendation.result: An array of recommended items. The structure of each item (e.g., game, selection) will depend on the context.product and placement configuration.
    • score: The relevance score assigned by the recommendation engine.
    • rank: The position of the item in the recommended list.
  • recId: A unique identifier for this specific recommendation response. Useful for logging or feedback loops.
  • recDateTime: Timestamp of when the recommendation was generated.
  • explanation: Provides insight into why these items were recommended (e.g., based on "MOST POPULAR" tag, collaborative filtering, etc.). This can vary based on the recommendation strategy employed by the placement.

Example Request: Sports Context with Exclusions

This example demonstrates a request for a "Sports" product, specifically "Football," and includes exclusions to prevent recommending items already in the user's bet slip.

{
  "context": {
    "product": "Sports",
    "category": "Football",
    "page": {
      "url": "sport.graphyte.ai",
      "title": "Football"
    }
  },
  "recommendation": {
    "target": {
      "exclusions": {
        "inBetSlip": false,
        "additionalItemList": [
          832831914
        ]
      }
    }
  },
  "userId": "1",
  "type": "recommendation"
}

The recommendation.target.exclusions object here tells the API to:

  1. Consider that these recommendations are not for display directly on the bet slip (inBetSlip: false).
  2. Exclude any recommendations related to item 832831914 (and other selections from the same event) as it's already in the user's bet slip (additionalItemList).

Example Response: Sports Context

The response will contain sports-related selections, respecting the exclusions.

{
  "recommendation": {
    "result": [
      {
        "selection": {
          "selectionKey": 1196055705,
          "selectionName": "Brighton",
          "marketName": "Match Betting",
          // ... other selection details
          "score": 0.6222013974969091,
          "rank": 1
        }
      }
      // ... other recommended selections
    ],
    "recId": "d3df0134-9262-4c8d-9241-ab56043fe7f0",
    "recDateTime": "2020-12-16T16:34:00.376Z"
  }
}

Example Request: E-commerce Context

The request includes context about the current product being viewed (currentItemId), the category, and items to exclude (e.g., from the cart).

{
  "context": {
    "product": "Ecommerce",
    "category": "Electronics - Laptops",
    "currentItemId": "SKU_LAPTOP123",
    "page": {
      "url": "https://yourshop.example.com/products/electronics/laptops/sku_laptop123",
      "title": "SuperFast Laptop Pro - Product Details"
    },
    "channel": "Desktop"
  },
  "userId": "user_ecom_67890",
  "traits": {
    "customerSegment": "power_user",
    "lastPurchaseDaysAgo": 30
  },
  "type": "recommendation",
  "recommendation": {
    "target": {
      "exclusions": {
        "additionalItemList": ["SKU_MOUSE456", "SKU_KEYBOARD789"]
      }
    }
  }
}

Key E-commerce Request Parameters in this example:

  • context.product: Set to "Ecommerce" to indicate the retail vertical.
  • context.category: Specifies the category of the item currently being viewed (e.g., "Electronics - Laptops"). This helps narrow down the type of related items.
  • context.currentItemId: Crucial for PDP recommendations. This is the unique identifier (e.g., SKU) of the product the user is currently viewing. The recommendation engine uses this to find related or complementary products.
  • recommendation.target.exclusions.additionalItemList: An array of item IDs (SKUs) that should be excluded from the recommendations. This is commonly used to list items already in the user's shopping cart or recently purchased items.

Example Response: E-commerce Context

The response contains a list of recommended e-commerce items, with details relevant to a shopping experience.

{
  "recommendation": {
    "result": [
      {
        "item": {
          "item_id": "SKU_SSDEXT1TB",
          "name": "UltraSpeed Portable SSD 1TB",
          "brand_name": "DataFast",
          "category_path": "Computer Accessories - External Storage",
          "price": 129.99,
          "currency_code": "USD",
          "thumbnail_url": "https://yourshop.example.com/images/sku_ssdext1tb_thumb.jpg",
          "product_url": "https://yourshop.example.com/products/accessories/storage/sku_ssdext1tb",
          "in_stock": true,
          "score": 0.92,
          "rank": 1
        }
      },
      {
        "item": {
          "item_id": "SKU_LAPTOPSTAND01",
          "name": "Ergonomic Laptop Stand - Silver",
          "brand_name": "ComfortView",
          "category_path": "Computer Accessories - Stands",
          "price": 39.95,
          "currency_code": "USD",
          "thumbnail_url": "https://yourshop.example.com/images/sku_laptopstand01_thumb.jpg",
          "product_url": "https://yourshop.example.com/products/accessories/stands/sku_laptopstand01",
          "in_stock": true,
          "score": 0.88,
          "rank": 2
        }
      }
      // ... other recommended items
    ],
    "recId": "rec-ecom-pdp-9f7ad83b-f938-4a8e-8b2d-1c9e4f6a0b7e",
    "recDateTime": "2025-06-04T16:10:00Z",
    "explanation": {
      "reason": "Cross-sell based on viewed item SKU_LAPTOP123",
      "tag_type": "product_detail_page_slot",
      "tag": "Frequently Bought Together"
    }
  }
}

Key E-commerce Response Fields in this example:

  • item: Each object in the result array represents a recommended product.
    • item_id: The unique identifier or SKU of the recommended product.
    • name: The display name of the product.
    • brand_name: The brand of the product.
    • category_path: The category breadcrumb or path for the product.
    • price: The selling price of the item.
    • currency_code: The currency for the price (e.g., "USD", "EUR").
    • thumbnail_url: URL for a small image of the product.
    • product_url: Direct URL to the product's detail page.
    • in_stock: Boolean indicating stock availability (important for e-commerce).
    • score & rank: Standard recommendation metrics.

ℹ️

Note: It is expected that a 200 status code will be delivered even if there are no suitable recommendations available. In such cases, the recommendation.result array will typically be empty.

Open API Specification

For the most comprehensive and up-to-date details on all API endpoints, parameters, data types, and mandatory/optional fields, please refer to the full API specification available within the Developer Tools section of the Opti-X platform.

Updated 1 day ago