ViSenze Tech Blog

Best Practices: Using im_id to refine upload search results

Posted by Yu Lu on Mar 16, 2016 7:51:09 PM

Visual search uploadsearch API provides powerful features on product category detection, results filtering, image cropping and pagination. They allow users to refine search results based on their preferences to get more accurate and relevant matches. As we noticed that users were performing result refinements frequently, we decided to introduce a cool feature to ViSearch uploadsearch API to make your search process even faster - im_id

When you upload an image file to perform upload search, an automatically-generated im_id is returned in the response. By attaching this im_id in the search parameters and calling the uploadsearch API again, you can skip the step of re-uploading the query image. This way, you get faster responses when performing search result refinements, as well as reducing network bandwidth usage since multiple uploading of the same query image are eliminated.

Curious about how this feature can be implemented in your application? Here is how we have done it in our Android demo app.

Overview of the search flow


Here is a simple illustration on the search flow in class of our Android demo, which takes on the main responsibility of performing search result refinement. Whenever you perform search result refinement by either changing the crop-box area, switching to another detection type, or rotating the image, the system will check whether the image has been modified. If the image is not modified, im_id will be used in the upload search instead of you having to re-upload the same image again.

Get im_id from upload search result

In class, we can get an auto-generated im_id from the search result obtained in It is returned together with the result list and can be queried by resultList.getImId():

private String imId;


public View onCreateView(LayoutInflater inflater, ViewGroup container,
                            Bundle savedInstanceState) {
   resultList = ((EditPhotoActivity)getActivity()).getResultList();
   imId = resultList.getImId();

Set im_id parameter in upload search parameter

Whenever we perform search refinement by either setting fq filters, searching for a specified sub-area of the query image or changing detection categories, we can set the value of the im_id parameter in the uploadsearch parameters as the id returned from the initial search result without attaching the image file:

//set search parameters
UploadSearchParams uploadSearchParams = new UploadSearchParams();
uploadSearchParams.setBox(new Box(x1, y1, x2, y2));


Set cropping box when using im_id

The cropping box is also supported when searching using im_id. Instead of passing the box parameters to Image object, which automatically performs a resizing of the image and re-calculation of the box based on the image quality configured, a Box object is directly passed to the UploadSearchParam object and no resizing will be performed. So you need to make sure the box parameters passed in are with respect to the resized image that is being uploaded for the first time. Please refer to the developer documentation for the image size we support in Android SDK.

Upload the image again if the image has been modified

If the image itself has been modified, for example being rotated, the modified image has to be uploaded again. In our demo, we re-upload the image if it has been rotated:

public void rotateImage() {

   Image image = new Image(imagePath, Config.IMAGE_QUALITY);

   //set search parameters
   UploadSearchParams uploadSearchParams = new UploadSearchParams(image);

Any refinement after the rotation shall be based on the new uploaded image. Therefore we need to update the im_id parameter from the search result:


public void onSearchResult(ResultList resultList) {

   if (resultList.getImId() != null) {
       this.imId = resultList.getImId();

   categoryListView.scrollTo(productList.indexOf(selectedType), 0);


Topics: New product features, Best practices