ViSenze Tech Blog

Best practices: Visual search Insert Status APIs

Posted by Guangda Li on Mar 10, 2015 3:48:00 PM

In our previous blog post, we announced the launch of a new feature in our visual search Data API - detailed error reporting for the failed insertion of images. With the introduction of this Data Insert Status API (/insert/status), we'd also like to share some tips for using it.

Our visual search Data APIs provide interfaces to allow developers manage their image collections. Insert API (/insert) is called to start an insert task for adding or updating images. Insert API (/insert) is able to handle up to 100 images insert in a single API call. This process runs asynchronously and takes certain amount of processing time to finish. During the processing, developers can always use Data Insert Status API (/insert/status) to monitor the progress.

 

Get transaction id from /insert response

When Insert API (/insert) is called to insert datas, a transaction id will be returned in the response. Developers can use this id to track the progress of this insert task.

Sample JSON response of POST /insert


{

   "status": "OK",
   "method": "insert",
   "trans_id": 246806789063168000,
   "total": 100,
   "result": [],
   "error": []
}

 

Check processing progress

 

Developers can check how much data has been processed at the time when the API call is made through the processed_percent field in the JSON response. This value is the rounded percentage value of the amount of processed images over the total number of images for this particular inserting transaction. E.g. a value of 100 means that all data in this transaction has been processed. They can also check if any error occurs during the insert task by check the value of "fail_count".

 

User case: Successful insert task

 

When the response shows that processed_percentis 100 and "fail_count" is 0, the insert task is considered to be finished and all the images are successfully indexed. Now the images inserted in this transaction are ready for search.

 

Sample JSON response of GET /insert/status/{transcation_id}


{
   "status": "OK",
   "method": "insert/status",

   "error": [],
   "result": [
       {
           "trans_id": 29031939452,

           "processed_percent": 100,
           "success_count": 55,
           "fail_count": 0,
           "total": 55,
           "error_list": []
           "error_page": 1,
           "error_limit": 10,
       }
   ]
}


User Case: Error in Insert task

 

processed_percent only reveals processing status. To check whether the image has been indexed successfully, developers should look at the error information in the JSON response. The error information are updated whenever an error is encountered during the inserting process. If "fail_count" shows a non-zero value, it means that error occurs when processing the image. The detail error information is listed in "error_list".

 

Sample JSON response of GET /insert/status/{transcation_id}


{
   "status": "OK",
   "method": "insert/status",

   "error": [],
   "result": [
       {
           "trans_id": 29031939452,

           "processed_percent": 95,
           "success_count": 94,
           "fail_count": 1,
           "total": 100,
           "error_list": [
               {
                   "im_name": "image_1",
                   "error_code": 201,
                   "error_message": "Could not download the image from im_url."
               }
           ],
           "error_page": 1,
           "error_limit": 10,
       }
   ]
}


 

Check the detail of inserting error information

 

“fail_count” indicates the number of images failed to be indexed at the time when the api is called, while “error_list” contains a list of detailed error information associate with each failed image. Error list supports pagination. Developers can request the error list by providing the pagination 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.

 

 

Three new error codes and corresponding descriptive error messages are added to help user understand why images are not inserted successfully. This error list advises the follow-up procedures for developers - check the validity of the image url or prepare images with required format and dimension for uploading:


201
Could not download the image from im_url.
202
Unsupported image format.
203
Unsupported image dimension.


Sample JSON response of GET /insert/status/{transcation_id}


{
   "status": "OK",
   "method": "insert/status",

   "error": [],
   "result": [
       {
           "trans_id": 29031939452,

           "processed_percent": 95,
           "success_count": 92,
           "fail_count": 3,
           "total": 100,
           "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,
       }
   ]
}


To learn more about our visual search Data API, please refer to the API documentation.

Topics: Best practices