NAV Navbar
Logo
curl Java Python PHP JavaScript iOS Android

Search API

API OVERVIEW

Introduction

Our ViSenze Search (ViSearch) API provides accurate, reliable and scalable image search. ViSearch API provides endpoints that let developers index their images and perform image searches efficiently. We provide powerful SDKs in various languages, so that our API can be easily integrated into your web and mobile applications.

SDK Setup

// Current stable version: 1.8.6
// Minimum JDK version: 1.6

// Maven projects: include the dependency in `pom.xml`:
<dependency>
 <groupId>com.visenze</groupId>
 <artifactId>visearch-java-sdk</artifactId>
 <version>1.8.6</version>
</dependency>


// Gradle projects: include this line in your `build.gradle` dependencies block:
compile 'com.visenze:visearch-java-sdk:1.8.6'


// SBT projects: add the following line to `build.sbt`:
libraryDependencies += "com.visenze" % "visearch-java-sdk" % "1.8.6"

* Current stable version: 1.0.1
* Minimum requirement: php5 and php5-curl

You can get the source code of the SDK and demos from the Github repo. Download the <a>ViSearch SDK</a>and place the ViSearch to your project directory.

Include ViSearch API into your project.

//To Include ViSearch API
require_once 'pathTo/ViSearch/viSearch.php';
# Current stable version: 0.4.5
# Supported on Python 2.6+ and 3.3+
$ pip install visearch
// You can use NPM to install
npm install visearch-javascript-sdk --save

// OR,
// Paste the following snippet into the header of your site.
// This snippet will load visearch.js onto the page asynchronously,
// so it will not affect your page load speed.

<script type="text/javascript">
    !function(e,r,t,s,a){e.__visearch_obj=a;var c=e[a]=e[a]||{};c.q=c.q||[],c.factory=function(r){return function(){var e=Array.prototype.slice.call(arguments);return e.unshift(r),c.q.push(e),c}},c.methods=["idsearch","uploadsearch","colorsearch","set","send","search","recommendation","out_of_stock","similarproducts","discoversearch"];for(var o=0;o<c.methods.length;o++){var n=c.methods[o];c[n]=c.factory(n)}var i=r.createElement(t);i.type="text/javascript",i.async=!0,i.src="//cdn.visenze.com/visearch/dist/js/visearch-1.5.2.min.js";var h=r.getElementsByTagName(t)[0];h.parentNode.insertBefore(i,h)}(window,document,"script",0,"visearch");
    visearch.set("app_key", "YOUR_APP_KEY");
</script>
// First you need to install the Cocoapods Ruby gem:
[sudo] gem install cocoapods
pod setup

// Then go to your project directory to create an empty Podfile:
cd /path/to/Demo
pod init

// Edit the Podfile as follow:

source 'https://github.com/CocoaPods/Specs.git'
platform :ios, '7.0'
...
pod 'ViSearch', '~>1.4.1'
...

// Install the ViSearch SDK:
pod install
// Current stable version: 1.2.2
// Minimum Android SDK Version: API 9, Android 2.3

// To integrate ViSearch SDK with your own application, you can start with including
// the dependency in your project using gradle:
compile 'com.visenze:visearch-android:1.2.2'

// In the build.gradle file under your app module, add the packaging options to
// ensure a successful compilation:

android {
    ...

    packagingOptions {
        exclude 'META-INF/NOTICE'
        exclude 'META-INF/LICENSE'
    }
    ...
}

You can easily setup our SDK with your preferred language and get started with integrations. You can find the source code our SDKs on the following github repos:

Authentication

$ curl https://visearch.visenze.com/search?im_name=example-0 \
      -X GET \
      -u access_key:secret_key

# for China, please use
$ curl https://visearch.visenze.com.cn/search?im_name=example-0 \
      -X GET \
      -u access_key:secret_key
ViSearch client = new ViSearch("YOUR_ACCESS_KEY", "YOUR_SECRET_KEY");

// for China, please use
ViSearch client = new ViSearch("https://visearch.visenze.com.cn" ,"YOUR_ACCESS_KEY", "YOUR_SECRET_KEY");
from visearch import client

api = client.ViSearchAPI('YOUR_ACCESS_KEY', 'YOUR_SECRET_KEY')

# for China, please use
api = client.ViSearchAPI(access_key, secret_key, host="https://visearch.visenze.com.cn")
$service = new ViSearch($access_key,$secret_key);

<script type="text/javascript">
    ...
    visearch.set("app_key", "YOUR_APP_KEY");
</script>

// for China, please use
<script type="text/javascript">
    ...
    visearch.set("app_key", "YOUR_APP_KEY");
    visearch.set("endpoint", "https://visearch.visenze.com.cn");
</script>
#import <ViSearch/VisearchAPI.h>
...
// using default ViSearch client. The client, by default,
// connects to Visenze's server

// 1. new way of init ViSearch client with only app key
static NSString * const appKey = @"your_app_key";


[ViSearchAPI setupAppKey:appKey];
ViSearchClient *client = [ViSearch defaultClient];


// 2. OR old way of init ViSearch client with access and secret key
static NSString * const accessKey = @"your_access_key";
static NSString * const privateKey = @"your_secret_key";

[ViSearchAPI setupAccessKey:accessKey andSecretKey:secretKey];
ViSearchClient *client = [ViSearch defaultClient];
client.isAppKeyEnabled = NO;
...


// OR using customized client, which connects to your own server
static NSString * const privateKey = @"your_url";
ViSearchClient *client = [[ViSearchClient alloc] initWithBaseUrl:url
  appKey:appKey];
...

public class MainActivity extends FragmentActivity {
  @Override
    protected void onCreate(Bundle savedInstanceState) {
      super.onCreate(savedInstanceState);

      ViSearch viSearch = new ViSearch
                  .Builder("YOUR_APP_KEY")
                  .build(this);
      viSearch.setListener(this);

      ...
    }
    ...
 }

// for China, please use
ViSearch viSearch = new ViSearch
                .Builder(APP_KEY)
                .setApiEndPoint("https://visearch.visenze.com.cn")
                .build(context);

Once an application is created in ViSearch Dashboard system, a unique pair of access key and secret key will be assigned to this application. The key pair will be used to authenticate each API call.

We provide HTTP Basic Auth to authenticate the call to the ViSearch API. The access key and secret key are encoded into base64 string and append to the request header, which is easy to use but only suitable for API calls from the backend system.

HTTP Basic Auth

This authentication method is the standard HTTP Basic Auth. Use your access key as the basic auth username, and secret key as the basic auth password.

Error Codes

General error messages:

Message
Invalid access key or secret key.
Unauthorized.
Exceeds image collection size limit.
System busy, please try again later.
A system error is reported and we are fixing it right now.

Data API Errors

Code Message
101 Transaction not found with trans_id.
102 Image not found with im_name.
103 Exceeded maximum insert batch size of 100.
104 No image inserted.
105 Number of parameters for image exceeds maximum limit of 32.
106 {parameter} exceeds length limit.
107 Invalid im_name.
108 Missing im_url.
109 {field} should be of data type {type}.
201 Could not download the image from im_url.
202 Unsupported image format.

Search API Errors

Message Remarks
The query image is still being processed, please try again later. Depending on the number of images in your catalog, this process can take several minutes.
Image not found with im_name. Please check to ensure im_name is keyed in correctly; otherwise the image you are looking for has not been uploaded.
Invalid image file format. The supported image formats include: ..jpg, .jpeg, .jpe, .png, .gif, .bmp, .dib, .webp, .pbm, .pgm, .ppm, .sr, .ras, .tiff, .tif
The image format or dimension is invalid. Please have images with at least 100 pixels in any one direction and no larger than 40MP in size.
Invalid image or im_url. The file or url you have supplied may not be an image.
Could not download the image, please try again later. Please check your image url and see if it’s accessible to the public.
Timeout while downloading image, please try again later. Your image size may have been too large; we recommend images around 1024x1024 pixels.
App doesn’t have any images. You can upload images via the dashboard or API.

DATA INDEXING APIs

ViSearch Data APIs provide interfaces to manage your image collections. To add or update images, you call the Insert API with a list of images and their metadata. You can retrieve the image processing progress and errors occurred during the process by calling the Insert Status API. If you need to remove images, you can call the Remove API.

Insert Image

POST /insert

$ curl https://visearch.visenze.com/insert \
-d im_name[0]=example-0 \
-d im_url[0]=http://example.com/example-0.jpg \
-d brand[0]=my_brand \
-d price[0]=199 \
-d im_name[1]=example-1 \
-d im_url[1]=http://example.com/example-1.jpg \
-u access_key:secret_key

# for China, please use
$ curl https://visearch.visenze.com.cn/insert \
-d im_name[0]=example-0 \
-d im_url[0]=http://example.com/example-0.jpg \
-d brand[0]=my_brand \
-d price[0]=199 \
-d im_name[1]=example-1 \
-d im_url[1]=http://example.com/example-1.jpg \
-u access_key:secret_key


# example response JSON
{
    "status": "OK",
    "method": "insert",
    "trans_id": 246806789063168000,
    "total": 2,
    "result": [],
    "error": []
}

List<Image> images = new ArrayList<Image>();
String imName = "vintage_wingtips";
String imUrl = "http://mydomain.com/images/vintage_wingtips.jpg";

// add metadata to your image
Map<String, String> metadata = new HashMap<String, String>();
metadata.put("title", "Vintage Wingtips");
metadata.put("description", "A pair of high quality leather wingtips");
metadata.put("price", "100.0");
images.add(new Image(imName, imUrl, metadata));
client.insert(images);
images = [{
           'im_name': 'blue_dress',
           'im_url': 'http://mydomain.com/images/blue_dress.jpg',
           'title': 'Blue Dress',
           'description': 'A blue dress',
           'price': 100.0
          },
          ...
         ]
# calls the /insert endpoint to index the image
response = api.insert(images)
$images[] = array('im_name'=>'blue_dress',
                  'im_url'=>'http://mydomain.com/images/blue_dress.jpg',
                  'title'=>'Blue Dress',
                  'description'=>'A blue dress',
                  'price'=> 100.0f);
// calls the /insert endpoint to index the image
$response = $service->insert($images);

This API is for adding or updating images to your image collections.

request parameters

The request parameters for the images must be in the following format:

{key}[index]=value

where key is the im_name, im_url, or metadata field name, and index is the 0 based integer index of the images.

There are several limits on the parameters and images:

name example description
im_name required im_name[0]=example-0 im_name[1]=example-1 A unique image name used as an identifier in the App image collection. Valid characters are [a-z], [A-Z], [0-9], [-], [_], [.], and [:]. If an image with the same name exists in the image collection, the image will be updated.
im_url required im_url[0]=http://example.com/example-0.jpg im_url[1]=http://example.com/example-1.jpg The image url that correspond to the image name. The image will be downloaded to our server to process.
[metadata fields] brand[0]=my_brand price[0]=199 Metadata fields for the image.

Check Insert Status

GET /insert/status/{trans_id}

$ curl https://visearch.visenze.com/insert/status/29031939452 \
    -u access_key:secret_key \

# for China, please use
$ curl https://visearch.visenze.com.cn/insert/status/29031939452 \
    -u access_key:secret_key \


# example response json:
{
    "status": "OK",
    "method": "insert/status",
    "result": [
        {
            "trans_id": 29031939452,
            "processed_percent": 100,
            "success_count": 1,
            "fail_count": 3,
            "total": 4,
            "error_list": [
                {
                    "im_name": "image_1",
                    "error_code": 201,
                    "error_message": "Could not download the image from im_url."
                },
                {
                    "im_name": "image_2",
                    "error_code": 202,
                    "error_message": "Unsupported image format."
                },
                {
                    "im_name": "image_3",
                    "error_code": 203,
                    "error_message": "Unsupported image dimension."
                }
            ],
            "error_page": 1,
            "error_limit": 10
        }
    ],
    "error": []
}
List<Image> images = new ArrayList<Image>();
String imName = "vintage_wingtips";
String imUrl = "http://mydomain.com/images/vintage_wingtips.jpg";
images.add(new Image(imName, imUrl));

// index the image and get the InsertTrans
InsertTrans trans = client.insert(images);

InsertStatus status;
// check the status of indexing process while it is not complete
int percent = 0;
while (percent < 100) {
    try {
        Thread.sleep(1000);
    } catch (InterruptedException e) {
        e.printStackTrace();
    }
    status = client.insertStatus(trans.getTransId());
    percent = status.getProcessedPercent();
    System.out.println(percent + "% complete");
}

int pageIndex = 1; // error page index always starts with 1
int errorPerPage = 10;  // set error page limit
status = client.insertStatus(trans.getTransId(), pageIndex, errorPerPage);
System.out.println("Start time:" + status.getStartTime());
System.out.println("Update time:" + status.getUpdateTime());
System.out.println(status.getTotal() + " insertions with "
        + status.getSuccessCount() + " succeed and "
        + status.getFailCount() + " fail");

// print all the error messages if there are any
if (status.getFailCount() > 0) {
    int totPageNumber = (int) Math.ceil(1.0 * status.getFailCount() / status.getErrorLimit());
    for (pageIndex = 1; pageIndex <= totPageNumber; pageIndex++) {
        status = client.insertStatus(trans.getTransId(), pageIndex, errorPerPage);
        List<InsertError> errorList = status.getErrorList();
        for (int errorIndex = 0; errorIndex < errorList.size(); errorIndex++) {
            System.out.println("failure at page " + pageIndex
                    + " with error message: " + errorList.get(errorIndex));
        }
    }
}
import time
import math

# the list of images to be indexed
# the unique identifier of the image 'im_name', the publicly downloadable url of the image 'im_url'
images = [
    {'im_name': 'pic5', 'im_url': 'http://mydomain.com/images/vintage_wingtips.jpg'},
]

response = api.insert(images)

trans_id = response['trans_id']

percent = 0
while (percent < 100):
    time.sleep(1)

    status_response = api.insert_status(trans_id)
    if 'result' in status_response and len(status_response['result']) > 0:
        percent = status_response['result'][0]['processed_percent']
        print '{}% complete'.format(percent)

page_index = 1
error_per_page = 10
fail_count = None
status_response = api.insert_status(trans_id, page_index, error_per_page)
if 'result' in status_response and len(status_response['result']) > 0:
    result_data = status_response['result'][0]
    print result_data
    fail_count = result_data['fail_count']
    print 'Start time: {}'.format(result_data['start_time'])
    print 'Update time: {}'.format(result_data['update_time'])
    print "{} insertions with {} succeed and {} fail".format(
        result_data['total'],
        result_data['success_count'],
        result_data['fail_count']
        )

if fail_count > 0:
    result_data = status_response['result'][0]
    error_limit = result_data['error_limit']
    total_page_number = int(math.ceil(float(fail_count) / error_limit))
    for i in range(total_page_number):
        page_index = i + 1
        status_response = api.insert_status(trans_id, page_index, error_per_page)
        error_list = status_response['result'][0]['error_list']
        for error in error_list:
            print "failure at page {} with error message {}".format(
                page_index,
                error)

Retrieve image processing status for an insert transaction. You can find the trans_id for an insert transaction in the response of the insert call.

request parameters

If there are failed images in the insert transaction, you can paginate the errors by providing the following parameters:

name type description
error_page integer Specifies the page of error info to be returned.
error_limit integer Specifies the number of error info per page to be returned.

response properties

name description
trans_id The transaction id.
processed_percent Rounded percentage value of the amount of processed images over the total number of images.
success_count Number of image inserted successfully.
fail_count Number of image failed to insert.
total Total number of images in the transaction.
error_list The list of error encountered when processing the images in the transaction.
error_page The page of error info.
error_limit The number of error info per page.

Remove Image

POST /remove

$ curl https://visearch.visenze.com/remove \
    -d im_name[0]=example-0 \
    -d im_name[1]=example-1 \
    -u access_key:secret_key

# for China, please use
$ curl https://visearch.visenze.com.cn/remove \
    -d im_name[0]=example-0 \
    -d im_name[1]=example-1 \
    -u access_key:secret_key


# example response JSON
{
    "status": "OK",
    "method": "remove",
    "total": 2,
    "result": [
    ],
    "error": []
}
// the list of unique identifiers 'im_name' of the images to be removed
List<String> removeList = new ArrayList<String>();
// removing previously indexed image "red_dress"
removeList.add("red_dress");
client.remove(removeList);
image_names = ["red_dress", "blue_dress"]
response = api.remove(image_names)
$response = $service->remove(array("red_dress","blue_dress"));

This API is for removing images from the image collection. Please allow 5 mins for the process that removes images from the indexed database.

request parameters

name example description
im_name required im_name[0]=example-0 im_name[1]=example-1 The image names for the images to be removed.

SOLUTION APIs

ViSenze provides APIs for four types of solutions:

  1. Visually Similar Recommendations
    Visually Similar Recommendations solution is to search against your image collection using an existing image in the collection.

  2. Search by Image
    Search by image solution is to search for similar images in the image database by uploading an image or providing an image url. The solution can detect the primary object in the uploaded image and search it against image database. Alternatively, the user can specify a bounding box as an API request parameter to search for the bounded object.

  3. Multiple Product Search
    Multiple Product Search solution is to detect multiple objects in the uploaded image, and search for their respective similar images in the image database. The API response will return the search results for each detected object.

  4. Search by Color
    Search by color solution is to search for images with similar color by providing color codes. The color code should be in Hexadecimal and passed to the color search service.

Visually Similar Recommendations

$ curl https://visearch.visenze.com/search?im_name=example-0 \
    -u access_key:secret_key

# for China, please use
$ curl https://visearch.visenze.com.cn/search?im_name=example-0 \
  -u access_key:secret_key
SearchParams params = new SearchParams("vintage_wingtips");
PagedSearchResult searchResult = client.search(params);
response = api.search("blue_dress")
$service = new ViSearch($access_key,$secret_key);
$service->search("blue_dress");
#import <ViSearch/VisearchAPI.h>
...
SearchParams *searchParams = [[SearchParams alloc] init];
searchParams.imName = @"imName-example";

[[ViSearchAPI defaultClient]
    searchWithImageId:searchParams
    success:^(NSInteger statusCode, ViSearchResult *data, NSError *error) {
    // Do something when request succeeds
    } failure:^(NSInteger statusCode, ViSearchResult *data, NSError *error) {
    // Do something when request fails
    }];
...

IdSearchParams idSearchParams = new IdSearchParams("dress_1");
viSearch.idSearch(idSearchParams);
visearch.search({
  im_name: 'your-image-name',
}, (res) => {
  // TODO handle response
}, (err) => {
  // TODO handle error
});

This API is for searching against your image collection using an existing image in the collection.

request parameters

name example description
im_name required im_name=example_name The image name of the image to search against the image collection.
page page=1 The result page number. Default value is 1.
limit limit=10 The number of results per page. Default value is 10. The maximum number of results returned from the API is 1000.
[advanced parameters] Check out even more powerful advanced parameters.
# example response JSON
{
    "status": "OK",
    "method": "search",
    "error": [],
    "page": 1,
    "limit": 10,
    "total": 1000,
    "result": [
        {
          "im_name": example_image_name,
        }, ...
    ],
    "reqid": example_reqid
}

Search by Image

POST /uploadsearch

Searching an uploaded image file

$ curl https://visearch.visenze.com/uploadsearch \
       -F image=@example-0.jpg \
       -F box=0,0,20,20 \
       -u access_key:secret_key

# for China, please use
$ curl https://visearch.visenze.com.cn/uploadsearch \
       -F image=@example-0.jpg \
       -F box=0,0,20,20 \
       -u access_key:secret_key
File imageFile = new File("/path/to/your/image");
UploadSearchParams params = new UploadSearchParams(imageFile);
PagedSearchResult searchResult = client.uploadSearch(params);
$image = new Image(imagePath);
$response = $service->uploadsearch($image);
image_path = 'blue_dress.jpg'
response = api.uploadsearch(image_path=image_path)
visearch.uploadsearch({
  image: inputImageFile,
}, (res) => {
  // TODO handle response
}, (err) => {
  // TODO handle error
});
#import <ViSearch/VisearchAPI.h>
...
UIImage *image = [UIImage imageNamed:@"example.jpg"];

UploadSearchParams *uploadSearchParams = [[UploadSearchParams alloc] init];
uploadSearchParams.imageFile = image

[[ViSearchAPI defaultClient]
    searchWithImageData:uploadSearchParams
    success:^(NSInteger statusCode, ViSearchResult *data, NSError *error) {
    // Do something when request succeeds
    } failure:^(NSInteger statusCode, ViSearchResult *data, NSError *error) {
    // Do something when request fails
    }];
// Using an image from a local file path:
Image image = new Image("/local/path/to/image.jpg");
UploadSearchParams uploadSearchParams.setImage(image);
viSearch.uploadSearch(uploadSearchParams);

// Using an image by providing the Uri of the image in photo gallery:
Image image = new Image(context, uri);
UploadSearchParams uploadSearchParams = new UploadSearchParams(image);
viSearcher.uploadSearch(uploadSearchParams);

// Construct the `image` from the byte array returned
// by the camera preview callback:
@Override
public void onPictureTaken(byte[] bytes, Camera camera) {
    Image image = new Image(bytes);
    UploadSearchParams uploadSearchParams = new UploadSearchParams(image);

    viSearcher.uploadSearch(uploadSearchParams);
}

Searching a publicly accessible image URL

$ curl https://visearch.visenze.com/uploadsearch \
       -d im_url=http://example.com/example-0.jpg \
       -d box=0,0,20,20 \
       -u access_key:secret_key

# for China, please use
$ curl https://visearch.visenze.com.cn/uploadsearch \
       -d im_url=http://example.com/example-0.jpg \
       -d box=0,0,20,20 \
       -u access_key:secret_key
String url = "http://mydomain.com/sample_image.jpg";
UploadSearchParams params = new UploadSearchParams(url);
PagedSearchResult searchResult = client.uploadSearch(params);
image_url = 'http://mydomain.com/images/red_dress.jpg'
response = api.uploadsearch(image_url=image_url)
$image = new Image('http://mydomain.com/images/red_dress.jpg');
$response = $service->uploadsearch($image);
visearch.uploadsearch({
  im_url: 'your-image-url',
}, (res) => {
  // TODO handle response
}, (err) => {
  // TODO handle error
});
#import <ViSearch/VisearchAPI.h>
...
UploadSearchParams *uploadSearchParams = [[UploadSearchParams alloc] init];
uploadSearchParams.imageUrl = @"http://example.com/example.jpg";

[[ViSearchAPI defaultClient]
    searchWithImageUrl:uploadSearchParams
    success:^(NSInteger statusCode, ViSearchResult *data, NSError *error) {
    // Do something when request succeeds
    } failure:^(NSInteger statusCode, ViSearchResult *data, NSError *error) {
    // Do something when request fails
    }];
...
String url = "http://mydomain.com/sample_image.jpg";
UploadSearchParams uploadSearchParams = new UploadSearchParams(url);
viSearcher.uploadSearch(uploadSearchParams);

Searching with im_id that can be retrieved from the previous uploadsearch response.

$ curl https://visearch.visenze.com/uploadsearch \
       -d im_id=example_image_id \
       -d box=0,0,20,20 \
       -u access_key:secret_key

# for China, please use
$ curl https://visearch.visenze.com.cn/uploadsearch \
       -d im_id=example_image_id \
       -d box=0,0,20,20 \
       -u access_key:secret_key
//get imid from previous request
String imId = prevSearchResult.getImId();

UploadSearchParams params = new UploadSearchParams(imId);
PagedSearchResult searchResult = client.uploadSearch(params);

// Get imid from previous request
$imid = $response->im_id;

// Searching using im_id
$newimage->setfilepath(imagepath);
$newimage = new Image();
$newimage->setimid($imid);
$response = $service->uploadsearch($new_image);
// Searching using im_id

#import <ViSearch/VisearchAPI.h>
...
UploadSearchParams *uploadSearchParams = [[UploadSearchParams alloc] init];
uploadSearchParams.imId = visearchResult.imId;

[[ViSearchAPI defaultClient]
  searchWithImage:uploadSearchParams
  success:^(NSInteger statusCode, ViSearchResult *data, NSError *error) {
      // Do something when request succeeds
    } failure:^(NSInteger statusCode, ViSearchResult *data, NSError *error) {
      // Do something when request fails
    }];
...

// Searching using im_id
String imId;

@Override
public void onSearchResult(ResultList resultList) {
    imId = resultList.getImId();
    for (ImageResult imageResult : resultList.getImageList()) {
        //Do something with the result
        ...
    }
}

UploadSearchParams uploadSearchParams = new UploadSearchParams();
uploadSearchParams.setImId(imId);
viSearcher.uploadSearch(uploadSearchParams);

This API is for searching for similar images in the image database by uploading an image or providing an image url. The solution can detect the primary object in the uploaded image and search it against image database. Alternatively, the user can specify a bounding box as an API request parameter to search for the bounded object.

There are some limitations on the request and the image:

request parameters

name example description
im_url im_url=http://example.com/example.jpg The url for the image to be downloaded and searched against the image collection. Image file or im_url or im_id must be provided.
im_id im_id=example_image_id For each uploaded image ViSearch service will return an unique im_id which can be used to do further search without downloading the image again. Image file or im_url or im_id must be provided.
image (image file object) The image file object that will be searched against the image collection. Image file or im_url or im_id must be provided.
box box=0,0,20,20 Optional parameter for restricting the image area x1,y1,x2,y2. The upper-left corner of an image is (0,0).
page page=1 The result page number. Default value is 1.
limit limit=10 The number of results per page. Default value is 10. The maximum number of results returned from the API is 1000.
[advanced parameters] Check out even more powerful advanced parameters.

For each uploaded image ViSearch service will return an unique im_id which can be used to do further uploadsearch without downloading the image again. If you need to do several upload searches using one same image, this is recommended to save the bandwidth and improve the overall speed.

response properties


# example response JSON
{
    "status":"OK",
    "method":"uploadsearch",
    "error":[],
    "page":1,
    "limit":10,
    "total":1000,
    "product_types":[
        {
            "type": "top",
            "attributes": {},
            "score": 0.9955333471298218,
            "box": [
                75,
                133,
                303,
                388
            ]
        }, ...
        ],
    "product_types_list": [
        ...
        ],
    "result": [
            {
                "im_name": example_image_name,
            }, ...
        ],
    "im_id": example_image_id,
    "reqid": example_reqid
}
name description
status The request status, either “OK”, “warning”, or “fail”.
method the request method.
error The list of error if the request was not successful i.e. when status is “warning” or “fail”.
page The result page number.
limit The number of results per page.
total The total number of result.
product_types The list of objects detected.
product_types_list The product_types_list contains the complete list of object types supported for detection for this app.
result The list of result objects if the request was successful, i.e. when status is “OK”.
im_id The unique ID for uploaded image.
reqid The unique request id of the api call.

POST /discoversearch

$ curl https://visearch.visenze.com/discoversearch \
       -d im_url=http://example.com/example-0.jpg \
       -d detection=all \
       -d detection_limit=5 \
       -d result_limit=10 \
       -d score=true \
       -d “fl=im_url” \
       -u access_key:secret_key

# for China, please use
$ curl https://visearch.visenze.com.cn/discoversearch \
       -d im_url=http://example.com/example-0.jpg \
       -d detection=all \
       -d detection_limit=5 \
       -d result_limit=10 \
       -d score=true \
       -d “fl=im_url” \
       -u access_key:secret_key
// Using an image from a local file path
File imageFile = new File("/path/to/your/image");
UploadSearchParams params = new UploadSearchParams(imageFile);
PagedSearchResult searchResult = client.discoverSearch(params);

// Using image url
String url = "http://mydomain.com/sample_image.jpg";
UploadSearchParams params = new UploadSearchParams(url);
PagedSearchResult searchResult = client.discoverSearch(params);
response = api.discoversearch(im_url='http://www.test.com/test.jpg', detection='all', detection_limit=3, result_limit=10, detection_sensitivity='high', box=(0, 0, 10, 10))
// Searching an uploaded image file
visearch.discoversearch({
  image: inputImageFile,
}, (res) => {
  // TODO handle response
}, (err) => {
  // TODO handle error
});

// Searching a publicly accessible image URL
visearch.discoversearch({
  im_url: 'your-image-url',
}, (res) => {
  // TODO handle response
}, (err) => {
  // TODO handle error
});
#import <ViSearch/VisearchAPI.h>
...
UIImage *image = [UIImage imageNamed:@"example.jpg"];

UploadSearchParams *uploadSearchParams = [[UploadSearchParams alloc] init];
uploadSearchParams.imageFile = image

[[ViSearchAPI defaultClient]
  discoverSearchWithImageData:uploadSearchParams
  success:^(NSInteger statusCode, ViSearchResult *data, NSError *error) {
  // Do something when request succeeds
    } failure:^(NSInteger statusCode, ViSearchResult *data, NSError *error) {
  // Do something when request fails
    }];
...


#import <ViSearch/VisearchAPI.h>
...
UploadSearchParams *uploadSearchParams = [[UploadSearchParams alloc] init];
uploadSearchParams.imageUrl = @"http://example.com/example.jpg";

[[ViSearchAPI defaultClient]
  discoverSearchWithImageUrl:uploadSearchParams
  success:^(NSInteger statusCode, ViSearchResult *data, NSError *error) {
  // Do something when request succeeds
    } failure:^(NSInteger statusCode, ViSearchResult *data, NSError *error) {
  // Do something when request fails
    }];
...

This API is for detecting multiple objects in the uploaded image, and search for their respective similar images in the image database. The API response will return the search results for each detected object.

There are some limitations on the request and the image:

request parameters

name example description
im_url im_url=http://example.com/example.jpg The url for the image to be downloaded and searched against the image database. User must input one of the following: image file, im_url or im_id.
im_id im_id=example_image_id For each uploaded image ViSearch service will return an unique im_id which can be used to do further search without downloading the image again. User must input one of the following: image file, im_url or im_id.
image (image file object) The image file object that will be searched against the image database. User must input one of the following: image file, im_url or im_id.
detection detection = eyewear Selects the type of objects to be recognized in the query image, can be used in following ways:
  • detection = all (default), recognize all the possible types of objects.
  • detection = {type}, recognize objects of the specified type.
  • detection = null, recognize all the possible types of objects.
  • detection = “ “, turn off detection, use the whole image to search.
  • detection = anything other than the supported product type, turn off detection, use the whole image to search.
detection_limit detection_limit = 3 Maximum number of products could be detected for a given image; default value is 5. Values must range between 1-30.
Returns the objects with higher confidence score first.
detection_sensitivity detection_sensitivity = low /
detection_sensitivity = high
Parameter to set the detection to more or less sensitive. Default is low.
  • detection_sensitivity = low: less sensitive detection, will only return objects that are very confident.
  • detection_sensitivity = high: more sensitive detection, will potentially detect more objects in the image.
box box=0,0,20,20 Optional parameter for restricting the image area x1,y1,x2,y2. Once this is passed in the parameter, only the area within bounding box will be analyzed.
point point=15,40 Pixel coordinates to indicate the position of the target object [x,y]. The upper-left corner of an image is [0,0]. Stack inputs for multiple points up to 5 values as default. box and point parameters are not allowed to appear in the same request. detection_limit is ignored when point exists.
page page=1 The result page number. Default value is 1.
result_limit result_limit = 10 The number of results returned per page for each product; default value is 10. Values must range between 1-1000.
[advanced parameters] Check out even more powerful advanced parameters.

response properties

# example response JSON
{
    "status": "OK",
    "method": "discoversearch",
    "error": [],
    "result_limit": 10,
    "detection_limit": 5,
    "page": 1,
    "objects": [
        {
            "type": "top",
            "attributes": {},
            "score": 0.9919997453689575,
            "box": [
                234,
                263,
                634,
                706
            ],
            "total": 100,
            "result": [
                {
                    "im_name": example_image_name-0,
                }, ...
            ]
        },
        {
            "type": "bottom",
            "attributes": {},
            "score": 0.7576414883136749,
            "box": [
                252,
                657,
                689,
                1099
            ],
            "total": 100,
            "result": [
                {
                    "im_name": example_image_name-1,
                }, ...
            ]
        }
    ],
    "object_types_list": [
        {
            "type": "top",
            "attributes_list": {
                "gender": [
                    "men",
                    "women"
                ]
            }
        },
        {
            "type": "bottom",
            "attributes_list": {
                "gender": [
                    "men",
                    "women"
                ]
            }
        }
    ],
    "im_id": example_image_id,
    "reqid": example_reqid
}

name description
status The request status, either “OK”, “warning”, or “fail”.
method The request method.
error The list of error if the request was not successful i.e. when status is “warning” or “fail”.
result_limit The number of results returned per page for each product. Default value is 10.
detection_limit Maximum number of products could be detected for a given image. Default value is 5.
page The result page number.
objects The objects is structured in the way that it contains all objects detected in the given image, including the object type, the confidence score, as well as the box coordinates of the objects.
Under each object, the total number of search results will be returned, and the im_name and score of the search results will be returned.
object_type_list The object_type_list contains the complete list of object types supported for detection for this app.

Search by Color

GET /colorsearch

$ curl https://visearch.visenze.com/colorsearch?color=012ACF:40&color=19668f:60 \
    -u access_key:secret_key

# for China, please use
$ curl https://visearch.visenze.com.cn/colorsearch?color=012ACF:40&color=19668f:60 \
    -u access_key:secret_key

ColorSearchParams.ColorAndWeight colorAndWeight1 = new ColorSearchParams.ColorAndWeight("000000", 50);
ColorSearchParams.ColorAndWeight colorAndWeight2 = new ColorSearchParams.ColorAndWeight("ffffff", 50);
ColorSearchParams params = new ColorSearchParams(Lists.newArrayList(colorAndWeight1, colorAndWeight2));
PagedSearchResult searchResult = client.colorSearch(params);
visearch.colorsearch({
 color: ['fa4d4d:30','3f48cc:70'],
}, (res) => {
 // TODO handle response
}, (err) => {
 // TODO handle error
});
response = api.colorsearch("fa4d4d")
$service->colorsearch("fa4d4d");
ColorSearchParams colorSearchParams = new ColorSearchParams("9b351b");
viSearch.colorSearch(colorSearchParams);
#import <ViSearch/VisearchAPI.h>
...
ColorSearchParams *colorSearchParams = [[ColorSearchParams alloc] init];
colorSearchParams.color = @"012ACF";
[[ViSearchAPI defaultClient]
    searchWithColor:colorSearchParams
    success:^(NSInteger statusCode, ViSearchResult *data, NSError *error) {
    // Do something when request succeeds   
    } failure:^(NSInteger statusCode, ViSearchResult *data, NSError *error) {
    // Do something when request fails
    }];
...

This API is for searching for images matching to the colors in your image collection. The API accepts multiple colors inputs and relative ratios.

The API supports up to 5 colors inputs by default. This number of colors input limit is customisable by ViSenze.

request parameters

name example description
color required color=012ACF:33
color=012ACF
6 digit color hex codes with relative ratios. Ratios must be integers ranging from 1 to 100. If no ratio input for all the color hex, treat as equal ratios.
page page=1 The result page number. Default value is 1.
limit limit=10 The number of results per page. Default value is 10. The maximum number of results returned from the API is 1000.
[advanced parameters] Check out even more powerful advanced parameters.
# example response JSON
{
    "status": "OK",
    "method": "colorsearch",
    "error": [],
    "page": 1,
    "limit": 10,
    "total": 1000,
    "result": [
      {
        "Im_name":"image-name-1",
      },
      {
          "Im_name":"image-name-2",
      }, ...
    ],
    "reqid": example_reqid
}

ADVANCED PARAMETERS

ViSearch API is even more powerful with advanced parameter configuration. The table summarizes the optional parameters that are common for all the search APIs. The usages of the parameters are explained in detail in the following sections.

name example description
detection detection=all Turn on automatic object detection so the algorithm will try to detect the object in the image and search. detection is not supported for /search or /colorsearch
fq fq=brand:my_brand&fq=price:0,199 The metadata fields to filter the results. Only fields marked with ‘searchable’ in ViSearch Dashboard can be used as filters. If the filter field is not in data schema, it will be ignored. Text fields can only be ‘searchable’.
fl fl=brand&fl=price The metadata fields to be returned. If the query value is not in data schema, it will be ignored. Text fields are not applicable for fl fetch.
get_all_fl get_all_fl=true If set true, return metadata for all the fields applicable for fl fetch. Default value is false.
score score=true If the value is true, the score for each image result will be included in the response.
score_min score_min=0.5 Sets the minimum score threshold for the search. The value must be between 0.0 to 1.0 inclusively, or an error will be returned. Default value is 0.0.
score_max score_max=0.8 Sets the maximum score threshold for the search. The value must be between 0.0 to 1.0 inclusively, or an error will be returned. Default value is 1.0.
dedup dedup=false Parameter to turn on remove similar image results function. Default is false.
dedup_score_threshold dedup_score_threshold=0.5 Sets the minimum gap between adjacent results. Only works when dedup=true. Default is 0.0.
facets facets = color,brand,price List of fields to enable faceting.
facets_limit facet_limit = 10 Limit of the number of facet values to be returned. Only for non-numerical fields. Default value is 10.
facets_show_count facets_show_count = true Option to show the facets count in the response. Item counts are based on the top 1000 results.
group_by group_by=category The metadata field used to group the search results. Only fields marked with ‘searchable’ in ViSearch Dashboard can be used as group_by field. group_by is not supported for /discoversearch.
group_limit group_limit = 10 (default) Limit of the number of groups displayed per page. The maximum value is 100.
sort_by sort_by=price:desc The metadata field used to sort the search results per page. Ascending or descending order needs to be specified.
qinfo qinfo=true If true, query information will be returned.

Automatic Object Detection

$ curl https://visearch.visenze.com/uploadsearch \
       -F image=@example-0.jpg \
       -d detection=all \
       -u access_key:secret_key

# for China, please use 
$ curl https://visearch.visenze.com.cn/uploadsearch \
       -F image=@example-0.jpg \
       -d detection=all \
       -u access_key:secret_key


# example of json response
{
    "status":"OK",
    "method":"uploadsearch",
    "error":[
    ],
    "page":1,
    "limit":30,
    "total":1000,
    "product_types":[
        {
            "type":"top",
            "attributes":{},
            "score":1,
            "box":[
                574,
                826,
                1693,
                2171
            ]
        }
    ],
    "product_types_list":[
        {
            "type": "bag",
            "attributes_list": {}
        },
        {
            "type": "bottom",
            "attributes_list": {}
        },
        {
            "type": "dress",
            "attributes_list": {}
        },
      ...
    ],
    "result":[
        {
            "im_name":"image-name-1",
        },
        {
            "im_name":"image-name-2",
        }
    ]
}
String url = "http://mydomain.com/sample_image.jpg";
UploadSearchParams params = new UploadSearchParams(url);
params.setDetection("all");
PagedSearchResult searchResult = client.uploadSearch(params);
param = {'detection': 'all'}
response = api.uploadsearch(image_url=image_url, **param)
$detection = 'all';
$response = $service->uploadsearch($image, $page, $limit, $fl, $fq, $get_all_fl,
                        $score, $score_max, $score_min, $detection);
params.detection = @"all";
uploadSearchParams.setDetection("all");
visearch.uploadsearch({
  im_url: 'your-image-url',
  score: 'true',
  detection: 'all',
}, (res) => {
  // TODO handle response
}, (err) => {
  // TODO handle error
});

With Automatic Object Recognition, ViSearch /uploadsearch and /discoversearch API are smart to detect the objects present in the query image and suggest the best matched product type to run the search on. /discoversearch API supports a point parameter to indicate the position of the target object by [x,y] coordinates.

We are now able to detect various types of products. Based on the domain of your application, the below sets of objects can be detected respectively:

You can use the Box parameter to restrict the image area [x1,y1,x2,y2] as the portion of your image to search for. When you input a box with 0 width and 0 height, eg. “box”:[574,224,574,224]. We will treat it as a point and detect the object over the current point.

Automatic object recognition based on user input point: detection point

set detection type as ‘bag’

$ curl https://visearch.visenze.com/uploadsearch \
       -d im_url=http://example.com/example-0.jpg \
       -d detection=bag \
       -u access_key:secret_key

# for China, please use 
$ curl https://visearch.visenze.com.cn/uploadsearch \
       -d im_url=http://example.com/example-0.jpg \
       -d detection=bag \
       -u access_key:secret_key

String url = "http://mydomain.com/sample_image.jpg";
UploadSearchParams params = new UploadSearchParams(url);
params.setDetection("bag");
PagedSearchResult searchResult = client.uploadSearch(params);
param = {'detection': 'bag'}
response = api.uploadsearch(image_url=image_url, **param)
$detection = 'bag';
$response = $service->uploadsearch($image, $page, $limit, $fl, $fq, $get_all_fl,
                        $score, $score_max, $score_min, $detection);
uploadSearchParams.setDetection("bag");
params.detection = @"bag";
visearch.uploadsearch({
  im_url: 'your-image-url',
  score: 'true',
  detection: 'bag',
}, (res) => {
  // TODO handle response
}, (err) => {
  // TODO handle error
});

You could also recognize objects from a particular 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.

To obtain the full list for your application, simply make an uploadsearch or discoversearch API call and get from the {product_types_list} in the response.

Sample request to detect bag in an uploaded image:

Selection Box

$ curl https://visearch.visenze.com/uploadsearch \
       -d im_url=http://example.com/example-0.jpg \
       -d box=0,0,20,20 \
       -u access_key:secret_key

# for China, please use 
$ curl https://visearch.visenze.com.cn/uploadsearch \
       -d im_url=http://example.com/example-0.jpg \
       -d box=0,0,20,20 \
       -u access_key:secret_key

File imageFile = new File("/path/to/your/image");
UploadSearchParams params = new UploadSearchParams(imageFile);
// create the box to refine the area on the searching image
// Box(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 box = new Box(50, 50, 200, 200);
params.setBox(box);
PagedSearchResult searchResult = client.uploadSearch(params);
$image = new Image(imagePath);
// create the box to refine the area on the searching image
// Box(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 = new Box(0,0,10,10);
$image->set_box($box);
image_url = 'http://mydomain.com/images/red_dress.jpg'
box = (0,0,10,10)
response = api.uploadsearch(image_url=image_url, box=box)
// create the box to refine the area on the searching image
// Box(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.
...
UploadSearchParams *uploadSearchParams = [[UploadSearchParams alloc] init];

Box *box = [[Box alloc]initWithX1:0 y1:0 x2:100 y2:100];
uploadSearchParams.box = box;

// start searching
...
// if you are uploading an local image
Image image = new Image(this, uri);
// create the box to refine the area on the searching image
// Box(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.
image.setBox(0, 0, 400, 400);

// if you are using im_url or im_id for upload search
// you should pass the box in this way
UploadSearchParams uploadSearchParams = new UploadSearchParams();
uploadSearchParams.setImId(imId);
uploadSearchParams.setBox(new Box(0, 0, 400, 400));

viSearcher.uploadSearch(uploadSearchParams);
visearch.uploadsearch({
  im_url: 'your-image-url',
  // The box format is [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
  // - (x2, y2) is the bottom-right corner of the box
  // IMPORTANT: Do not put space before/after any comma in the box coordinates
  box: 'x1,y1,x2,y2',
}, (res) => {
  // TODO handle response
}, (err) => {
  // TODO handle error
});

If the object you wish to search for takes up only a small portion of your image, or if 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. The box coordinates are set with respect to the original size of the uploading image. For box parameters given in the sequences as x1, y1, x2, y2, (x1, y1) is the top-left corner of the box and (x2, y2) is the bottom-right corner of the box.

Filtering Results

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

$ curl https://visearch.visenze.com/uploadsearch \
       -d im_url=http://example.com/example-0.jpg \
       -d box=0,0,20,20 \
       -d fl=brand \
       -d fl=price \
       -d fq=brand:my_brand \
       -d fq=price:199 \
       -d score=true \
       -u access_key:secret_key

# for China, please use 
$ curl https://visearch.visenze.com.cn/uploadsearch \
       -d im_url=http://example.com/example-0.jpg \
       -d box=0,0,20,20 \
       -d fl=brand \
       -d fl=price \
       -d fq=brand:my_brand \
       -d fq=price:199 \
       -d score=true \
       -u access_key:secret_key

# example of json response
{
    "status":"OK",
    "method":"uploadsearch",
    "im_id":"example_image_id",
    "error":[
    ],
    "page":1,
    "limit":10,
    "total":1000,
    "result":[
        {
            "im_name":"image-name-1",
            "value_map":{
                "brand":"my_brand",
                "price":"199"
            }
        },
        {
            "im_name":"image-name-2",
            "value_map":{
                "brand":"my_brand",
                "price":"199"
            }
        },
        ...
    ]
}
SearchParams params = new SearchParams("vintage_wingtips");
// add fq param to specify the filtering criteria
Map<String, String> fq = new HashMap<String, String>();
// description is metadata type text
fq.put("description", "wingtips");
// price is metadata type float
fq.put("price", "0,199");
params.setFq(fq);
PagedSearchResult searchResult = client.search(params);
fq = {"im_cate": "bags", "price": "10,199"}
response = api.uploadsearch(image_url=image_url, fq=fq)
$fq = array("im_cate" => "bags");
$response = $service->uploadsearch($image, $page, $limit, $fl, $fq);
// add fq param to specify the filtering criteria
Map<String, String> fq = new HashMap<String, String>();
// description is metadata type text
fq.put("description", "wingtips");
// price is metadata type float
fq.put("price", "0,199");
baseSearchParams.setFq(fq);
UploadSearchParams *uploadSearchParams = [[UploadSearchParams alloc] init];

// the type of "count" on db schema is int,
// so we can specify the value range, or do a value match
[uploadSearchParams.fq setObject:@"0,199" forKey:@"count"];
[uploadSearchParams.fq setObject:@"199" forKey:@"count"];

// the type of "price" on db schema is float,
// so we can specify the value range, or do a value match
[uploadSearchParams.fq setObject:@"0.0,199.0" forKey:@"price"];
[uploadSearchParams.fq setObject:@"15.0" forKey:@"price"];

// the type of "description" on db schema is string, so we can do a string match.
[uploadSearchParams.fq setObject:@"wooden" forKey:@"description"];

// start searching
...
var filterQuery = ['description:bag', 'brand:brandA'];
visearch.uploadsearch({
  im_url: 'your-image-url',
  fq: filterQuery,
}, (res) => {
  // TODO handle response
}, (err) => {
  // TODO handle error
});
Type Explanation
string Metadata value must be either
  • exactly matched with the query value, e.g. Vintage Wingtips would not match vintage wingtips or vintage
  • matched with multiple exact query values separated with OR operator. e.g. Wingtips OR Longwing would retrieve results that are matched by either Wingtips or Longwing
  • double quoted if it contains special character, e.g. "Women's shoes" OR "Women's Clothes"would retrieve results that are matched by either Women's shoes or Women's Clothes
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, the smaller value should always be put before the larger.
text Query text field with partial matching and operators. Explained in detail in the following section*
  • for Latin language, metadata value will be indexed using full-text-search engine and supports fuzzy text matching.
  • for non-Latin language, text query can be matched with substrings separated by pre-defined delimiters.

Query Syntax for Text Field *

ViSearch supports querying text fields with partial matching and operators. The commonly used operators are: AND, OR, and NOT. It is case insensitive in any case.

Delimiter

The delimiter will not be used for matching, but to separate the text phrases and concatenate the phrases with the operator to form the query value.

For example, both queries below have the same performance as the query fq=tag:a AND b:

The accepted field delimiter:

Type Accepted Delimier
Latin language [.,?~!@#$%^&*(-+=_`‘\“:;<>/]), space and newlilnes.
non-Latin language unicode delimiters*, including white spaces, English and CJK punctuations.

The full list of unicode delimiter:

Delimiter Explanation Codepoint
whitespace: tab (\t) U+0009
whitespace newline (\n) U+000A
whitespace: form feed (\f) U+000C
whitespace: carriage return (\r) U+000D
whitespace: space U+0020
! ascii: exclamation mark U+0021
ascii: double quotes U+0022
# ascii: number sign U+0023
$ ascii: dollar sign U+0024
% ascii: percent sign U+0025
& ascii: ampersand U+0026
ascii: single quote U+0027
( ascii: open bracket U+0028
) ascii: close bracket U+0029
* ascii: asterisk U+002A
+ ascii: plus U+002B
, ascii: comma U+002C
- ascii: hyphen U+002D
. ascii: dot U+002E
/ ascii: slash U+002F
: ascii: colon U+003A
; ascii: semicolon U+003B
< ascii: less than U+003C
= ascii: equals U+003D
> ascii: greater than U+003E
? ascii: question mark U+003F
@ ascii: at symbol U+0040
[ ascii: open square bracket U+005B
\ ascii: backslash U+005C
] ascii: close square bracket U+005D
^ ascii: caret U+005E
_ ascii: underscore U+005F
` ascii: grave accent U+0060
{ ascii: open curly bracket U+007B
| ascii: vertical bar U+007C
} ascii: close curly bracket U+007D
~ ascii: tilde U+007E
¡ latin: inverted exclamation mark U+00A1
¦ latin: broken bar U+00A6
« latin: open double angle quotations U+00AB
latin: soft hyphen U+00AD
¯ latin: macron U+00AF
´ latin: acute accent U+00B4
¸ latin: cedilla U+00B8
» latin: close double angle quotations U+00B8
¿ latin: inverted question mark U+00BF
ˇ modifier: caron U+02C7
ˉ modifier: macron U+02C9
ˊ modifier: acute accent U+02CA
ˋ modifier: grave accent U+02CB
˜ modifier: small tilde U+02DC
punctuation: hyphen U+2010
punctuation: dash U+2014
punctuation: horizontal bar U+2015
punctuation: double vertical bar U+2016
punctuation: left single quotation U+2018
punctuation: right single quotation U+2019
punctuation: left double quotation U+201C
punctuation: right double quotation U+201D
punctuation: bullet U+2022
punctuation: ellipsis U+2026
punctuation: single left angle quotation U+2039
punctuation: single right angle quotation U+203A
maths: division U+2215
  CJK: space U+3000
CJK: comma U+3001
CJK: full stop (period) U+3002
CJK: left angle bracket U+3008
CJK: right angle bracket U+3009
CJK: left double angle bracket U+300A
CJK: right double angle bracket U+300B
CJK: left corner bracket U+300C
CJK: right corner bracket U+300D
CJK: left white corner bracket U+300E
CJK: right white corner bracket U+300F
CJK: left black lenticular bracket U+3010
CJK: right black lenticular bracket U+3011
CJK: left tortoise shell bracket U+3014
CJK: right tortoise shell bracket U+3015
CJK: left white lenticular bracket U+3016
CJK: right white lenticular bracket U+3017
CJK: reversed double prime quotations U+301D
CJK: double prime quotations U+301E
CJK: katakana middle dot U+30FB
CJK: vertical two dot leader U+FE30
CJK: vertical low line U+FE33
CJK: vertical wavy low line U+FE34
CJK: vertical left bracket U+FE35
CJK: vertical right bracket U+FE36
CJK: vertical left curly bracket U+FE37
CJK: vertical right curly bracket U+FE38
CJK: vertical left tortoise shell bracket U+FE39
CJK: vertical right tortoise shell bracket U+FE3A
CJK: vertical left black lenticular bracket U+FE3B
CJK: vertical right black lenticular bracket U+FE3C
CJK: vertical left double angle bracket U+FE3D
CJK: vertical right double angle bracket U+FE3E
︿ CJK: vertical left angle bracket U+FE3F
CJK: vertical right angle bracket U+FE40
CJK: vertical left corner bracket U+FE41
CJK: vertical right corner bracket U+FE42
CJK: vertical left white corner bracket U+FE43
CJK: vertical right white corner bracket U+FE44
CJK: dashed overline U+FE49
CJK: centreline overline U+FE4A
CJK: wavy overline U+FE4B
CJK: double wavy overline U+FE4C
CJK: dashed underline U+FE4D
CJK: centreline underline U+FE4E
CJK: wavy underline U+FE4F
CJK: comma U+FE50
CJK: ideographic comma U+FE51
CJK: semicolon U+FE54
CJK: colon U+FE55
CJK: question mark U+FE56
CJK: left tortoise shell bracket U+FE5D
CJK: rihgt tortoise shell bracket U+FE5E
CJK: number sign U+FE5F
CJK: ampersand U+FE60
CJK: asterisk U+FE61
CJK: plus U+FE62
CJK: less than U+FE64
CJK: equals U+FE66
CJK: backslash (solidus) U+FE68
CJK: dollar sign U+FE69
CJK: percent sign U+FE6A
CJK: at sign U+FE6B
CJK: full-width exclamation mark U+FF01
CJK: full-width double quotations U+FF02
CJK: full-width single quotation (apostrophe) U+FF03
CJK: full-width left bracket U+FF08
CJK: full-width right bracket U+FF09
CJK: full-width comma U+FF0C
CJK: full-width colon U+FF1A
CJK: full-width semicolon U+FF1B
CJK: full-width question mark U+FF1F
_ CJK: full-width underscore U+FF3F

Operator

Operator Explanation
AND query text fields which are matched by both of the subexpressions.
  • For example, fq=tag:a AND b retrieves results whose tag fields containing both a and b in any order.
OR query text fields which are matched by either of the subexpressions.
  • For example, fq=tag:a OR b retrieves results whose tag fields containing either a or b or both a and b in any order.
NOT query text fields which are not matched by the subexpressions.
  • For example, fq=tag:NOT a retrieves results whose tag fields does not contain a at all.

The default query operator is AND. The default query operator can be customised.

For example, fq=tag:a b will retrieve results with tag value that contain both a and b, same as fq=tag:a AND b.

Precedence

The default precedence from highest to lowest is:

  1. NOT
  2. AND
  3. OR

For example, in the query fq=tag:a OR b AND c, the AND takes precedence, so this is the same as fq=tag:a OR (b AND c). You can override the precedence using fq=tag:(a OR b) AND c.

Result Scores

$ curl https://visearch.visenze.com/uploadsearch \
       -F image=@example-0.jpg \
       -F min_score=0.5 \
       -u access_key:secret_key

# for China, please use 
$ curl https://visearch.visenze.com.cn/uploadsearch \
       -F image=@example-0.jpg \
       -F min_score=0.5 \
       -u access_key:secret_key
// get similarity score
SearchParams params = new SearchParams("vintage_wingtips");
// return scores for each image result, default is false
params.setScore(true);
PagedSearchResult searchResult = client.search(params);
List<ImageResult> imageResults = searchResult.getResult();
for (ImageResult imageResult : imageResults) {
    float score = imageResult.getScore();
    // do something with the score
}

// only retrieve search results with scores between 0.5 and 0.8
SearchParams params = new SearchParams("vintage_wingtips");
params.setScoreMin(0.5f);
params.setScoreMax(0.8f);
PagedSearchResult searchResult = client.search(params);
score = True
response = api.uploadsearch(image_url=image_url, score=score)

# only retrieve search results with scores between 0.5 and 0.8
score_min = 0.5
score_max = 0.8
response = api.uploadsearch(
              image_url=image_url,
              score_max=score_max,
              score_min=score_min)
$score = true;
$response = $service->uploadsearch($image, $page, $limit, $fl, $fq, $score);

// only retrieve search results with scores between 0.5 and 0.8
$score_min = 0.5;
$score_max = 0.8;
$response = $service->uploadsearch($image, $page, $limit, $fl, $fq,
                        $score, $score_max, $score_min);
// return scores for each image result, default is false
baseSearchParams.setScore(true);

IdSearchParams idSearchParams = new IdSearchParams("dress_1");
idSearchParams.setBaseSearchParams(baseSearchParams);
visearch.idSearch(idSearchParams);

...
@Override
public void onSearchResult(ResultList resultList) {
    for (ImageResult imageResult : resultList.getImageList()) {
        float score = imageResult.getScore();
        //Do something with the score
        ...
    }
}

//set the threshold value
baseSearchParams.setScoreMin(0.5);
baseSearchParams.setScoreMax(0.8);

// only retrieve search results with scores between 0.5 and 0.8
IdSearchParams idSearchParams = new IdSearchParams("dress_1");
idSearchParams.setBaseSearchParams(baseSearchParams);
visearch.idSearch(idSearchParams);
UploadSearchParams *uploadSearchParams = [[UploadSearchParams alloc] init];
uploadSearchParams.score = YES; // result will include score for every image

UploadSearchParams *uploadSearchParams = [[UploadSearchParams alloc] init];
uploadSearchParams.score = YES;
// result will include score for every image
uplaodSearchParams.scoreMin = 0.3; // the minimum score is 0.3
uplaodSearchParams.scoreMax = 0.8; // the maximum score is 0.8

// start searching. Every image result will have a score within [0.3, 0.8]. ...
visearch.uploadsearch({
  im_url: 'your-image-url',
  score: 'true',
}, (res) => {
  // TODO handle response
}, (err) => {
  // TODO handle error
});

// only retrieve search results with scores between 0.5 and 0.8
visearch.uploadsearch({
  im_url: 'your-image-url',
  score: 'true',
  score_min: '0.5',
  score_max: '0.8',
}, (res) => {
  // TODO handle response
}, (err) => {
  // TODO handle error
});

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:

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.

Remove Similar Image Results

$ curl https://visearch.visenze.com/uploadsearch \
       -F image=@example-0.jpg \
       -F dedup=true \
       -F dedup_score_threshold=0.5 \
       -u access_key:secret_key

# for China, please use 
$ curl https://visearch.visenze.com.cn/uploadsearch \
       -F image=@example-0.jpg \
       -F dedup=true \
       -F dedup_score_threshold=0.5 \
       -u access_key:secret_key

To remove repeated images or very similar images from the search result list, use dedup and dedup_score_threshold parameters to enlarge the score gap between adjacent results.

Name Type Description
dedup Boolean Parameter to turn on deduplication function. Default is false.
dedup_score_threshold Float Sets the minimum gap between adjacent results. Only works when dedup=true. Default is 0.0.

Retrieving Metadata

$ curl https://visearch.visenze.com/uploadsearch \
       -F image=@example-0.jpg \
       -F box=0,0,20,20 \
       -F fl=brand \
       -F fl=price \
       -u access_key:secret_key

# for China, please use 
$ curl https://visearch.visenze.com.cn/uploadsearch \
       -F image=@example-0.jpg \
       -F box=0,0,20,20 \
       -F fl=brand \
       -F fl=price \
       -u access_key:secret_key

SearchParams params = new SearchParams("vintage_wingtips");
// add fq param to specify the list of metadata to retrieve
List<String> fl = new ArrayList<String>();
fl.add("title");
fl.add("price");
params.setFl(fl);
PagedSearchResult searchResult = client.search(params);
List<ImageResult> imageResults = searchResult.getResult();
for (ImageResult imageResult : imageResults) {
    Map<String, String> metadata = imageResult.getMetadata();
    // read your metadata here
}
fl = ["price", "brand", "title", "im_url"]  
#, or fl = ("price", "brand", "title", "im_url")
response = api.uploadsearch(image_url=image_url, fl=fl)
$fl = array("price","brand","title","im_url");
$response = $service->uploadsearch($image, $page, $limit, $fl);
BaseSearchParams baseSearchParams = new BaseSearchParams();
List<String> fl = new ArrayList<>();
fl.add("price");
fl.add("brand");
baseSearchParams.setFl(fl);

UploadSearchParams uploadSearchParams =
                    new UploadSearchParams(new Image("/path/to/image"));
uploadSearchParams.setBaseSearchParams(baseSearchParams);

//In result callback you can read the metadata
@Override
public void onSearchResult(ResultList resultList) {
    for (ImageResult imageResult : resultList.getImageList()) {
        Map<String, String> metaData = imageResult.getMetaData();
        //Do something with the metadata
        ...
    }
}
SearchParams *searchParams = [[SearchParams alloc] init];
searchParams.fl = @[@"price",@"brand",@"im_url"];

// In result callback you can read the metadata
success:^(NSInteger statusCode, ViSearchResult *data, NSError *error) {
    // Iterate all returned results
    for (ImageResult *result in data.imageResultsArray) {
        NSLog("%@", result.metadataDictionary);//log result's metadata.
        NSLog("%@", [result.metadataDictionary
            objectForKey:@"price"]);//log price in metadata
        //Do something here
    }
}
visearch.uploadsearch({
  im_url: 'your-image-url',
  fl: ['price', 'brand', 'title', 'im-url'], // list of fields to be returned
}, (res) => {
  // TODO handle response
}, (err) => {
  // TODO handle error
});

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.

example of query all metadata

$ curl https://visearch.visenze.com/uploadsearch \
       -F image=@example-0.jpg \
       -F box=0,0,20,20 \
       -F get_all_fl=true \
       -u access_key:secret_key

# for China, please use 
$ curl https://visearch.visenze.com.cn/uploadsearch \
       -F image=@example-0.jpg \
       -F box=0,0,20,20 \
       -F get_all_fl=true \
       -u access_key:secret_key


# example of json response
{
    "status":"OK",
    "method":"uploadsearch",
    "im_id":"example_image_id",
    "error":[
    ],
    "page":1,
    "limit":10,
    "total":1000,
    "result":[
        {
            "im_name":"image-name-1",
            "value_map":{
                "brand":"BrandA",
                "price":"99.0",
                "gender": "Male",
                "age_group": "Adult",
                "item_group_id": "8596225",
                "itemId": "3311950",
            }
        },
         ...
     ]
}
SearchParams params = new SearchParams("vintage_wingtips");
params.setGetAllFl(true);
PagedSearchResult searchResult = client.search(params);
List<ImageResult> imageResults = searchResult.getResult();
for (ImageResult imageResult : imageResults) {
Map<String, String> metadata = imageResult.getMetadata();
// read your metadata here
}
get_all_fl = True
response = api.uploadsearch(image_url=image_url, get_all_fl=get_all_fl)
$get_all_fl = true;
$response = $service->uploadsearch($image, $page, $limit, $get_all_fl);
BaseSearchParams baseSearchParams = new BaseSearchParams();
baseSearchParams.setGetAllFl(true);

UploadSearchParams uploadSearchParams =
                    new UploadSearchParams(new Image("/path/to/image"));
uploadSearchParams.setBaseSearchParams(baseSearchParams);

visearch.uploadsearch({
  im_url: 'your-image-url',
  get_all_fl: 'true',
}, (res) => {
  // TODO handle response
}, (err) => {
  // TODO handle error
});

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

Name Type Example Description
fl String fl=brand&fl=price The metadata fields to be returned. If the query value is not in data schema, it will be ignored. Text fields are not applicable for fl fetch.
get_all_fl Boolean get_all_fl=true If set true, return metadata for all the fields applicable for fl. Default value is false.

Facet and Filtering

You can get the facet results by sending a list of fields to enable faceting on. Here are some limitations on the request:

$ curl https://visearch.visenze.com/uploadsearch \
       -d im_url=http://example.com/example-0.jpg \
       -d box=0,0,20,20 \
       -d fl=Brand \
       -d fl=Gender \
       -d fl=Price \
       -d facets=color,brand,size,price \
       -d facets_limit=5 \
       -u access_key:secret_key

# for China, please use 
$ curl https://visearch.visenze.com.cn/uploadsearch \
       -d im_url=http://example.com/example-0.jpg \
       -d box=0,0,20,20 \
       -d fl=Brand \
       -d fl=Gender \
       -d fl=Price \
       -d facets=color,brand,size,price \
       -d facets_limit=5 \
       -u access_key:secret_key


# example of json response

{
  "status": "OK",
  "method": "uploadsearch",
  "error": [],
  "page": 1,
  "limit": 2,
  "total": 1000,
  "result": [
      {
        "im_name": "3024",
        "value_map": {
          "Brand": "BrandA",
          "Gender": "Women",
          "Price": "10"
        }
      },
      {
        "im_name": "OL13071",
        "value_map": {
          "Brand": "BrandB",
          "Gender": "Men",
          "Price": "20"
        }
      }
  ],
  "facets": [
    {
      "key": "Brand",
      "items": [
          {
            "value": "BrandA",
            "count": 1
          },
          {
            "value": "BrandB",
            "count": 1
          }
    },
    {
      "key": "Gender",
      "items": [
          {
            "value": "Women",
            "count": 1
          },
          {
            "value": "Men",
            "count": 1
          }
      ]
    },
    {
      "key": "Price",
      "range": {
        "min": 10,
        "max": 20
      }
    }
  ]
}

Request Parameters

Name Type Example Description
facets String facets = color,brand,price List of fields to enable faceting.
facets_limit Integer facet_limit = 10 (default) Limit of the number of facet values to be returned. Only for non-numerical fields.
facets_show_count Boolean facets_show_count = true Option to show the facets count in the response. Item counts are based on the top 1000 results.
# E.g. of filtering request with facet result

$ curl https://visearch.visenze.com/uploadsearch \
       -d im_url=http://example.com/example-0.jpg \
       -d box=0,0,20,20 \
       -d fl=brand \
       -d fl=price \
       -d fq=brand:brandA OR brandB \
       -d fq=color:red \
       -d fq=price:0,199 \
       -d score=true \
       -u access_key:secret_key

# for China, please use 
$ curl https://visearch.visenze.com.cn/uploadsearch \
       -d im_url=http://example.com/example-0.jpg \
       -d box=0,0,20,20 \
       -d fl=brand \
       -d fl=price \
       -d fq=brand:brandA OR brandB \
       -d fq=color:red \
       -d fq=price:0,199 \
       -d score=true \
       -u access_key:secret_key

Facet Filtering

To filter search results based on facet values, provide a map of metadata key to filter value in the fq (filter query) property. All the syntax are same as normal filtering results.

Grouping Search Results

$ curl https://visearch.visenze.com/uploadsearch \
       -d im_url=http://example.com/example-0.jpg \
       -d group_by=category \
       -u access_key:secret_key

# for China, please use 
$ curl https://visearch.visenze.com.cn/uploadsearch \
       -d im_url=http://example.com/example-0.jpg \
       -d group_by=category \
       -u access_key:secret_key

# example of json response

{
    "status": "OK",
    "method": "uploadsearch",
    "error": [],
    "page": 1,
    "group_by_key": "category",
    "group_limit": 10,
    "total": 1000,
    "group_results": [
        {
            "group_by_value": "dress",
            "result": [
                {
                    "im_name": "1201"
                },
                {
                    "im_name": "1202"
                },
            ]
        },
        {
            "group_by_value": "skirt",
            "result": [
                {
                    "im_name": "2201"
                },
                {
                    "im_name": "2202"
                },
            ]
        },
        {
            "group_by_value": "jumpsuit",
            "result": [
                {
                    "im_name": "3201"
                },
                {
                    "im_name": "3202"
                }
            ]
        }
    ]
}

You can group your search results by a specified field. The parameters are applicable to /search and /uploadsearch. Here are some limitations on the request:

Request Parameters

Name Type Example Description
group_by String group_by = category Field to be used as a group_by key.
group_limit Integer group_limit = 10 (default) Limit of the number of groups displayed per page. The maximum value is 100.

Sorting Search Results

$ curl https://visearch.visenze.com/uploadsearch \
       -d im_url=http://example.com/example-0.jpg \
       -d sort_by=price:desc \
       -u access_key:secret_key

# for China, please use 
$ curl https://visearch.visenze.com.cn/uploadsearch \
       -d im_url=http://example.com/example-0.jpg \
       -d sort_by=price:desc \
       -u access_key:secret_key

# example of json response

{
    "status": "OK",
    "method": "uploadsearch",
    "error": [],
    "page": 1,
    "limit": 10,
    "total": 1000,
    "result": [
        {
            "im_name": "001",
            "value_map": {
                "price": "120.0"
            }
        },
        {
            "im_name": "002",
            "value_map": {
                "price": "85.0"
            }
        },
        {
            "im_name": "003",
            "value_map": {
                "price": "82.0"
            }
        }
    ]
}

Be default, the search results are sorted in descending order of the scores. You can refine the sorting logic per page for your search results according to a named field. For example, you can sort according to descending order of the price. The parameters are applicable to /search, /uploadsearch and /discoversearch. Here are some limitations on the request:

Request Parameters

Name Type Example Description
sort_by String sort_by = price:asc
sort_by = price:desc
Field to be used as sort key per page, and specify the ascending/ descending order.

Tagging API

API OVERVIEW

Introduction

Our Tagging API (ViRecognition) can be used to detect individual products/objects in images, find their detailed fashion attributes/styles, and predict the image’s quality.

When you upload an image via file or URL, our ViRecognition API can generate tags that describe the object in the image.

You may choose tag_group and tags based on your needs and requirements. Our system will process your images based on the chosen tag_group.

We currently provide a list of tag_group for fashion recognition and image quality recognition. The list is ever-expanding as we explore for more use cases. Check information below for more details.

Authentication key pairs are required to authenticate each API call. Contact us at support@visenze.com to get your API Key pair and tag_group list.

Fashion Recognition

Our image recognition for fashion uncovers every layer of a fashion image. Fashion attribute recognition analyzes your images and tells you what are the fashion attributes inside of them. Fashion style and occasion recognition tells you the fashion elements and trends in your images.

fashion_attributes

tag_group name: fashion_attributes. ViSenze’s fashion attributes taxonomy covers 70 fashion categories and more than 220 fashion tags under attributes including color, pattern, neckline, sleeve style, dress shape, shoe decoration, and many more.

Your images can be clean product images or user generated content. Fashion attribute recognition supports the detection of fashion object(s) in your images, and return the category and the associated attribute tags for each object.

Interested in the complete taxonomy? Please contact your account manager or start a free trial if you do not have an account yet.

fashion_style

tag_group name: fashion_style. This tag_group is used to predict the styles of the fashion object in your image. ViSenze’s fashion style taxonomy covers the following list of styles:

fashion_occasion

tag_group name: fashion_occasion. This tag_group is used to predict the suitable occasions associated with the fashion object in your image. ViSenze’s fashion occasion taxonomy covers the following list of occasions:

gender_detect

tag_group name: gender_detect. This tag_group is used to predict the gender associated with the fashion objects in your images. ViSenze’s gender taxonomy covers the following list of gender information:

Image Quality Recognition

Our API can also recognize images with low quality in terms of whether they are collaged, with text or watermark, blurred, with human/model or show only part of the product.

Here is a list of tag_group names available for image quality recognition:

RECOGNITION API

Authentication

$ curl http://virecognition.visenze.com/v1/image/recognize \
   -u access_key:secret_key

We provide authentication using HTTP Basic Authentication. You can append the base64 string of access key and secret key pair in the request header, which is easy to use and suitable for API calls from backend systems.

name description
access_key Access key string.
secret_key Secret key string. Keep the secret key in a safe place and do not call the API directly from the client-side for security reasons.

For the first method, the following steps describe how a client request URL is generated before making an API call.

The format of authorization in the header is like this: Authorization: Basic €˜access_key:secret_key.

Request

POST https://virecognition.visenze.com/v1/image/recognize

/image/recognize method uses an image (URL or file) as input and generates tags about the image.

Parameters

$ curl http://virecognition.visenze.com/v1/image/recognize \
    -F url=https://example.com/shorts.png \
    -F tag_group=fashion_attributes \
    -F tag_group=fashion_occasion \
    -u access_key:secret_key

There are several limits on the parameters and images:

name description example
url An image URL that will be used to call the engine.

NOTE: required if file has not been specified.
url=http://example_image.com
file An image file.

NOTE: required if url has not been specified.
file=example_image.jpg
tag_group
required
The tag_group parameter allows user to specify the attributes to predict in the given image.
Users can specify multi tag_groups in one API call using multiple tag_group key-value pairs.
Users can also specify the version of the tag_group by adding the version number behind the tag_group name seperated by “:”.

NOTE: Use GET https://virecognition.visenze.com/v1/tag_groups to check the available tag group versions and default versions on your account.
tag_group=fashion_style
tag_group=fashion_attributes

tag_group=fashion_style:2.0.2
object_limit Maximum number of objects to be returned. Return objects with
higher confidence (box) score first. Default is 5, and Maximum number is 30
object_limit = 3
limit Maximum number of tags to be returned for each attribute. Return top N results with confidence scores in descending order. Default number varies for different tag groups, and maximum number is 30 limit = 3
language The language parameter allows user to specify the language he/she prefers the tag to be returned in.
The default language is English, and currently we support Chinese(zh), Korean(ko), Japanese(ja) and Indonesian(id).
language = zh
box Optional parameter for restricting the image area x1,y1,x2,y2. Once this is passed in the parameter, only the area within bounding box will be analyzed.
The box’s size must be minimally 20x20.
box=0,0,20,20
detection The detection parameter allows user to specify the type of products to detect and draw box on. Here is a list of commonly used product types:
  • bag
  • bottom
  • dress
  • onepiece
  • outerwear
  • shoe
  • skirt
  • top
If not specified, all possible types of objects will be detected.

NOTE: The above list of product types is not exhaustive, please approach your account manager to get the full list.
detection = top
taxonomy_mapping The taxonomy_mapping parameter allows user to receive a group of custom tags defined by a rule-based mapping from ViSenze tags.

NOTE: Please approach your account manager to set up the taxonomy mapping for your account.
taxonomy_mapping = seo_keywords

Response

# example response JSON
{
    "error": [],
    "status": "OK",
    "method": "image/recognize",
    "reqid": "853563886081818624",
    "result": [
        {
            "objects": [
                {
                    "tags": [
                        {
                            "tag": "category:apparel",
                            "score": 0.9984000325202942
                        },
                        {
                            "tag": "apparel:lower_body_garment",
                            "score": 0.9795398712158203
                        },
                        {
                            "tag": "lower_body_garment:shorts",
                            "score": 0.8808417320251465
                        },
                        {
                            "tag": "product_color:grey",
                            "score": 0.8789975643157959
                        },
                        {
                            "tag": "product_pattern:melange",
                            "score": 0.7442622184753418
                        },
                        {
                            "tag": "lower_body_length:extra_short",
                            "score": 0.7016705870628357
                        },
                        {
                            "tag": "rise_type:high_rise",
                            "score": 0.4379652738571167
                        }
                    ],
                    "box": [
                        45,
                        170,
                        1009,
                        919
                    ]
                }
            ],
            "tag_group": "fashion_attributes"
        },
        {
            "objects": [
                {
                    "tags": [
                        {
                            "tag": "beach_swim",
                            "score": 0.9997109770774841
                        }
                    ],
                    "box": [
                        45,
                        170,
                        1009,
                        919
                    ]
                }
            ],
            "tag_group": "fashion_occasion"
        }
    ]
}

For a single tag group, the information includes:

name description
status OK or fail.
error List of error messages.
result List of tags (with confidence scores) grouped according to tag groups.
tag Name of the tag.
tag_group The name of the tag group which the tag belongs to.
box The perimeter of the detected object, with the coordinates [x1, y1, x2, y2]. [x1, y1] and [x2, y2] are the bottom-left and upper-right coordinates of the bounding box accordingly. Valid only when the requested tag_group enable object detection.
score Confidence score ranging from 0 to 1. The higher the number, the more confident our ViRecognition engine is of correctly recognizing the object.

Automatic Object Detection

# Automatically recognize the main object(s) and return corresponding tag values:

$ curl 'https://virecognition.visenze.com/v1/image/recognize' -u access_key:secret_key  \
    -F "url=https://example.com/example_1.jpg" \
    -F "tag_group=fashion_attributes"

# example response JSON
{
    "status": "OK",
    "method": "image/recognize",
    "error": [],
    "result": [
            {
            "objects": [
                {
                    "tags": [
                        {
                            "tag": "category:t_shirt",
                            "score": 0.9992560148239136
                        },
                        {
                            "tag": "neckline:o_neck",
                            "score": 0.9824492931365967
                        },
                        {
                            "tag": "sleeve_length:short",
                            "score": 0.9993560910224915
                        },
                        {
                            "tag": "sleeve_style:straight",
                            "score": 0.9986153841018677
                        },
                        {
                            "tag": "top_length:short",
                            "score": 0.9964359402656555
                        }
                    ],
                    "box": [
                      185,
                      118,
                      397,
                      299
                    ]
                },
                {
                    "tags": [
                        {
                            "tag": "category:jeans",
                            "score": 0.9683170318603516
                        },
                        {
                            "tag": "pants_fit_type:straight_leg",
                            "score": 0.8666971325874329
                        },
                        {
                            "tag": "denim_wash_color:medium",
                            "score": 0.9181555509567261
                        }
                    ],
                    "box": [
                      207,
                      267,
                      395,
                      621
                    ]   
                }
            ],
            "tag_group": "fashion_attributes"
        }
    ]
}


Our recognize API can automatically extract the objects from a noisy background image. For example, in the image below, we could recognize the tshirt and the jeans as two objects and return their corresponding attributes. For the t_shirt, we will return its neckline, sleeve_length, sleeve_style, and top_length; while for the jeans, we will return its pants_fit_type and denim_wash_color.

recognize

If you have already known what’s the product for the image, you can specify the category parameter with the product type to make our automatic extraction of the key objects more accurate. This is an optional parameter but it is highly recommended for eCommerce clients to tag product images with well-defined category info.

For the same image, when specify the category=jeans, our API will detect the jeans in the given images and return only the jeans attributes correspondingly, including pants_fit_type and denim_wash_color.

recognize_pants

Error Codes

General Error Messages

Message
System busy, please try again later.

Image Error Messages

Message Remarks
Image not given. Do check your image source again and see if it is an image or another filetype.
Only one image source is allowed. Do use **either* im_url or image param.*
Multiple image url detected. Only one is allowed.
Missing tag group parameters. Your tag_group param should contain at least one of the categories found in the product tagging catalogue.
Invalid image. The supported image formats includes: .jpg, .jpeg, .jpe, .png, .gif, .bmp, .dib, .webp, .pbm, .pgm, .ppm, .sr, .ras, .tiff, .tif
Image file size over limit. The maximum file size of an image is 10MB.
Unable to get image from url. Do check your im_url to see if it links to a publicly accessible image.
Invalid box parameter. Your box parameters may be out of the range of the given image.
Box parameter should not contain negative values.
Box parameter dimensions should be at least 20x20.
Please use form-data for request body in POST method. Query with url params is no longer supported.

Authentication Error Messages

Message
Authentication failed. Invalid access key or secret key.
No access rights to tag groups: {0}.
Missing authorization information.
Account is disabled. Please contact administrator for enquiries.
Invalid tag group {0}.
Tag group {0} given in version does not match with any tag group given.

ProductCat API

API OVERVIEW

Introduction

Our ProductCat(Products Catalog Platform) API enables you to find and search for your products more easily by cataloguing your products automatically.

Each product response returned from the products summary API represents a unique product. In other words, URLs that represent the same product on different stores will be merged into a single pgid (ViSenze generated product group ID) entry.

Product variations are stored as separate entries in the database. For example, if a particular model of shoes is sold in two colors and two sizes, the product details API will return up to four entries for this model of shoes. For the purpose of grouping, these variations will each be tagged with the same pgid. Each variant has a unique product id (pid).

Authentication

The API is secure with HTTPS. To use the API, an app_key parameter must be provided in each API call. Please contact us at support@visenze.com to get an API endpoint and an API Key.

$ curl https://productcat.visenze.com/summary/products?app_key=xxxxx
      -X POST \
      -u im_url=https://visenze-productivity-evaluation.s3-accelerate.amazonaws.com/fca641b3ad7d23d3561585fa9ee4f972a239f470

# for China, please use
$ curl https://productcat.visenze.com.cn/summary/products?app_key=xxxxx
      -X POST \
      -u im_url=https://visenze-productivity-evaluation.s3-accelerate.amazonaws.com/fca641b3ad7d23d3561585fa9ee4f972a239f470
// ProductCat must be initialized with an app key before it can be used, default endpoint (https://productcat.visenze.com)

ProductCat productCat = new ProductCat.Builder(appKey)
                        // optional, set custom endpoint that is not productcat.visenze.com
                        .setApiEndPoint(new URL(customEndpoint))
                        // optional, set request timeout
                        .setTimeout(30000)
                        // optional, set an unique string to identify the search requests coming from same user
                        .setUid(uniqueStringId)
                        .build(context);

SDK Setup

// You can include the dependency in your project using gradle:

compile 'com.visenze.productcat:productcat:1.2.4'

// In the build.gradle file under your app module, add the packaging options to ensure a successful compilation:

android {
  ...

    packagingOptions {
        exclude 'META-INF/NOTICE'
        exclude 'META-INF/LICENSE'
    }
    ...
}

You can easily setup our SDK with your preferred language and get started with integrations. You can find the source code our SDKs on the following github repos:

Error Codes

Generic system errors

Code Error Message
100 Unauthorized.
101 A system error is reported and we are fixing it right now.
102 System busy, please try again later.
103 Parameter ‘{param}’ type is invalid. Example: Parameter search_min_score type is invalid.
104 limit must be no more than 100.
105 box parameter must include exactly 4 integers in comma separated format.
106 Product not found.
107 Invalid thumbnail_size format.
108 price parameter must include exactly 2 numbers in comma separated format.
109 page must be at least 1.
110 cp1 length must be no more than 32.
111 cp2 length must be no more than 32.
112 Product not found.
117 price_unit parameter is invalid: ‘{invalid_value}’.
118 Invalid country code: ‘{invalid_value}’.
119 Invalid store_id: ‘{invalid_value}’.
122 The request format is not supported. Please use multipart/form-data for request body.
123 A network error has occurred. Please check your connection and try again.
124 An unknown network error has occurred. Please try again later.
125 Parameter ‘{param}’ must be true or false.
126 sort_by field ‘{field}’ is not supported.
127 thumbnail_size dimension must be in [20, 1024] range.
128 facets_limit must be in [1, 1000] range.
129 page must be in [1, 50] range.
130 facets field ‘{field}’ is not supported.
132 latLng parameter must include exactly 2 numbers in comma separated format.
199 Parameter ‘{param}’ is required.

Visual Search Errors

Code Error Message
200 Any generic visual search related-error. Can be one of the following:
  • Could not download the image, please try again later.
  • Request image size exceeds 10 MB.
  • Timeout while downloading image, please try again later.
  • {parameter} is required.
  • {parameter} is invalid.
  • {parameter} must be no more than {number}
  • {parameter} must be false or true.
  • {parameter} must be file object.
  • {parameter} must be a valid number.
  • {parameter} is invalid.
  • The facets_limit must be in [1, 1000].
    201 Invalid image file format.
    202 Image not found.

    Text Search Errors

    Code Error Message
    300 Text search related-error. Example:
    Text query missing.

    PRODUCT SEARCH APIs

    ViSenze Product Search APIs provide visual search and text search from a comprehensive collection of online products. A unique user identifier can be passed to the APIs for user actions track.

    1. Products Summary
      Products summary API returns a list of products with summaries, based on a specified query. Visual search and text search are supported.

    2. Product Details
      Product details API returns product detail and its variants information including product latest offers at various stores.

    3. Product Deeplink
      Product Deeplink API redirects to the product deeplinking URL page (with affiliate tracking info if available).

    Products Summary

    endpoint /summary/products

    This API will return a list of product summaries based on a specified query.

    Image search can be performed by providing an image multi-part data or a previously search image ID. Please note the following for image search:

    image resizing settings

    When performing visual search, you may notice the increased search latency with bigger image file size. This is due to the longer time in the network to transfer your images to the ProductCat server, and for processing larger images.

    To reduce the latency, it is recommended to resize the image before sending to our server. To lower search latency while not sacrificing search accuracy for general use cases, we recommend to use lossless compression to at least 800x800 pixels.

    common request parameters

    $ curl https://productcat-example.visenze.com/summary/products?app_key=1234567abcdefg
          -X POST \
          -u im_url=https://visenze-productivity-evaluation.s3-accelerate.amazonaws.com/fca641b3ad7d23d3561585fa9ee4f972a239f470
    
    # for China, please use
    $ curl https://productcat-example.visenze.com.cn/summary/products?app_key=1234567abcdefg
          -X POST \
          -u im_url=https://visenze-productivity-evaluation.s3-accelerate.amazonaws.com/fca641b3ad7d23d3561585fa9ee4f972a239f470
    
    // Using an image from a local file path:
    
    Image image = new Image("/local/path/to/image.jpg");
    ImageSearchParams searchParams = new ImageSearchParams(image);
    
    productCat.imageSearch(searchParams);
    
    
    // Using an image by providing the Uri of the image in photo gallery:
    
    Image image = new Image(context, uri);
    ImageSearchParams searchParams = new ImageSearchParams(image);
    
    productCat.imageSearch(searchParams);
    
    
    // Construct the image from the byte array returned by the camera preview callback:
    
    @Override
    public void onPictureTaken(byte[] bytes, Camera camera) {
        Image image = new Image(bytes);
        ImageSearchParams searchParams = new ImageSearchParams(image);
    
        productCat.imageSearch(searchParams);
    }
    
    
    // Alternatively, you can pass an image url directly to uploadSearchParams to start the search :
    
    String url = "http://mydomain.com/sample_image.jpg";
    ImageSearchParams searchParams = new ImageSearchParams(url);
    
    productCat.imageSearch(searchParams);
    
    
    // If you are performing refinement on an uploaded image, you can pass the im_id returned in the search result to start the search instead of uploading the image again:
    String imId;
    
    @Override
    public void onSearchResult(ResultList resultList) {
        imId = resultList.getImId();
      for (ProductSummary summary : resultList.getProductSummaryList()) {
        //Do something with the result
        ...
      }
    }
    
    ImageSearchParams searchParams = new ImageSearchParams(url);
    uploadSearchParams.setImId(imId);
    productCat.imageSearch(searchParams);
    
    
    // Text Search solution is to search similar products by given query text.
    
    TextSearchParams textParams = new TextSearchParams(queryText) ;
    productCat.textSearch(textParams);
    
    name type description
    im_url string Only applicable for image search.
    Search by providing an image URL. Image file or im_url or im_id must be provided for image search.
    im_id string Only applicable for image search.
    For each uploaded image, ViSearch service will return an unique im_id which can be used to do further search without needing to re-upload the image again. Image file or im_url or im_id must be provided.
    image file Only applicable for image search.
    The image file object that will be searched against the image collection. Image file or im_url or im_id must be provided for image search.
    uid string (Optional) Unique string that can identify the user/app, e.g. device serial, advertising ID or a server generated string (reqid for first search) for analytics purpose.
    q string Only applicable for text search.
    Free text search keyword. E.g. “nike shoes” will return products with description containing “nike” and/or “shoes” words.
    country string Filter search results by products that ship to this country code. ISO Alpha-2 code of a country. e.g. SG, US…. Refer to ISO country codes .
    price string Filter results by sale price range e.g. price=20,100 will return results with price between 20 and 100, and price=199 would match ranged query 0,199 but would not match ranged query 200,300.
    store_ids string Filter search results by list of store ids in comma separated format e.g. 5,7.
    box string Only applicable for image search.
    The image bounding box for the search. The box should be in the format of “x1,y1,x2,y2”. The upper-left corner of an image is (0,0). The box is useful in the following scenarios:
    • There are multiple products in the image and users want to select their desired product by cropping a box.
    • The search was already performed once. The API will return an im_id. User crops the image and only the im_id and box coordinates need to be sent (instead of re-uploading the image which would take longer).
    Note: If the box coordinates are invalid (negative or exceed the image boundary), it will be ignored.
    auto_roi boolean Default value is false.
    Set to true if the box covering the region of interest (ROI) is automatically generated by the Android client, and not by an end user.
    Note: If the box values are invalid or null, the auto_roi value will be ignored.
    page int The result page number. Used for pagination.
    Default value is 1.
    limit int The number of results per page.
    Default value is 10. Value range is from 1 to 100, inclusive.
    facets string List of fields to enable faceting, in comma separated format. Currently only store and price are supported.
    facets_limit int Limit the number of facet values to be returned. Only applicable for non-numerical fields e.g. store. For image search, this shows the items appearing in the top 1000 results. This parameter only takes effect with facets specified, otherwise is ignored.
    Value range is from 1 to 1000, inclusive.
    sort_by string The metadata field used to sort the search results. Ascending or descending order needs to be specified. Currently only price is supported. e.g. sort_by=price:desc
    search_min_score float Only applicable for image search.
    Filter search result if visual score is above this threshold. The score is referring to the visual similarity score of each product image in the search results.
    The range of the value is from 0 to 1, inclusive.
    show_visual_score boolean Default value is false. Only applicable for image search. If set to true, will display the visual similiarity score of each product image in the search results.
    thumbnail_size string Specify the preferred thumbnail size in a format similar to 256x256. Value limits from 20x20 to 1024x1024.
    detection_only boolean Default value is false.
    By default the response shows search results. If this parameter is set to true, returns detection box only, search results are set to empty.
    cp1 string (Optional) custom tag parameter for analytics or for your own subid tracking. Max length limit of 32 characters.
    cp2 string (Optional) similar to cp1 , cp2 is an additional tag parameter that can be sent. Max length limit of 32 characters.

    To support promoted listing and sponsored content, the following optional API parameters can be added.

    name type description
    return_sponsored_content boolean Whether to return sponsored content (e.g. promotions/offers/deals/ featured listing or ads) for this search. Default value is false. Set this to true to return the sponsored content if applicable.
    s_banner_img_w int exact width of sponsored banner image in pixels (generally located at the top as a promotion or offer banner before the search results). This is optional. Either s_banner_img_w or s_banner_img_wmin should be set. It is recommended to leave this parameter blank and set s_banner_img_wmin.
    s_banner_img_wmin int (Recommended to set) minimum width of sponsored banner image in pixels. The client can rescale image if a bigger image is returned. Either s_banner_img_w or s_banner_img_wmin should be set.
    s_banner_img_h int exact height of sponsored banner image in pixels. This is optional. Either s_banner_img_h or s_banner_img_hmin should be set. It is recommended to leave this parameter blank and set s_banner_img_hmin.
    s_banner_img_hmin int (Recommended to set) minimum height of sponsored banner image in pixels. The client can rescale image if a bigger image is returned. Either s_banner_img_h or s_banner_img_hmin should be set.
    s_banner_img_mime string comma separated list of supported image MIME types by the client e.g. “image/jpg,image/gif”.
    s_title_max_len int Maximum length of text in the title element of sponsored content or featured listing within the search results. Default value is 25. Recommended values: 25, 90 or 140.
    s_desc_max_len int Maximum length of text in the desc element of sponsored content or featured listing within the search results. Default value is 25. Recommended values: 25, 90 or 140.

    The desc element is optional and must appear below the title element in another line and with different visual representation e.g. smaller font with optionally a different color. The desc refers to a short description for the sponsored content e.g. “Up to 70% off”
    s_img_w int exact width of sponsored content or featured listing image (within the search results) in pixels. This is optional. Either s_img_w or s_img_wmin should be set. It is recommended to leave this parameter blank and set s_img_wmin.
    s_img_wmin int (Recommended to set) minimum width of sponsored content or featured listing image (within the search results) in pixels. The client can rescale image if a bigger image is returned. Either s_img_w or s_img_wmin should be set.
    s_img_h int exact height of sponsored content or featured listing image (within the search results) in pixels. This is optional. Either s_img_h or s_img_hmin should be set. It is recommended to leave this parameter blank and set s_img_hmin.
    s_img_hmin int (Recommended to set) minimum height of sponsored content or featured listing image (within the search results) in pixels. The client can rescale image if a bigger image is returned. Either s_img_h or s_img_hmin should be set
    s_img_mime string comma separated list of supported image MIME types by the client e.g. “image/jpg,image/gif”.
    uip string records the actual IP address of the user device if the request is forwarded from user device to partner server before reaching ViSenze server.
    ua string records custom user agent of the user device if the request is forwarded from user device to partner server before reaching ViSenze server.
    device_model string client device model
    os string client device operating system e.g Android
    osv string client device operating system version
    didmd5 string hardware device ID e.g. IMEI hashed in md5. This is optional if uid or ifa is already provided
    ifa string Google advertising ID or Apple IDFA. Providing this will enable more relevant sponsored content/native ads
    geo string user’s device latitude and longitude in comma separated format e.g. 90.0,180.0

    response fields

    The response is in JSON format. The sponsored_content section will be added to API response if return_sponsored_content is set to true in API request and there is available sponsored contents for the API request.

    # example response JSON
    {
        "im_id": "example_image_name.jpg",
        "reqid": "770150114080614372",
        "status": "OK",
        "error": [],
        "product_types": [
            {
                "type": "dress",
                "score": 0.968,
                "box": [
                    302,
                    36,
                    703,
                    1261
                ],
                "attributes": {}
            }
        ],
        "result": [
            {
                "pgid": "b3555f8bbd30u9febf823e5e5c07e04c",
                "main_image": "https://imgtio.visenze.com/product-search-example-image.jpg",
                "images": [
                    "https://cdn-images.store.com/1/product-sesarch-example-image.jpg"
                ],
                "title": "Elie Saab Plunge Dress",
                "desc": "Shop Elie Saab plunge dress.",
                "brand": "Elie Saab",
                "brand_id": "7654321",
                "country": "US",
                "min_price": 49.36,
                "max_price": 49.36,
                "price_unit": "SGD",
                "price_symbol": "S$",
                "original_min_price": 35.95,
                "original_max_price": 35.95,
                "original_price_unit": "USD",
                "attrs": {
                    "source": "V-store",
                    "color" : "",
                        ...
                    ]
                },
                "stores": [
                    {
                        "store_id": 12300000,
                        "name": "V Store",
                        "availability": 1
                    }
                ],
                "availability": 1,
                "pid": "XXXX-US_12676714",
                "product_url": "https://productcat-api.visenze.com/redirect/XXXX-US_12676714?cid=123456&reqid=XXXXX&pos=1&uid=XXX&country=US",
                "visual_score": 0.6906737
            },
            ...
        ],
        "sponsored_content": [
            {
                "id": 2,
                "content_type": "banner",
                "tracker_url": "http://track.visenze.com/__aq.gif",
                "link": "https://www.visenze.com/",
                "placement": "top",
                "images": [
                    {
                        "url": "https://imgresize.visenze.com.cn/sample_banner.jpg",
                        "w": 1920,
                        "h": 485
                    }
                ]
            },
            {
                "id": 1,
                "content_type": "ads",
                "title": "Test ads title",
                "desc": "Test ads content",
                "tracker_url": "http://track.visenze.com/__aq.gif",
                "link": "https://www.visenze.com/",
                "placement": "within",
                "placement_position": 8,
                "images": [
                    {
                        "url": "https://imgresize.visenze.com.cn/visenze.jpg",
                        "w": 1200,
                        "h": 627
                    }
                ]
            },
            {
                "id": 3,
                "content_type": "featured_listing",
                "tracker_url": "http://track.visenze.com/__aq.gif",
                "link": "https://www.visenze.com/",
                "placement": "within",
                "placement_position": 4,
                "org_search_result_position": 10
            }
        ],
        "facets" : [
                 {
                  "key": "store",
                  "items": [
                      {
                         "count": 82,
                        "name": "V Store",
                        "id": 1547675469,
                        "value": "V-store"
                      },
                      {
                         "count": 10,
                        "name": "Sample Store",
                        "id": 1234,
                        "value": "sample-store"
                      }
                  ]
                },
                {
                  "key": "price",
                  "range": {
                    "min": 10.45,
                    "max": 999.5
                  }
                }
          ],
          "recognize_result": [
                 {
                "tag_group": "category",
                "tags": [
                    {
                        "tag_id": "root|bag",
                        "tag": "bag",
                        "score": 0.9836792349815369
                    },
                    {
                        "tag_id": "root|bag|backpack",
                        "tag": "backpack",
                        "score": 0.9464564323425293
                    }
                ]
                }
    
          ]
    }
    
    // example response
    @Override
    public void onSearchResult(ResultList resultList) {
      for (ImageResult imageResult : resultList.getImageList()) {
        //Do something with each result image
        ...
      }
    }
    
    @Override
    public void onSearchError(String error) {
        resultView.displayError(error);
    }
    
    
    @Override
    public void onSearchCanceled() {
    
    }
    
    name description
    status The request status, either OK, warning, or fail.
    error The list of error if the request was not successful i.e. when status is warning or fail.
    im_id Image ID. Can be used to search again without reuploading.
    reqid The unique request id. This can be used for event tracking purpose e.g. tracking user behaviour.
    product_types Detected product types and their bounding box in (x1,y1,x2,y2) format.
    result The list of products in the search results.
    facets List of facet fields value and response.
    sponsored_content The list of sponsored content corresponding to specified country parameter in the API request.
    page The result page number.
    limit The number of results per page.
    total Total number of search results.
    country_filter Indicate if this country is supported in our platform. not_supported indicates that there are not enough products in the platform. In this case, the search will return matching products in corresponding geographical region.

    If sponsor content is available, it will be returned in sponsored_content section. The details for various fields within the section can be found below.

    name type description
    id int The sponsored content ID. It is not needed to display this field in the UI. Meant for analytics purposes.
    content_type string Type of sponsored content:

    - ads: native ads with title, image and optional desc elements. Generally displayed within Search Results.
    - banner: promotion/offer banner generally displayed at the top, before Search Results. Only image element is needed.
    - featured_listing: featured product listing with placement_position defining the boosted product position.
    title string Title of sponsored content. Only applicable for ads content type.
    desc string Description of sponsored content. Only applicable for ads content type. This field is optional and must appear below title field.
    images array contained list of images that can be displayed for the sponsor content e.g. banner image, a featured listing or ads image. Each image object will consist of w (image width), h (image height) and url (image URL). Image width and height might be unavailable. The images might be in different dimension and the optimal image can be chosen for display in the client. Only 1 image is needed for display in the UI.
    link string Destination link (landing page) when user clicks on the Sponsored content i.e. this link must be opened upon clicking (activation) of the content.
    tracker_url string A transparent tracking image pixel (1x1 in dimension) which records the impression when user views a Sponsor Content. This URL must be called in the background to measure ads impression accurately if the content is shown to end-user.
    placement string Where to position the content. Possible values: “top” , “bottom” , “within”.
    - top : show this content at the top, before the search results e.g. ads banner
    - bottom: show this content at the bottom, after the search results e.g. recommendation widget
    - within: show this content within the search results e.g. promoted listing
    placement_position int If “placement” is “within”, this specifies the position to put this content within the search result. For example, “4” means that this content should replace the 4th search result ( search result items from 4th position will be pushed down).

    For featured_listing content type, this refers to the boosted position of the product in the search result.
    org_search_result_position int Only applicable for featured_listing content type. This refers to the original position of the featured product before boosting.

    Product Details

    GET /summary/products/{pgid}

    This API returns product detail and its variants information including product latest offers at various stores.

    request parameters

    $ curl https://productcat-example.visenze.com/summary/products/876f0932d1c5523baf30a7b6c926274c?app_key=1234567abcdefg
          -X GET \
    
    # for China, please use
    $ curl https://productcat-example.visenze.com.cn/summary/products/876f0932d1c5523baf30a7b6c926274c?app_key=1234567abcdefg
          -X GET \
    
    
    
    
    name type description
    pgid required string Product Group ID.
    uid string Unique string that identifies the user, e.g. device serial, advertising ID or a server generated string. For action track purpose.
    image_size string Specify the preferred image size in a format similar to 800x800.
    uid string (Optional) Unique string that can identify the user/app, e.g. device serial, advertising ID or a server generated string (reqid for first search) for analytics purpose.
    cp1 string (Optional) custom tag parameter for analytics or for your own subid tracking. Max length limit of 32 characters.
    cp2 string (Optional) similar to cp1 , cp2 is an additional tag parameter that can be sent. Max length limit of 32 characters.

    response properties

    # example response JSON
    {
        "status": "OK",
        "error": [],
        "result": {
            "pgid": "876f0932d1c5523baf30a7b6c926274c",
            "main_image": "https://imgtio.visenze.com/product-sesarch-example-image.jpg",
            "images": [
                "https://cdn-images.visenze-store.com/6/product-sesarch-example-image.jpg",
            ],
            "title": "Adrianna Papell Green Vivid Emerald Embellished Satin Chiffon Gown Long Formal Dress Size 2 (XS)",
            "desc": "Brand new, with tags, never been worn!  Sizes 2-16. ",
            "country": "US",
            "min_price": 199,
            "max_price": 199,
            "price_unit": "USD",
            "attrs": {
                "source": "V-store"
            },
            "stores": [
                {
                    "store_id": 7654321,
                    "name": "V-store",
                    "availability": 1
                }
            ],
            "variants": [
                {
                    "title": "Adrianna Papell Green Vivid Emerald Embellished Satin Chiffon Gown Long Formal Dress Size 2 (XS)",
                    "desc": "Brand new, with tags, never been worn!  Sizes 2-16. ",
                    "pid": "VS_22202720",
                    "gtin": [
                        "22202720"
                    ],
                    "images": [
                        "https://cdn-images.visenze-store.com/7/product-sesarch-example-image.jpg"
                    ],
                    "main_image": "https://cdn-images.visenze-store.com/product-sesarch-example-image.jpg",
                    "store_id": 231912530,
                    "availability": 1,
                    "attrs": {
                        "source": "V-store"
                    },
                    "product_url": "https://www.visenze-store-example.com/dresses/dress-green-22202720/",
                    "latest_offer_id": "8971d94a263b5506a846854d37cc118f",
                    "price_unit": "USD",
                    "original_price": 199,
                    "sale_price": 199,
                    "deeplink_url": "https://productcat-api.visenze.com/redirect/MR-PORTER-VS_22202720?cid=12345&reqid=XXX&pos=1&uid=XXX&country=US"
                },
                ....
            ],
            "availability": 1,
            "pid": "VS_22202720"
        }
    }
    
    name description
    status The request status, either OK, warning, or fail.
    error The list of error if the request was not successful i.e. when status is warning or fail.
    result Product detail and its variant information.

    SEARCH ANALYTICS

    To analyze search performance and usage statistics (such as Click Through Rate, Active Users, Conversion Tracking, Retention Rate, etc), it is recommended that the uid paramater is sent on all requests. The UID can be generated in 2 ways:

    If you use our Android SDK, the UID is automatically captured from our server.

    {} 
    
    {}