Image Search

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

By default, the API is not enabled for commercetools projects. If you would like to activate the API, please contact us via our platform support.

Representations

SimilarImage

ProductVariantMatch

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}/image-search
Method: POST
OAuth2 Scopes: view_products:{project_key}
Response Representation: PagedQueryResult with a results 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 5MB and image file encoding must be one of [.jpg, .jpeg, .png].

$curl -X POST \
-H "Authorization: Bearer {access_token}" \
-H "Content-Type: image/jpeg" \
--upload-file "{image_file}" \
"https://ml-eu.europe-west1.gcp.commercetools.com/{project_key}/image-search?limit=3"
{
"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
}