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.

Endpoint

Request Method: Post

Sample

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

Request Method: Get

Sample

{
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

Authentication is done using API Keys and Sitekeys, which are generated during the account creation process and can be found in the Console under Manage -> Configure Site -> Keys.

Uploading Images

Upload Using Public Image URL

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" }'

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

Make sure you replace {site_key} with your actual site key, and API Key with the API key you’re using for authorisation.

Here is how an Image to Base64 Encoder splits out data

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

Here’s how to read this data

data:,

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

Here are the supported mime types

image/jpeg;base64
image/png;base64
image/tiff;base64

Headers

The following parameters are available:

Parameter	Description
unbxd-user-id	The Unbxd Analytics javascript sets a unique identifier in your browser’s cookie referred to as the userid. For example, uid-1466015353887-20419.
user-agent	In each HTTPS request, the user-agent identification information is passed to the web server
unbxd-device-type	Unbxd-device-type is a custom Unbxd header that identifies if the request originated from an app.
<style=”font-weight: 400; font-size: 16px;”>X-Forwarded-For	<style=”font-weight: 400; font-size: 16px;”> In this header, the IP address of the end user is identified. This is crucial in the case of a backend integration, since Unbxd cannot obtain the end-user’s IP address from the browser.
Content-Type	This header signifies the content type of the request being sent. application/json; image/; base64image/ * currently supported – Jpg/JPEG, PNG, TIFF

*unbxd-device-type:

 *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:

PNG: image/png
JPEG/JPG: image/jpg
TIFF: image/tiff

Request Parameters

The values of the request parameters are defined below:

Parameter	Description	DataType	Possible Values/Format
version Mandatory	The version parameter specifies the API version. To access the latest features, always pass v2 with every API call.	String	Supported Values:v2
user-type Mandatory	The number of times a user visits the site. Possible values include frequent and first-time users.	String	Format: “first-time” Supported Valuesfirst-time, frequent
uid Mandatory	Visitors are identified by a unique identification id, which can be obtained from the unbxd.userId browser cookie.	String	&uid=uid-1666356549013-78531
format Optional	A format parameter specifies the format in which the response result will be generated,	String	Format: &format=xml Supported values: JSON, XML Default Value: JSON
start Optional	The start parameter is used to offset the results by a specific number.	Integer	Format: &start=2 Default Value: 0
page optional	Displays the right set of products with respect to the number of products shown on one page(rows parameter).	Integer	Format: &page=2
rows optional	Paginate the results of a query	Integer	Format: &rows=2 Default Value: 10
variants	Displays variants of the same product	Boolean	Format: &variants=True Supported Values: True ,False Default value: False.
variants.count	Displays multiple defined variants of a product.	Integer	Format: &variants.count=5
fields	Defines attributes for a product like color, size etc.	String	Format: &fields=, Default Values: If not applied, returns all fields
bucket.field	Allows to group products with a common field value into groups known as buckets, returning the top products per bucket.	String	Format: &bucket.field=,
bucket.limit	Determines the number of products in a bucket	Integer	Format: &bucket.limit=10 Default Value: 10
bucket.offset	To Paginate to the next 5 products of the group	Integer	Format: &bucket.offset=10
rows	Determines the number of buckets that are displayed at a time in case bucketing is done on a field.	Integer	Format: &rows=10
analytics	Enables or disables tracking the query hit for analytics.	String	Default value: Tracking is enabled
stats	Gives information about the products with highest and lowest field value.		Format: fieldName *(only numerical fields)

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.

Component	Description
ID	“id”: “ad85491c-9d2b-4cab-900a-df96aa11f0d9”, When an image is uploaded we assign a UUID to it.
Boxes	Boxes have array of bounding boxes for an image. These bounding boxes can be used to retrieve the search results related to the bounding box. boxes: [{ box.url }] has URL that can directly be accessed to get the results for that specific bounding box.
Selected	selected: stores the ID of the bounding box that has been selected
status	Response status code defines if it is Ok (code 200), Not Found (code 404), Internal server error (code 500), and many more
queryTime	Time is taken to process the shopper’s request
queryParams	Parameters sent as a part of the request
numberOfProducts	A total number of products returned for the page.
start	Offset in the complete result set of products for the page
products	Product details are sent as a result that matches the request query. The structure will be the same as passed in the feed.
relevantDocument	Mentions if the parent or the variant for a particular product needs to be displayed in the UI. It can be either ”parent” or “variant”
facets	Filters which are displayed in the UI to allow visitors to narrow down result set based on product fields
breadcrumb	Position in the field hierarchy
selected	Filters which are selected in the UI

Did this answer your question?
Yes!
Nice work, I love it.

No…
I have some feedback

On this Section

User ID method
Request ID method
Analytics method
Tracking Visitor Event
Category Page Event
Product Click Event
Add to Cart event
Order event
Cart Removal event
Autosuggest event
Recs Widget Impression
Search Impression
Category Page Impression
Dwell Time
Facet Event

Visual Search API

Integrate Visual Search Functionality with Unbxd Visual Search API

Endpoint

Request Method: Post

Request Method: Get

Sample

Authentication

Uploading Images

Upload Using Public Image URL

Request Method: Post

Request Method: Get

Image Uploaded as multipart/form-data

Upload Image by sending Base64 Encoding

Headers

The following parameters are available:

Supported Image Types:

Request Parameters

API Response

A search API response comprises of

Response Components

Yes!

No…

On this Section