Documentation
BETA

Image Search

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

Product search with images using machine learning.

The Image Search endpoint queries a product catalog using an image. The endpoint returns images which are similar to the query image and the product variants that they are associated with.

A technical blog post about how the feature works can be read here.

The quality of predictions is highest when the product in the image is aligned centrally and the image is taken in a similar style to that of images in the product database.

For example:

product to category relationship

Good quality images are:

  • Aligned centrally
  • On a solid colored or neutrally colored background
  • Well lit and show the image's borders

Bad quality images:

  • Show the product in an incomplete manner, such as having arms or other items overlapping the product
  • Have a busy or non-uniform background
  • Have no clear product outline.

Activating the API

Before using the image search API, a project must first be activated through a request to the ImageSearchConfig endpoint. To see results for a search query, a project must have one or more products with images included in the product variant images field. It takes up to one week for new or updated images to appear in search results. Additionally, for the time being, the image search API can be activated for projects with fewer than 500 thousand products. If you would like to reduce this delay for your project, or if you have a project with greater than 500 thousand products, please contact us via our platform support.

Representations

ImageSearchConfig Request

  • actions - Array of UpdateActions - Required
    The list of update actions to be performed on the project.

ImageSearchConfig Response

  • status - String - "on" or "off"
    The image search activation status.
  • lastModifiedAt - DateTime

Update actions

Change Status

  • action - String - "changeStatus" - Required
  • status - String - "on" or "off" - Required
    Activate or deactivate the image search API.

Query

Add or update a config

Host: one of the Machine Learning hosts.
Endpoint: /{projectKey}/image-search/config
Method: POST
OAuth 2.0 Scopes: view_products:{projectKey}
Request Representation: ImageSearchConfig Request
Response Representation: ImageSearchConfig Response

Fetch a config

Host: one of the Machine Learning hosts.
Endpoint: /{projectKey}/image-search/config
Method: GET
OAuth 2.0 Scopes: view_products:{projectKey}
Response Representation: ImageSearchConfig Response

Querying with images

Representations

SimilarImage

ProductVariantMatch

Query

Host: one of the Machine Learning hosts.
Endpoint: /{projectKey}/image-search
Method: POST
OAuth 2.0 Scopes: view_products:{projectKey}
Response Representation: PagedQueryResult with results containing an array of SimilarImage, sorted by most similar images first.

Headers:

  • Content-Type - one of image/jpg, image/jpeg or image/png.

Query Parameters:

  • limit - Number - Optional
    Range: [1-500] - Default: 10
  • offset - Number - Optional
  • staged - Boolean - Optional - Default: false

Body: The raw binary data of the image.

Examples

Note: File uploads are limited to 5 MB and image file encoding must be one of [.jpg, .jpeg, .png].

Example Request for Image SearchTerminal
$curl -X POST \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: image/jpeg"  \
  --upload-file "{image_file}" \
  "https://ml-{mlRegion}.europe-west1.gcp.commercetools.com/{projectKey}/image-search?limit=3"
Example Responsejson
{
    "count": 3,
    "offset": 0,
    "results": [
        {
            "imageUrl": "https://s3-eu-west-1.amazonaws.com/commercetools-maximilian/products/081508_1_medium.jpg",
            "productVariants": [
                {
                    "product": {
                        "id": "0f5feac3-b50f-447b-8c36-7603153a2dd0",
                        "typeId": "product"
                    },
                    "variantId": 1
                }
            ]
        },
        {
            "imageUrl": "https://s3-eu-west-1.amazonaws.com/commercetools-maximilian/products/081796_1_large.jpg",
            "productVariants": [
                {
                    "product": {
                        "id": "8a7f5101-8b20-4ba6-8988-ff43dbf35d3d",
                        "typeId": "product"
                    },
                    "variantId": 1
                }
            ]
        },
        {
            "imageUrl": "https://s3-eu-west-1.amazonaws.com/commercetools-maximilian/products/079533_1_medium.jpg",
            "productVariants": [
                {
                    "product": {
                        "id": "15245f8f-478b-426a-b3a9-41e8257f39d9",
                        "typeId": "product"
                    },
                    "variantId": 1
                },
                {
                    "product": {
                        "id": "a315869c-3d78-476c-99d1-3dec4375a97a",
                        "typeId": "product"
                    },
                    "variantId": 1
                },
                {
                    "product": {
                        "id": "a315869c-3d78-476c-99d1-3dec4375a97a",
                        "typeId": "product"
                    },
                    "variantId": 1
                }
            ]
        }
    ],
    "total": 100
}