Documentation
BETA

Machine Learning

This document gives an overview of the characteristics and machine learning features.

Machine learning features of the commercetools platform provide automated predictions by autonomously learning from data. In general, these features make use of artificial intelligence to reduce the amount of manual work that is required to manage projects. For example, machine learning can be used to automatically predict which of potentially thousands of available categories fit best to a given product.

Since the machine learning features are in an early stage of development, your feedback can have a large impact. If there is anything you would like to tell us (positive experiences, criticism, or requests for new features), please contact us via the platform support.

Currently, the following machine learning features are available:

Difference from other endpoints

Compared to other endpoints of the commercetools platform, machine learning features have some characteristic differences:

  • The results are based on probabilities and have a margin of error, which is indicated by confidence scores in the responses (0.0 is low, 1.0 is high).
  • The response times are typically longer since the underlying computations can be complex.
  • Most of the endpoints are based on Asynchronous Requests.

Hosts

The Machine Learning API has different hosts from the HTTP API. The Machine Learning API is hosted at the following URLs:

RegionAPI URL
North America (Google Cloud, Iowa)https://ml-us.europe-west1.gcp.commercetools.com/
Europe (Google Cloud, Belgium)https://ml-eu.europe-west1.gcp.commercetools.com/

If documentation refers to https://ml-{mlRegion}.europe-west1.gcp.commercetools.com/, the {mlRegion} placeholder has to be replaced with us or eu respectively.

The Machine Learning APIs are available in the Google Cloud Regions except Australia (Google Cloud, Sydney).

Confidence filtering

Queries for a collection of predictions can optionally provide confidence bounds on the returned predictions. This allows users to specify that the endpoint should only return those predictions about which we are more confident than confidenceMin and less confident than confidenceMax.

Asynchronous requests

Requests for most of the Machine Learning APIs (currently Similar Products and Missing Data) are asynchronous. That is because the number of products searched affects the time required to perform the search. To manage this delay, these APIs have an initiation endpoint and a status endpoint.

First, a POST request to the initiation endpoint starts the search, and returns a status URI. Next, a GET request to the status endpoint polls the status URI to receive the results.

Status polling requests return one of two statuses:

  • PENDING: A search started and is awaiting completion, or the task ID does not exist.
  • SUCCESS: A search completed.

If a search completes unsuccessfully, the status endpoint returns an error response. After completing a search, the status endpoint serves the results for one day.

Representations

These representations are shared by all Machine Learning API endpoints that are based on Asynchronous Requests.

TaskStatus

A response wrapper for an Asynchronous Request.

  • state - String
    One of PENDING or SUCCESS, as described in Asynchronous Requests.
  • expires - DateTime
    The expiry date of the result. You cannot access the result after the expiry date. Default: 1 day after the result first becomes available. This is only available when the TaskStatus state is SUCCESS.
  • result - Any Type
    The response to an asynchronous request. The type depends on the request initiated. Only populated when the status is SUCCESS.

TaskToken

Represents a URL path to poll to get the results of an Asynchronous Request.

  • taskId - String
    The ID for the task. Used to find the status of the task.
  • uriPath - String
    The URI path to poll for the status of the task.