Similar Products

General concepts

To make a request, you need to specify two product sets using ProductSetSelectors, define how to measure similarity, and initiate the search. You then need to poll the search status endpoint to get the results of the search.

Product set selection

Product set selection is the stage in the processing of this request where product catalogues are filtered down to the products to be compared. The search compares two sets of products and users can specify how those sets are selected. The ProductSetSelector object specifies the selection criteria. By default, all products in a project will be selected for comparison. Optionally, the user can specify a set of product IDs or a set of product type IDs to filter by.

Product set selection examples

Compare every product in a project "sunrise" to a product with the ID {product_id} in a project {projectKey}

...
"productSetSelectors": [
    { "projectKey": "{projectKey}",
      "productIds": ["{product_id}"] },
    { "projectKey": "sunrise" }
]
...

Compare every product with type {product_type_id_1} with products with type {product_type_id_2}

...
"productSetSelectors": [
    { "projectKey": "{projectKey}",
      "productTypeIds": ["{product_type_id_1}"] },
    { "projectKey": "{projectKey}",
      "productTypeIds": ["{product_type_id_2}"] }
]
...

Compare the staged version of product {product_id_1} with the current version of products {product_id_2} and {product_id_3}

...
"productSetSelectors": [
    { "projectKey": "{projectKey}",
      "productIds": ["{product_id_1}"],
      "staged": true },
    { "projectKey": "{projectKey}",
      "productIds": ["{product_id_2}", "{product_id_3}"],
      "staged": false }
]
...

Product comparisons

The maximum number of allowed product comparisons is 20,000,000. The calculation of the number of comparisons depends on the type of the request.

If the two specified productSetSelectors are identical, each product in the first ProductSet will be compared to all the products in the second ProductSet excluding itself resulting in (N choose 2) comparisons, where N is the total number of products in one ProductSet. If the two specified productSetSelectors are different, every product in one ProductSet is compared to every product in the other ProductSet, resulting in (N1 * N2) total comparisons.

Similarity specification

The similarityMeasures attribute defines which aspects of a product to use to calculate product similarity, and how important each aspect is to the overall similarity score between products.

You can use the following attributes for comparisons:

• name
• description
• price
• variantCount
• attribute

Similarity Measure examples

Compare similarity using name, description and attribute, where the similarity of attribute is twice as important to overall similarity:

...
"similarityMeasures": {
    "name": 1,
    "description": 1,
    "attribute": 2
}
...

Compare similarity based on price and attribute, where both are equal to overall similarity:

...
"similarityMeasures": {
    "price": 1,
    "attribute": 1
}
...

Representations

ProductSetSelector

A set of ProductData for comparison. If no optional attributes are specified, all current ProductData are selected for comparison. See Product set selection for more details and examples.

• projectKey - String - Required
  The project containing the project set.
• productIds - Array of String - Optional
  An array of Product IDs to compare. If unspecified, no Product ID filter is applied.
• productTypeIds - Array of String - Optional
  An array of product type IDs. Only products with product types in this array are compared. If unspecified, no product type filter is applied.
• staged - Boolean - Optional
  Specifies use of staged or current product data. Default: false (that means use current ProductData).
• includeVariants - Boolean - Optional
  Specifies use of product variants. If set to true, all product variants are compared, not just the master variant. Default: false.
• productSetLimit - Integer - Optional
  Maximum number of products to check (if unspecified, all products are considered). Note that the maximum number of product comparisons between two productSets is 20,000,000. This limit cannot be exceeded. If you need a higher limit, contact Support Portal.

Default ProductSetSelector

Compare all products within a project.

[{ "projectKey": "{projectKey}" }, { "projectKey": "{projectKey}" }]

SimilarityMeasures

Specify which ProductData attributes to use for estimating similarity and how to weigh them. An attribute's weight can be any whole positive integer, starting with 0. The larger the integer, the higher its weight. See Similarity Specification for more details and examples.

• name - Integer - Optional
  Importance of the name attribute in overall similarity. Default: 1.
• description - Integer - Optional
  Importance of the description attribute in overall similarity. Default: 1.
• attribute - Integer - Optional
  Importance of the product variant's attribute values in overall similarity. Default: 1.
• variantCount - Integer - Optional
  Importance of the number of product variants in overall similarity. Default: 0.
• price - Integer - Optional
  Importance of the price attribute in overall similarity. Default: 0.

Default SimilarityMeasures

{
  "name": 1,
  "description": 1,
  "attribute": 1
}

SimilarProductSearchRequest

• limit - Number - Optional
• offset - Number - Optional
• language - String Default: enIETF language tag language tag used to prioritize language for text comparisons.
• currencyCode - String - Default: EUR
  The three-digit ISO 4217 currency code to compare prices in. When a product has multiple prices, all prices for the product are converted to the currency provided by the currency attribute and the median price is calculated for comparison. Currencies are converted using the European Central Bank (ECB) currency exchange rates at the time the request is made. Of the ISO 4217 currency codes, only currencies with currency exchange rates provided by the ECB are supported.
• similarityMeasures - SimilarityMeasures - Optional
  Default: Default SimilarityMeasures. similarityMeasures defines the attributes taken into account to measure product similarity.
• productSetSelectors - Array of length 2 of ProductSetSelector - Optional
  Default: Default ProductSetSelector.
• confidenceMin - Float - Range [0.0 - 1.0] - Default: 0.01
  See Confidence Filtering.
• confidenceMax - Float - Range [0.0 - 1.0] - Default: 1.0
  See Confidence Filtering.

SimilarProduct

One part of a SimilarProductPair. Refers to a specific ProductVariant.

• product - Reference to a Product
• variantId - Integer
  ID of the ProductVariant that was compared.
• meta - SimilarProductMeta - Optional
  Supplementary information about the data used for similarity estimation. This information helps you understand the estimated confidence score, but it should not be used to identify a product.

SimilarProductMeta

• name - LocalizedString - Optional
  Localized product name used for similarity estimation.
• description - LocalizedString - Optional
  Localized product description used for similarity estimation.
• price - Money - Optional
  The product price in cents using the currency defined in SimilarProductSearchRequest. If multiple prices exist, the median value is taken as a representative amount.
• variantCount - Integer - Optional
  Total number of variants associated with the product.

SimilarProductPair

A pair of SimilarProducts.

• confidence - Float - Range [0.0 - 1.0].
  The probability of product similarity.
• products - Array of two SimilarProduct

SimilarProductSearchRequestMeta

Metadata about the search parameters.

• similarityMeasures - The SimilarityMeasures used in this search.

Endpoints

Initiation endpoint

Host: one of the Machine Learning hosts.
Endpoint: /{projectKey}/similarities/products
Method: POST
OAuth 2.0 Scopes: view_products:{projectKey}
Response Representation: TaskToken
Request Representation: SimilarProductSearchRequest

Status endpoint

Host: one of the Machine Learning hosts.
Endpoint: /{projectKey}/similarities/products/status/{task_id}
Method: GET
OAuth 2.0 Scopes: view_products:{projectKey}
Response Representation: TaskStatus of a PagedQueryResult with results containing an array of SimilarProductPairs, sorted by confidence scores in descending order and the meta information of SimilarProductSearchRequestMeta.

Examples

curl -X POST https://ml-{mlRegion}.europe-west1.gcp.commercetools.com/{projectKey}/similarities/products \
-H "Content-Type: application/json" \
-H 'Authorization: Bearer {access_token}' \
-d \
'
{
    "limit" : 3,
    "similarityMeasures" : {
        "name": 1
    },
    "productSetSelectors" : [
        {
            "projectKey": "{projectKey}",
            "productTypeIds": [ "8b50b0b0-8091-8e32-4601-948a8b504606" ],
            "staged": true
        },
        {
            "projectKey": "{projectKey}",
            "productTypeIds": [ "46068292-4a41-4601-948a-948a8b508b50" ],
            "staged": true
        }
    ]
}
'

{
  "taskId": "078b4eb3-8e29-1276-45b1-8964cf118707",
  "location": "/{projectKey}/similarities/products/078b4eb3-8e29-1276-45b1-8964cf118707"
}

curl -sH 'Authorization: Bearer {access_token}' https://ml-{mlRegion}.europe-west1.gcp.commercetools.com/{projectKey}/similarities/products/078b4eb3-8e29-1276-45b1-8964cf118707

{
  "state": "SUCCESS",
  "result": {
    "count": 1,
    "total": 16,
    "offset": 0,
    "results": [
      {
        "confidence": 0.68427,
        "products": [
          {
            "product": {
              "id": "b0b08091-8e32-4601-948a-8b504606d3ac",
              "typeId": "product"
            },
            "variantId": 1,
            "meta": {
              "name": {
                "en": "White T-Shirt | Commercetools Hackathon Edition | Available in S/M/L"
              }
            }
          },
          {
            "product": {
              "id": "46014606-8b50-4606-8292-4a414601948a",
              "typeId": "product"
            },
            "variantId": 1,
            "meta": {
              "name": {
                "en": "Limited edition of the Commercetools T-Shirt - White Color - Now on Sale!"
              }
            }
          }
        ]
      },
      "... other similar products ..."
    ],
    "meta": {
      "similarityMeasures" : {
        "name": 1
      }
    }
  }
}