Visual Search API

This API fetches a list of objects identified from the uploaded image. It also returns similar product recommendations for the items detected in the image.

Endpoints

Path Parameters

Parameter	Type	Description	Required
widget_id	string	The ID of the widget, which can be found in the Widget Configurator in the Dashboard.	required

Query Parameters

Parameter	Type	Description	Required
account_id	integer	Your site's numerical Bloomreach account ID. Your Bloomreach representative gives your site's account ID to you before or during your integration kickoff meeting.	required
domain_key	string	Your site domain's ID, which Bloomreach provides during initial scoping and integration. This ID is for the domain that you want to receive your Bloomreach API requests. This parameter identifies the specific site version when the one account ID hosts multiple site versions with unique characteristics, such as language versions.	required
url	string	The absolute URL of the page where the request is initiated. Do not use a relative URL.	required
_br_uid_2	string	A first-party cookie created by the Bloomreach tracking pixel library (BrTrk). This cookie creates a unique, anonymous identifier for every browser or device. Use the default value provided, which is already encoded. `&_br_uid_2=uid%3D7797686432023%3Av%3D11.5%3Ats%3D1428617911187%3Ahc%3D55`	required
image_id	string	You’ll get this value in the Upload API response once an image is uploaded. You can use image_id to make any number of subsequent queries for widget responses (with different parameters/filters and objects) without the need to re-upload.	optional
item_ids	string	Item ID/PID of item for which we want visual recommendations. Passing this parameter makes it a Visual Recommendations request.	optional
sku_id	string	If you have SKUs in the catalog, sku_id should be passed, else this can be skipped.	optional
fields	string	A comma-separated list of fields to be sent in the request. Alternatively, you may configure the fields in the Widget Configurator in the Dashboard instead. This parameter is required if not sent via the Dashboard.	optional
rows	integer	The number of matching items to return per results page in the API response. The maximum value is 200. The result size is used from the Dashboard if it is not sent in the API. To enhance performance, limit this value to the number of items that you think is reasonable for a single page of search results.	optional
object_id	integer	By default, you will get the recommendations for the whole image you uploaded if you make an API call without the object_id [denoted by -1]. To get more targeted results, you can also make API calls specific to object_ids.	optional
filter	string	The filter parameter applies a faceted filter to the returned products, searching for products that fit your parameter values. Any facet that you want to filter must be in your feed. Attributes must be enabled and mapped by Bloomreach. Let your Bloomreach representative know which attributes in your content feed you want to apply as filters to search results. You can filter results based on numeric ranges. For example, &filter=(price:["100" TO ""]). To provide multiple filters, send multiple filter parameters. For example, &filter=(price:["" TO "100"])&filter=(color_groups: ("blue"))	optional

Header

Parameter	Type	Description	Required
auth_key	string	The unique key shared during the integration phase. This is used to authenticate a merchant API call.	required

Visual Recommendations API

The Visual Recommendations API fetches a list of objects identified from the Item ID and SKU ID combination passed in the query. It also returns similar product recommendations for the objects detected in the image.

A Visual Search Request is considered as a Visual Recommendations request based on the combination of values of the image_ids, item_ids and sku_id parameters as follows:

`image_id` passed	`item_ids` passed	`sku_id` passed	Request Type
Yes	No	No	Visual Search
No	Yes	No	Visual Recommendations
No	Yes	Yes	Visual Recommendations
Yes	Yes	Yes/No	Invalid Request - Cannot pass image_id and item_ids together
No	No	Yes/No	Invalid Request - Pass either image_id or item_ids

Note that it is mandatory to pass the item_ids parameter for a Visual Recommendations API Request.

Response Example

The response lists the identified objects and retrieves similar product recommendations for all the objects.

If you make a call with object_id, you’ll get targeted results. In the example below, product suggestions are displayed for the object with the "object_id": "1".

{

"response": {
        "numFound": 2,
        "start": 0,
        "docs": [
            {
                "brand": "GA",
                "skuid": "sku211482439",
                "pid": "prod253090443",
                "thumb_image": "https://media.homeoasis.com/f_auto,q_auto/w_1200,h_1500/01/nm_4357250_100380_m",
                "variants": [
                    {
                        "skuid": "sku211482439"
                    }
                ],
                "price": 2095.0
            },
            {
                "brand": "GA",
                "skuid": "sku215611655",
                "pid": "prod258280236",
                "thumb_image": "https://media.homeoasis.com/f_auto,q_auto/w_1200,h_1500/01/nm_4484851_100380_m",
                "variants": [
                    {
                        "skuid": "sku215611655"
                    }
                ],
                "price": 3995.0
            }
        ]
    },
    "objects": [
        {
            "id": 1,
            "bbox": [
                0,
                180,
                490,
                817
            ],
"object_type": "dress",
        },
        {
            "id": 2,
            "bbox": [
                236,
                698,
                273,
                822
            ],
"object_type": "shoe",
        }
    ],
    "metadata": {
        "widget": {
            "id": "79opvm5j",
            "name": "preview",
            "description": "preview",
            "type": "visual_search",
            "rid": "e8811c01-a2f7-4907-a65d-ad42635f8d0e"
        },
        "response": {
           "personalized_results": false,
            "fallback": "",
            "recall": "pure"
        },
        "query": {
            "image_id": "3d4b4331763c31b39da02704d48e890f90c36ef6b4835eface4820a3e1127987",
            "object_id": "1"
        }
    }
}

{
  "response": {
    "numFound": 19,
    "start": 0,
    "docs": [
      {
        "title": "Melissa Techno Cotton Pants, Black",
        "thumb_image": "https://www.neimanmarcus.com/product_assets/B/2/X/X/5/NMB2XX5_mk.jpg",
        "pid": "prod178830492"
      }
    ]
  },
  "objects": [
    {
      "id": 1,
      "bbox": [
        136,
        0,
        255,
        13
      ],
      "parent_category": "N/A",
      "category": "N/A"
    },
    {
      "id": 2,
      "bbox": [
        121,
        6,
        272,
        414
      ],
      "parent_category": "lowerbody",
      "category": "pants"
    },
    {
      "id": 3,
      "bbox": [
        148,
        429,
        190,
        479
      ],
      "parent_category": "N/A",
      "category": "N/A"
    },
    {
      "id": 4,
      "bbox": [
        202,
        431,
        240,
        479
      ],
      "parent_category": "N/A",
      "category": "N/A"
    }
  ],
  "metadata": {
    "widget": {
      "id": "preview",
      "name": "preview",
      "description": "preview",
      "type": "visual_search",
      "rid": "53f36486-7637-456c-a8eb-f5831ac2ec94"
    },
    "response": {
      "personalized_results": false,
      "fallback": "",
      "recall": "pure"
    },
    "query": {
      "image_id": null,
      "object_id": -1,
      "visual_search_request_type": "recommendations_request"
    }
  }
}