Documentation
BETA

Image Search

This feature is part of our Machine Learning APIs that are available in the Google Cloud Regions in Europe and North America.

Product search with images using machine learning.

The Image Search API provides functionality to query a product catalog using an image. The Query endpoint returns images that are similar to the query image and the Product Variants that they are associated with.

To find similar images, the API performs reverse image search using computer vision. You can learn more about the Image Search API on the commercetools Tech Blog.

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

Good prediction quality can be achieved by images that are:

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

In contrast, prediction quality would be negatively impacted by images that:

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

For example:

product to category relationship

Activating the API

The Image Search API must first be activated for a Project 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. The Image Search API can support querying Projects with up to 500 000 Products.

It can take up to one week for the activation to be fully completed or for changes to Product images to be reflected in the image search results. If you would like to reduce this delay for your Project or if you have a Project with more than 500 000 Products, please contact 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
}