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.

📘

Image Requirements And Best Practices

To ensure optimal performance and accurate results, follow these image guidelines:

1. Recommended Limits File Size.

• Ideal: ≤ 500 KB

• Maximum recommended: ≤ 1 MB

2. Resolution

• Recommended: ≤ 1000px (longest side) (Avoid: Images larger than 2000px)

3. Large images (like 3–4MB, 4000px+) may result in API timeouts Return 0 results. In this case, be routed to alternate processing pipelines like mimir.image_search.
4. Supported formats include JPEG, PNG, TIFF, HEIC, and HEIF.

❗Recommended : Approach Resize images on the client side before uploading Maintain ≤1000px resolution on the longest side Compress images before Base64 encoding

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/......'

📘

Note

Ensure (site_key) is replaced with your actual site key, and API Key with the API key you are using for authorisation.

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.

📘

Note

The dd.tag field is an internal Datadog logging tag used for monitoring and observability. It does not affect request routing or search results.

All image search requests are handled by the mimir pipeline, which orchestrates calls to downstream AI services.

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.