Category Recommendations

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 our 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.

The feature can also be used in our Merchant Center.

Activation Criteria

By default, the API is enabled for commercetools projects that match the following criteria:

  • The project is flagged as a production project by commercetools.
  • The project contains at least one category and product.
  • The project does not contain more than 50000 categories.

If your project does not match these criteria (e.g., if it is an evaluation project or the number of categories in your project is above the limit), but you are still interested in testing the API, do not hesitate to contact us via the platform support.

Representations

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 (Europe): https://ml-eu.europe-west1.gcp.commercetools.com
Host (United States): https://ml-us.europe-west1.gcp.commercetools.com
Endpoint: /{project_key}/recommendations/project-categories/{product_id}
Method: GET
OAuth2 Scopes: view_products:{project_key}
Response Representation: PagedQueryResult with a results 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

$curl -G -H "Authorization: Bearer {access_token}" \
--data staged=true \
--data limit=2 \
"https://ml-eu.europe-west1.gcp.commercetools.com/{project_key}/recommendations/project-categories/{product_id}"
{
"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 (Europe): https://ml-eu.europe-west1.gcp.commercetools.com
Host (United States): https://ml-us.europe-west1.gcp.commercetools.com
Endpoint: /{project_key}/recommendations/general-categories
Method: GET
OAuth2 Scopes: view_products:{project_key}
Response Representation: PagedQueryResult with a results 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 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

$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-eu.europe-west1.gcp.commercetools.com/{project_key}/recommendations/general-categories"
{
"count": 3,
"total": 20,
"offset": 0,
"results": [
{
"categoryName": "hoodies",
"confidence": 0.42429
},
{
"categoryName": "sweaters",
"confidence": 0.0289
},
{
"categoryName": "sweatshirts",
"confidence": 0.0164
}
]
}
$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-eu.europe-west1.gcp.commercetools.com/{project_key}/recommendations/general-categories"
{
"count": 3,
"total": 11,
"offset": 0,
"results": [
{
"categoryName": "headwear",
"confidence": 0.06584
},
{
"categoryName": "caps",
"confidence": 0.0279
},
{
"categoryName": "women",
"confidence": 0.02391
}
]
}