visearch sdk javascript
5.0.0 Release
ViSenze's Javascript SDK provides accurate, reliable and scalable image search APIs within our catalogs. The APIs included in this SDK aims to provide developers with endpoints that executes image search efficiently while also making it easy to integrate into webapps.
Note: In order to use any of our SDKs, you are required to have a ViSenze developer account. You will gain access to your own dashboard to manage your appkeys and catalogs. Visit here for more info.
Follow these simple steps to get familiarized with how the SDK can be integrated and how it actually works by exploring our demos included in the main repo.
If you are using the project provided directly from the main repo, you can simply run the following command from the root directory of this project:
npm install
If you are trying to include this SDK into your own project via npm, run the following command from the root directory of your project:
npm install visearch-javascript-sdk
In Node
import ViSearch from 'visearch-javascript-sdk';
...
const visearch = ViSearch();If you have multiple placements or if you want to run placements with different configurations, you would need to create multiple ViSearch instances.
const visearch1 = ViSearch();
const visearch2 = ViSearch();In browser
If you wish to include the SDK directly onto your webpage, add this to the header of your site
<script type="text/javascript">
!function(e,t,r,s,a){if(Array.isArray(a))for(var n=0;n<a.length;n++)o(e,t,r,s,a[n]);else o(e,t,r,s,a);function o(e,t,r,s,a){var n=e[a]||{};e[a]=n,n.q=n.q||[],n.factory=function(e){return function(){var t=Array.prototype.slice.call(arguments);return t.unshift(e),n.q.push(t),n}},n.methods=["set","setKeys","sendEvent","sendEvents","productMultisearch","productMultisearchAutocomplete","productSearchByImage","productSearchById","productRecommendations","productSearchByIdByPost","productRecommendationsByPost","setUid","getUid","getSid","getLastQueryId","getSessionTimeRemaining","getDefaultTrackingParams","resetSession","resizeImage","generateUuid",];for(var o=0;o<n.methods.length;o++){var i=n.methods[o];n[i]=n.factory(i)}if(e.viInit)viInit(e,a);else{var c,d,u,f,g,m=(c=t,d=r,u=s,(f=c.createElement(d)).type="text/javascript",f.async=!0,f.src=u,(g=c.getElementsByTagName(d)[0]).parentNode.insertBefore(f,g),f);m.onload=function(){viInit(e,a)},m.onerror=function(){console.log("ViSearch Javascript SDK load fails")}}}}(window,document,"script","https://cdn.visenze.com/visearch/dist/js/visearch-5.0.0.min.js","visearch");
script>Copy the same code but change the keyword "visearch" into an array of your desired instances names.
<script type="text/javascript">
...(window,document,"script",0,["visearch", "visearch2"]);
script>Before you can start using the SDK, you will need to set up . Most of these keys can be found in your account's dashboard.
Please take a look at the table below to understand what each key represents:
| Key | Importance | Description |
|---|---|---|
| app_key | Compulsory | All SDK functions depends on a valid app_key being set. The app key also limits the API features you can use. |
| placement_id | Compulsory | Placement id of the current placement |
| endpoint | Situational | Default is https://search.visenze.com/
|
| timeout | Optional | Defaulted to 15000 |
| uid | Optional | If this is not provided, we will auto generate the uid |
Set up the ViSearch instance(s) with the keys from console.
visearch.set('app_key', 'YOUR_APP_KEY');
visearch.set('placement_id', 'YOUR_PLACEMENT_ID');
visearch.set('timeout', TIMEOUT_INTERVAL_IN_MS);or
visearch.setKeys({
'app_key': 'YOUR_APP_KEY',
'placement_id': 'YOUR_PLACEMENT_ID'
});
visearch2.setKeys({
'app_key': 'YOUR_APP_KEY_2',
'placement_id': 'YOUR_PLACEMENT_ID_2'
});or
if you are in a Node env, you can pass the configs in directly when creating the ViSearch client.
const visearch = ViSearch({
'app_key': 'YOUR_APP_KEY',
'placement_id': 'YOUR_PLACEMENT_ID'
})The demo is only applicable to those who work directly off the main repo. You are required to have a Node.js environment and remember to fill up the relevant files.
Create a
.envfile and fill in the relevant app key and placement id
SEARCH_APP_KEY =
SEARCH_PLACEMENT_ID =
SEARCH_IM_URL =
REC_PID =
REC_APP_KEY =
REC_PLACEMENT_ID =
ENDPOINT =
To run the webpage demo:
npm run start-demoAfter the above command, you should see that the server is running locally on your device. You can then access the different demo webpages in your browser by using this format http://localhost:3000/examples/*.html.
http://localhost:3000/examples/product_search_by_id.html
http://localhost:3000/examples/product_search_by_image.html
http://localhost:3000/examples/tracking.html
POST /product/search_by_image
Searching by Image can happen in three different ways - by url, id or File.
Using image id:
const parameters = {
im_id: 'your-image-id'
};
const onResponse = (response)=> {
// TODO handle response
}
const onError = (error)=> {
// TODO handle error
}
visearch.productSearchByImage(parameters, onResponse, onError);Using image url:
const parameters = {
im_url: 'your-image-url'
};
const onResponse = (response)=> {
// TODO handle response
}
const onError = (error)=> {
// TODO handle error
}
visearch.productSearchByImage(parameters, onResponse, onError);Using image file:
<form>
Upload image: <input type="file" id="fileUpload" name="fileInput"><br>
<input type="submit" value="Submit">
form>const parameters = {
image: document.getElementById('fileUpload')
};
const onResponse = (response)=> {
// TODO handle response
}
const onError = (error)=> {
// TODO handle error
}
visearch.productSearchByImage(parameters, onResponse, onError);The request parameters for this API can be found at ViSenze Documentation Hub.
GET /product/recommendations/{product_id}
Search for visually similar products in the product database giving an indexed product’s unique identifier.
const product_id = 'your-product-id';
const parameters = {
};
const onResponse = (response)=> {
// TODO handle response
}
const onError = (error)=> {
// TODO handle error
}
visearch.productRecommendations(product_id, parameters, onResponse, onError);The request parameters for this API can be found at ViSenze Documentation Hub.
POST /product/multisearch
Multisearch can happen in four different ways - by text, url, id or File.
Using text:
const parameters = {
q: 'your-text-query'
};
const onResponse = (response)=> {
// TODO handle response
}
const onError = (error)=> {
// TODO handle error
}
visearch.productMultisearch(parameters, onResponse, onError);Using image id:
const parameters = {
im_id: 'your-image-id'
};
const onResponse = (response)=> {
// TODO handle response
}
const onError = (error)=> {
// TODO handle error
}
visearch.productMultisearch(parameters, onResponse, onError);Using image url:
const parameters = {
im_url: 'your-image-url'
};
const onResponse = (response)=> {
// TODO handle response
}
const onError = (error)=> {
// TODO handle error
}
visearch.productMultisearch(parameters, onResponse, onError);Using image file:
<form>
Upload image: <input type="file" id="fileUpload" name="fileInput"><br>
<input type="submit" value="Submit">
form>const parameters = {
image: document.getElementById('fileUpload')
};
const onResponse = (response)=> {
// TODO handle response
}
const onError = (error)=> {
// TODO handle error
}
visearch.productMultisearch(parameters, onResponse, onError);The request parameters for this API can be found at ViSenze Documentation Hub.
POST /product/multisearch/autocomplete
Multisearch autocomplete can happen in four different ways - by text, url, id or File.
Using text:
const parameters = {
q: 'your-text-query'
};
const onResponse = (response)=> {
// TODO handle response
}
const onError = (error)=> {
// TODO handle error
}
visearch.productMultisearchAutocomplete(parameters, onResponse, onError);Using image id:
const parameters = {
im_id: 'your-image-id'
};
const onResponse = (response)=> {
// TODO handle response
}
const onError = (error)=> {
// TODO handle error
}
visearch.productMultisearchAutocomplete(parameters, onResponse, onError);Using image url:
const parameters = {
im_url: 'your-image-url'
};
const onResponse = (response)=> {
// TODO handle response
}
const onError = (error)=> {
// TODO handle error
}
visearch.productMultisearchAutocomplete(parameters, onResponse, onError);Using image file:
<form>
Upload image: <input type="file" id="fileUpload" name="fileInput"><br>
<input type="submit" value="Submit">
form>const parameters = {
image: document.getElementById('fileUpload')
};
const onResponse = (response)=> {
// TODO handle response
}
const onError = (error)=> {
// TODO handle error
}
visearch.productMultisearchAutocomplete(parameters, onResponse, onError);The request parameters for this API can be found at ViSenze Documentation Hub.
Javascript does not contain type definitions and the REST API response for all our APIs will instead just convert straight into javascript objects. Here are some of the API's response object's keys to take note of:
| Name | Type | Description |
|---|---|---|
| status | string | The request status, either OK, warning, or fail
|
| imId | string | Image ID. Can be used to search again without reuploading |
| im_id | string | |
| error | object | Error message and code if the request was not successful i.e. when status is warning or fail
|
| product_types | object[] | Detected products' types, score and their bounding box in (x1,y1,x2,y2) format |
| result | object[] | The list of products in the search results. Important fields for first release. If missing, it will be set to blank. Note that we are displaying customer’s original catalog fields in “data” field |
| objects | object[] | When the search_all_objects parameter is set to true
|
| catalog_fields_mapping | object | Original catalog’s fields mapping |
| facets | object[] | List of facet fields value and response for filtering |
| page | number | The result page number |
| limit | number | The number of results per page |
| total | number | Total number of search result |
| reqId | string | ID assigned to the request made |
| Name | Type | Description |
|---|---|---|
| code | number | Error code, e.g. 401, 404 etc... |
| message | string | The server response message. |
| Name | Type | Description |
|---|---|---|
| box | number[] | The image-space coordinates of the detection box that represents the product. |
| type | string | The detected type of the product. |
| Name | Type | Description |
|---|---|---|
| product_id | string | The product's ID which can be used in Recommendations. |
| main_image_url | string | Image URL. |
| data | object | This data field is dependent on the metadata requested by user under here. |
The fields returned under here are dependent on the product metadata requested through the attrs_to_get params and the fields indexed in your catalog.
Other than that, we return 2 default fields.
| ViSenze pre-defined catalog fields | Client X's catalog original names |
|---|---|
| product_id | sku |
| main_image_url | medium_image |
When using the search_all_objects is set to true, the search response will return the results in a list of ProductObject instead of a list of Product directly. The difference is that ProductObject will split the products according to type.
| Name | Type | Description |
|---|---|---|
| result | object[] | The list of products belonging to this type. |
| total | number | The total number of results in this type. |
| type | string | The detected type of the product. |
| box | number[] | The image-space coordinates of the detection box that represents the product. |
Facets are used to perform potential filtering of results.
| Name | Type | Description |
|---|---|---|
| key | string | |
| items | object[] | |
| range | object |
To check usage guideline, please refer here
Facet for distinct value filtering.
| Name | Type | Description |
|---|---|---|
| value | string | |
| count | number |
Facet for value range filtering.
| Name | Type | Description |
|---|---|---|
| min | string | |
| max | string |
There are many parameters that our API support and we will be showing you a few examples of how to use them in this section.
You can find all of the supported advance search parameters for ProductSearch API here.
To retrieve metadata of your image results, provide the list of metadata keys for the metadata value to be returned in the attrs_to_get property:
visearch.productSearchByImage({
im_url: 'your-image-url',
attrs_to_get: ['price', 'brand', 'im-url'], // list of fields to be returned
}, (res) => {
// TODO handle response
}, (err) => {
// TODO handle error
});Note that only the indexed attributes can be retrieved with this parameter. You may go the the Edit App page in the Discovery Suite console to review which attributes have been included in the app index.
To filter search results based on metadata values, provide a string array of metadata key to filter value in the filters property. Only price, category, brand, original_price support filter parameter.
visearch.productSearchByImage({
im_url: 'your-image-url',
filters: ['brand:my_brand'],
}, (res) => {
// TODO handle response
}, 
