node package manager
Easy sharing. Manage teams and permissions with one click. Create a free org »

visearch-javascript-sdk

visearch-javascript-sdk npm version

Javascript SDK for ViSearch


Table of Contents

  1. Overview
  2. Setup and initialization
  3. Searching Images
  4. Search Results
  5. Advanced Search Parameters
  6. Event tracking
  7. FAQ

1. Overview

ViSearch is an API that provides accurate, reliable and scalable image search. ViSearch API provides endpoints that let developers index their images and perform image searches efficiently. ViSearch API can be easily integrated into your web and mobile applications. More details about ViSearch API can be found in the documentation.

The ViSearch Javascript SDK is an open source software for easy integration of ViSearch Search API with your application server. It provides three search methods based on the ViSearch Search API - pre-indexed search, color search and upload search. For source code and references, visit the github repository.

Our latest stable version: npm version

2. Setup and initialization

Paste the following snippet into the header of your site.

This snippet will load visearch.js onto the page asynchronously, so it won’t affect your page load speed.

Replace "YOUR_APP_KEY" with your ViSearch Client-side App Key. It is recommended to initiate the client when the SDK is loaded into the page.

Your credentials can be found in ViSearch Dashboard

<script type="text/javascript">
!function(e,r,t,a,s){e.__visearch_obj=s;var c=e[s]=e[s]||{};c.q=c.q||[],c.factory=function(e){return function(){var r=Array.prototype.slice.call(arguments);return r.unshift(e),c.q.push(r),c}},c.methods=["idsearch","uploadsearch","colorsearch","set","send"];for(var n=0;n<c.methods.length;n++){var o=c.methods[n];c[o]=c.factory(o)}var i=r.createElement(t);i.type="text/javascript",i.async=!0,i.src=a;var h=r.getElementsByTagName(t)[0];h.parentNode.insertBefore(i,h)}(window,document,"script","//cdn.visenze.com/visearch/dist/js/visearch-1.1.0.min.js","visearch");
visearch.set("app_key", "YOUR_APP_KEY");
</script> 

And it's just as easy with npm:

npm install visearch-javascript-sdk --save
// import module
import visearch from 'visearch-javascript-sdk';
// setup keys
visearch.set("app_key", "YOUR_APP_KEY");
visearch.set("timeout", Timeout_Interval); //default to be 15000
visearch.set("endpoint", "End_Point");

3. Searching Images

Any search api request should follow the pattern below.

visearch.[API_METHOD](parameters, // parameter objects.
  function(res) {
    /**
    this is response handler, will callback this function after receiving the http response.
    please add your code here to process the http response.
    **/
});
  • parameters

Please refer Parameters In ViSearch for the detail of each supported parameters.

  • callback function

A JSON object of the search response will be passed into this callback function. please refer Search Responses for details of the object.

  • error function

This function will be callback if any client exception raised when proceed API calling. an error parameter will be passed in, the structure of this error parameter will be like this:

{
  "message": "Failed to fetch"
}

3.1 Visually Similar Recommendations

Pre-index search is to search similar images based on the your indexed image by its unique identifier (im_name). It should be a valid ID that is used to index your images in the database.

var imageId = "yoox-38377218";
visearch.idsearch({
  im_name: imageId,
  fl: ["im_url"]
}, function(res) {
  // @TODO
  // some response handler
});

3.2 Search by Image

Upload search is used to search similar images by uploading an image or providing an image url.

  • Using an image from a local file path:
  • image parameter must be a html file Object. you can get this object with follow method:
    • Raw Javascript: document.getElementById("fileInputId")
    • JQuery style: $("#fileInputId")[0]

Sample code for upload search with html form:

<form>
  Upload image: <input type="file" id="fileUpload" name="fileInput"><br>
  <input type="submit" value="Submit">
</form>
var inputImageFile = document.getElementById("fileUpload");
visearch.uploadsearch({
  image: inputImageFile, //html file input object
  fl: ["im_url"]
}, function(res) {
  // @TODO
  // some response handler
});
  • Alternatively, you can pass an image url directly to uploadsearch to start the search.
visearch.uploadsearch({
  im_url: "", // image url string
  fl: ["im_url"]
}, function(res) {
  // @TODO
  // some response handler
});

3.2.1 Selection Box

If the object you wish to search for takes up only a small portion of your image, or other irrelevant objects exists in the same image, chances are the search result could become inaccurate. Use the Box parameter to refine the search area of the image to improve accuracy. Noted that the box coordinated needs to be set with respect to the original size of the image passed.

visearch.uploadsearch({
  im_url: "", // image url string
  // input a string array of [x1, y1, x2, y2]
  // where (0,0) is the top-left corner
  // of the image, (x1, y1) is the top-left corner of the box,
  // and (x2, y2) is the bottom-right corner of the box.
  box: [x1, y1, x2, y2],
  fl: ["im_url"]
}, function(res) {
  // @TODO
  // some response handler
});

3.3 Multiple Product Search

Multiple Product Search solution is to search similar images by uploading an image or providing an image url, similar to Search by Image. Multiple Product Search is able to detect all objects in the image and return similar images for each at one time.

  • Using an image from a local file path:
  • image parameter must be a html file Object. you can get this object with follow method:
    • Raw Javascript: document.getElementById("fileInputId")
    • JQuery style: $("#fileInputId")[0]

Sample code for upload search with html form:

<form>
  Upload image: <input type="file" id="fileUpload" name="fileInput"><br>
  <input type="submit" value="Submit">
</form>
var inputImageFile = document.getElementById("fileUpload");
visearch.discoversearch({
  image: inputImageFile, //html file input object
  fl: ["im_url"]
}, function(res) {
  // @TODO
  // some response handler
});
  • Alternatively, you can pass an image url directly to uploadsearch to start the search.
visearch.discoversearch({
  im_url: "", // image url string
  fl: ["im_url"]
}, function(res) {
  // @TODO
  // some response handler
});

3.4 Color Search

Color search is to search images with similar color by providing a color code. The color code should be in Hexadecimal and passed to the colorsearch service.

var colorHexFormat = "fa4d4d";
visearch.colorsearch({
  color: colorHexFormat,
  fl: ["im_url"]
}, function(res) {
  // @TODO
  // some response handler
});

4. Search Results

ViSearch returns a maximum number of 1000 most relevant image search results. You can provide pagination parameters to control the paging of the image search results.

Pagination parameters:

Name Type Description
page Integer Optional parameter to specify the page of results. The first page of result is 1. Defaults to 1.
limit Integer Optional parameter to specify the result per page limit. Defaults to 10.
visearch.uploadsearch({
  im_url: "", // image url string,
  page: 1,
  limit: 25,
  fl: ["im_url"]
}, function(res) {
  // @TODO
  // some response handler
});

5. Advanced Search Parameters

5.1 Retrieving Metadata

To retrieve metadata of your image results, provide the list of metadata keys for the metadata value to be returned in the fl (field list) property:

visearch.uploadsearch({
  im_url: "", // image url string,
  fl: ["price","brand","title","im_url"] //list of field list to be returned
}, function(res) {
  // @TODO
  // some response handler
});

To retrieve all metadata of your image results, specify get_all_fl parameter and set it to True:

visearch.uploadsearch({
  im_url: "", // image url string,
  get_all_fl: true
}, function(res) {
  // @TODO
  // some response handler
});

Only metadata of type string, int, and float can be retrieved from ViSearch. Metadata of type text is not available for retrieval.

5.2 Filtering Results

To filter search results based on metadata values, provide a string array of metadata key to filter value in the fq (filter query) property:

var filterQuery = ['description : bag', 'brand : nike'];
visearch.uploadsearch({
  im_url: "", // image url string,
  fq: filterQuery
}, function(res) {
  // @TODO
  // some response handler
});

Querying syntax for each metadata type is listed in the following table:

Type FQ
string Metadata value must be exactly matched with the query value, e.g. "Vintage Wingtips" would not match "vintage wingtips" or "vintage"
text Metadata value will be indexed using full-text-search engine and supports fuzzy text matching, e.g. "A pair of high quality leather wingtips" would match any word in the phrase
int Metadata value can be either:
  • exactly matched with the query value
  • matched with a ranged query minValue,maxValue, e.g. int value 1, 99, and 199 would match ranged query 0,199 but would not match ranged query 200,300
float Metadata value can be either
  • exactly matched with the query value
  • matched with a ranged query minValue,maxValue, e.g. float value 1.0, 99.99, and 199.99 would match ranged query 0.0,199.99 but would not match ranged query 200.0,300.0

5.3 Result Score

ViSearch image search results are ranked in descending order i.e. from the highest scores to the lowest, ranging from 1.0 to 0.0. By default, the score for each image result is not returned. You can turn on the score property to retrieve the scores for each image result:

visearch.uploadsearch({
  im_url: "", // image url string,
  score: true
}, function(res) {
  // @TODO
  // some response handler
});

If you need to restrict search results from a minimum score to a maximum score, specify the score_min and/or score_max parameters:

Name Type Description
score_min Float Minimum score for the image results. Default is 0.0.
score_max Float Maximum score for the image results. Default is 1.0.
visearch.uploadsearch({
  im_url: "", // image url string,
  score: true,
  min_score: 0.2,
  max_score: 0.5
}, function(res) {
  // @TODO
  // some response handler
});

5.4 Automatic Object Recognition Beta

With Automatic Object Recognition, ViSearch /uploadsearch API is smart to detect the objects present in the query image and suggest the best matched product type to run the search on.

You can turn on the feature in upload search by setting the API parameter "detection=all". We are now able to detect various types of fashion items, including Top, Dress, Bottom, Shoe, Bag, Watch and Indian Ethnic Wear. The list is ever-expanding as we explore this feature for other categories.

Notice: This feature is currently available for fashion application type only. You will need to make sure your app type is configurated as "fashion" on ViSenze dashboard.

visearch.uploadsearch({
  im_url: "", // image url string,
  score: true,
  detection: 'all'
}, function(res) {
  // @TODO
  // some response handler
});

You could also recognize objects from a paticular type on the uploaded query image through configuring the detection parameter to a specific product type as "detection={type}". Our API will run the search within that product type.

Sample request to detect bag in an uploaded image:

visearch.uploadsearch({
  im_url: "", // image url string,
  score: true,
  detection: 'bag'
}, function(res) {
  // @TODO
  // some response handler
});

The detected product types are listed in product_types together with the match score and box area of the detected object. Multiple objects can be detected from the query image and they are ranked from the highest score to lowest. The full list of supported product types by our API will also be returned in product_types_list.

6. Event Tracking

ViSearch Javascript SDK provides methods to understand how your customer interact with the search results.

In addition, to improve subsequent search quality, it is recommended to send user actions when they interact with the results.

6.1 Event handler

User action can be sent through an event handler. Register an event handler to the element in which the user will interact.

visearch.send({
  reqid: "xxxxxx",
  im_name: "xxxxx",
  action: "action type"
});
  • reqid The request id of the search request. This reqid can be obtained from the all search responses.
visearch.idsearch({
  // request parameters
}, function(res) {
  // some response handler
  var reqid=res.reqid
});
  • action The action type of this event. We are currently able to support "click". More actions will be supported in the future.
visearch.send({
  reqid: "xxxxxx",
  im_name: "xxxxx",
  action: "click"
});
  • im_name The im_name of the image which the user has clicked on. im_name is the unique identifier of the indexed image, in this case the searched result.

6.2 Tracking via url

The SDK provides another alternative to event tracking which is via url. Append the following url requests into the links where the user will interact.

?reqid={reqid}&im_name={im_name}

When the link is clicked, the system will detect the user interaction.

<a href="domain/path?reqid={reqid}&im_name={im_name}">text</a>

7 FAQ

  • When performing upload search, you may notice the increased search latency with increased image file size. This is due to the increased time spent in network transferring your images to the ViSearch server, and the increased time for processing larger image files in ViSearch.