Overview

The Visual Search API allows you to seamlessly integrate with the Unbxd platform and effortlessly incorporate all functionalities related to visual search. It enables you to display search results for an image from the array of products that match the visual cues.

You can use the JSON /XML response format and leverage various built-in features. All API requests must be made over HTTPS.

Sample Request: Method POST

{  
curl -X POST 
'https://search.unbxd.io/v2.0/sites/{site_key}/images' 
-H 'Authorization: API Key' 
-H 'Content-Type: application/json'
}

Sample Request: Method GET

{  
curl -X GET "https://search.unbxd.io/v2.0/sites/(site_key)/images?imageUrl=https://some.site/images/image.png" 
-H "Authorization: API Key"
}

Authentication

Log in to Netcore Unbxd console and naviagte to Configure Site > Keys.

Authentication is done using API Keys and Sitekeys, which are generated during the account creation process.

Uploading Images

Upload Using Public Image URL.

Sample Request: Method POST

curl --location '/v2.0/sites/{site_key}/images' 
--header 'Content-Type: application/json' 
--header 'Authorization: API Key' 
--data '{ "imageUrl": "http://example.com/img/1.jpg" }'

Sample Request: Method GET

curl --location 'v2/sites/(site_key)/images?imageUrl=http%3A%2F%2Fexample.com%2Fimages%2F1.jpg' \\\
\--header 'Authorization: API Key'

Image Uploaded as Multipart/ Form-data

curl --location '/v2.0/sites/(site_key)/images' \\\
\--header 'Authorization: API Key' \
\--form 'image=@"./scripts/test/test.png"'

Upload Image by Sending Base64 Encoding

curl --location '/v2.0/sites/(site_key)/images' \\\
\--header 'Content-Type: image/png;base64' \
\--header 'Authorization: API Key' \
\--data 'iVBORw0KGgoAAAANSUhEUgAAAq4AAAIdCAYAAAD8of/......'

Here is how an Image to Base64 Encoder splits out data

data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/4QC2.....TP/9k=

Read this data as:

 data:<mime-type>,<raw-image-data>
  </raw-image-data></mime-type>

When using this API, emit the mime-type within the content-type header as shown above, along with raw-image-data within the body.

Here are the supported mime types:

• image/jpeg;base64
• image/png;base64
• image/tiff;base64
• image/heic
• image/heif

Headers

The following parameters are available:

unbxd-device-type

{ "type":"tablet" , "os": "iOS" , "source": "app" }

• Possible values of “type” : “desktop”, “tablet”, “mobile”
• Possible values of “os” : “android”, “ios”, “windows”
• Possible values of “source” : “browser”, “app”`
• Supported Image Types (Refer the table below)

Request Parameters

The values of the request parameters are defined below:

API Response

"searchMeta"
...
"queryParams": { ... },
"image": {
"id": "ad85491c-9d2b-4cab-900a-df96aa11f0d9",
"boxes": [{
"id": 1089,
"vertices": [{
"x": 164.07107543945312,
"y": 352.81292724609375
},
{
"x": 188.38121032714844,
"y": 384.0833435058594
}
],
"url": "/v2.0/sites//images/ad85491c-9d2b-4cab-900a-df96aa11f0d9/boxes/1089"
}{
"id": 811,
"vertices": [{
"x": 147.3377685546875,
"y": 68.75267028808594
},
{
"x": 255.28317260742188,
"y": 340.2548522949219
}]
"url": "/v2.0/sites//images/ad85491c-9d2b-4cab-900a-df96aa11f0d9/boxes/811"
},
...
...
],
"selected": 1089
},
...

A search API response comprises of

• searchMetaData
• response
• And some other high level fields of the response.

The above JSON gets added in searchMetaData block, besides queryParams.

Response Components

Unbxd returns the list of products that match the search criteria. The response would be in application/JSON or application/XML content type format.

Error Handling

Visual Search validates the uploaded image before processing it. If the image cannot be processed, the API returns a specific error code that identifies the reason for the failure.

Use the error code from the API response to identify the issue and display an appropriate message to the user.

Error codes

The following error codes are returned when an image cannot be processed:

Error code details

Handling Errors in Your Application

When the API returns an error, use the error code to determine the appropriate action or message to display to the user. For example:

Note: These error codes help you identify why an image could not be processed and provide meaningful feedback to users.

Image requirements

To minimize image-processing errors, make sure the image meets the Visual Search requirements before sending the request.

If an image does not meet these requirements, the API returns the corresponding error code.

Switch Between Detected Products

Multi-Object Detection: Switching Between Detected Products

When an uploaded image contains multiple distinct items, a rug and a sofa in a room photo, or a shirt and jeans in an outfit photo, the API detects each item as its own box in the boxes array. There are three ways to handle this on the frontend:

• Keep default behavior: The system automatically returns results for the box with the largest area. No extra integration work needed.

• Let users switch between auto-detected boxes: Surface the detected boxes in the UI so a user can toggle between, e.g., rug results and sofa results, or shirt results and jeans results.

curl --location --request GET 'https://search.unbxd.io/v2.0/sites/{site_key}/images/{image-id}/boxes/{box-id}' \
  --header 'Authorization: {api_key}' \
  --header 'Content-Type: application/json'

Pagination

The boxes endpoint supports the same pagination parameters as the main search API (page, start, rows). Append them the same way, on top of whichever box-id is currently selected:

curl --location --request GET 'https://search.unbxd.io/v2.0/sites/{site_key}/images/{image-id}/boxes/{box-id}?page=2' \
  --header 'Authorization: {api_key}' \
  --header 'Content-Type: application/json'

Paginating does not change the selected box - it only pages through that box's own result set. Switching boxes and paginating are independent actions against the same endpoint.