Category Recommendations

This feature is part of our Machine Learning APIs that are available in the Google Cloud Regions except Australia (Google Cloud, Sydney).

Predicting categories for products with machine learning.

When a new product is added, it needs to be manually assigned to the correct product categories. Since new products need to be added frequently and the number of available categories can be large, this is often a very time-consuming and tedious process. This feature is designed to make this process easier by automatically predicting which categories belong to a given product.

Two different endpoints are available. The project-specific endpoint matches existing products to categories that are already defined in a specific project. In contrast, the general endpoint takes arbitrary product names or image urls and predicts general category names, independent of the categories defined in a particular project.

You can read more about the feature implementation in the tech blog.

Project-specific Category Recommendations

This endpoint takes a specific product ID and searches for the best-fitting categories in a particular project. In the background, the API applies machine learning classifiers to the information from the product name and the first product image of the master variant (if available).

The quality of the predictions is usually higher in the following cases:

Product and category names are available in English.
Product images are representative of the product.
The categories defined in the project cover a broad range of topics.

Activating the API

The API can be activated using the Merchant Center, navigate to Settings > Project Settings > Miscellaneous > Recommended categories > Machine Learning. Once the feature is enabled, you can request recommendations on a product details page by navigating to Product categories > Add categories > Recommendations

A project can be enabled if it meets the following criteria:

The project contains at least one category and product.
The project does not contain more than 50000 categories.

If your project has more than 50000 categories, but you are still interested in testing the API, do not hesitate to contact us via the platform support.

Representations

ProjectCategoryRecommendation

ProjectCategoryRecommendationMeta

ProjectCategoryRecommendation

category - Reference to a Category
A category that is recommended for a product.
confidence - Float - Range [0.0 - 1.0]
Probability score for the category recommendation.
path - String
Breadcrumb path to the recommended category. This only picks up one language, not all available languages for the category. English is prioritized, but if English data is not available, an arbitrary language is selected. Do not use this to identify a category, use the category ID from the category reference instead.

ProjectCategoryRecommendationMeta

productName - String - Optional
The product name that was used to generate recommendations.
productImageUrl - String - Optional
The product image that was used to generate recommendations.
generalCategoryNames - Array of Strings
Top 5 general categories that were used internally to generate the project-specific categories. These category names are not related to the categories defined in the project, but they provide additional information to understand the project-specific categories in the results section.

Query

Host: one of the Machine Learning hosts.
Endpoint: /{projectKey}/recommendations/project-categories/{product_id}
Method: GET
OAuth 2.0 Scopes: view_products:{projectKey}
Response Representation: PagedQueryResult with results containing an array of ProjectCategoryRecommendation, sorted by confidence scores in descending order and the meta information of ProjectCategoryRecommendationMeta.

Query Parameters:

staged - Boolean - Optional - Default: true
Flag to target either the staged or the current version of a Product.
confidenceMin - Float - Range [0.0 - 1.0] - Default: 0.01
confidenceMax - Float - Range [0.0 - 1.0] - Default: 1.0
limit - Number - Optional - Range: [1-20] - Default: 3
offset - Number - Optional - Default: 0

Examples

Example Request for Project CategoriesTerminal

$curl -G -H "Authorization: Bearer {access_token}" \
--data staged=true \
--data limit=2 \
"https://ml-{mlRegion}.europe-west1.gcp.commercetools.com/{projectKey}/recommendations/project-categories/{product_id}"

Example Responsejson

{
  "count": 2,
  "total": 16,
  "offset": 0,
  "results": [
    {
      "category": {
        "id": "c077eb33-c5fe-4560-af75-abb8b205ca25",
        "typeId": "category"
      },
      "confidence": 0.08427,
      "path": "Men > Shoes"
    },
    {
      "category": {
        "id": "b0b08091-8e32-4601-948a-8b504606d3ac",
        "typeId": "category"
      },
      "confidence": 0.08319,
      "path": "Accessories > Men > Shoes"
    }
  ],
  "meta": {
    "productName": "Runner – Philippe Model “Tropez”",
    "productImageUrl": "https://s3-eu-west-1.amazonaws.com/commercetools-maximilian/products/083442_1_medium.jpg?$mcsmall$",
    "generalCategoryNames": [
      "shoes",
      "sports",
      "fitness",
      "sneakers",
      "loafers"
    ]
  }
}

General Category Recommendations

This endpoint takes arbitrary product names or image URLs and generates recommendations from a general set of categories, which cover a broad range of industries. The full list of supported categories can be found here. These are independent of the categories that are actually defined in your project. The main purpose of this API is to provide a quick way to test the behavior of the category recommendations engine for different names and images. In contrast to the project-specific endpoint, this endpoint does not have activation criteria and is enabled for all projects.

Representations

GeneralCategoryRecommendation

categoryName - String
An English category name that is recommended for a product.
confidence - Float - Range [0.0 - 1.0].
Probability score for the category recommendation.\

Query

Host: one of the Machine Learning hosts.
Endpoint: /{projectKey}/recommendations/general-categories
Method: GET
OAuth 2.0 Scopes: view_products:{projectKey}
Response Representation: PagedQueryResult with results containing an array of GeneralCategoryRecommendation, sorted by confidence scores in descending order.

Query Parameters:

productImageUrl - String (URL-encoded) - Either productName or productImageUrl is required
URL to a product image.
productName - String (URL-encoded) - Either productName or productImageUrl is required
Name of the product that should get category recommendations (best results with English names).
confidenceMin - Float - Range [0.0 - 1.0] - Default: 0.01
confidenceMax - Float - Range [0.0 - 1.0] - Default: 1.0
limit - Number - Optional - Range: [1-20] - Default: 3
offset - Number - Optional - Default: 0

Examples

Example Request with an ImageTerminal

$curl -G -H "Authorization: Bearer {access_token}" \
--data-urlencode productImageUrl="https://storage.googleapis.com/ctp-playground-ml-public/hoodie.jpg" \
--data limit=3 \
"https://ml-{mlRegion}.europe-west1.gcp.commercetools.com/{projectKey}/recommendations/general-categories"

Example Responsejson

{
  "count": 3,
  "total": 20,
  "offset": 0,
  "results": [
    {
      "categoryName": "hoodies",
      "confidence": 0.42429
    },
    {
      "categoryName": "sweaters",
      "confidence": 0.0289
    },
    {
      "categoryName": "sweatshirts",
      "confidence": 0.0164
    }
  ]
}

Example Request with a Product NameTerminal

$curl -G -H "Authorization: Bearer {access_token}" \
--data-urlencode productName="Madison Drop Cap - 100% Cotton - Available In Duke Blue/Red - Now On Sale" \
--data limit=3 \
"https://ml-{mlRegion}.europe-west1.gcp.commercetools.com/{projectKey}/recommendations/general-categories"

Example Responsejson

{
  "count": 3,
  "total": 11,
  "offset": 0,
  "results": [
    {
      "categoryName": "headwear",
      "confidence": 0.06584
    },
    {
      "categoryName": "caps",
      "confidence": 0.0279
    },
    {
      "categoryName": "women",
      "confidence": 0.02391
    }
  ]
}