Quick search

The Update API

The Update API is a long polling request that returns a list of results for all your images that have been successfully processed by the IQ Engines image recognition engine. The Update API times out after 90 seconds. Hence you can maintain an Update API request between your client and the IQ Engines image recognition engine to retrieve the results of your Query API requests. It is particularly useful in the context of mobile applications where the results cannot be posted to the device using a webhook. Note that the Update API will return the results for a Query API request only once. However, you can always access the results for a Query API request using the Result API.

The URL pattern for the Update API is:

http://api.iqengines.com/v1.2/update/

Please note, any client implementation of this api-call should be able to gracefully handle http redirects

Request parameters

required

api_key: Your API key.

api_sig: The signature of the API call, see Authentication.

time_stamp: The time stamp for your request. The formatting is ‘YYYYmmDDHHMMSS’ (e.g. ‘20100405224038’), and the standard is UTC time.

api_key:	Your API key.
api_sig:	The signature of the API call, see Authentication.
time_stamp:	The time stamp for your request. The formatting is ‘YYYYmmDDHHMMSS’ (e.g. ‘20100405224038’), and the standard is UTC time.

optional

device_id: The unique identification of the device that is querying the API. If you are using the API on multiple mobile devices, you should pass the device_id as a parameter to the Query API and Update API. This ensures that the Update API returns only results corresponding to image queries sent by the device.

json: If this parameter is not empty, the results are in the JSON format, otherwise the results are in the XML format.

device_id:	The unique identification of the device that is querying the API. If you are using the API on multiple mobile devices, you should pass the device_id as a parameter to the Query API and Update API. This ensures that the Update API returns only results corresponding to image queries sent by the device.
json:	If this parameter is not empty, the results are in the JSON format, otherwise the results are in the XML format.

Sample request

Sample POST request using cURL:

curl -d "api_key=API_KEY&api_sig=SIGNATURE&time_stamp=20090612111832&json=1" \
    http://api.iqengines.com/v1.2/update/

Return values

Let’s consider the example where there are the results are available for two Query API requests corresponding to QID1 and QID2. The first query has been labeled “Diet Coke”, and the second request has been matched to an image of an Orangina can in the IQ Engines image database. The sample response is:

{
    'data': {
        'error': 0,
        'results': [
            {
                'qid': 'QID1',
                'qid_data': {
                    'color': 'Mostly red gray.',
                    'labels': 'Diet Coke',
                }
            },
            {
                'extra': '"hello world"',
                'qid': 'QID2',
                'qid_data': {
                    'bbox': [0, 2, 315, 209],
                    'color': 'Mostly yellow blue.',
                    'labels': 'Orangina',
                    'meta': {},
                    'obj_id': 'OBJ_ID'
                }
            }
        ]
    }
}

If you have passed the multiple_results argument in your Query API request, then a sample response in the scenario described in the context of webhook results is:

{
    'data': {
        'error': 0,
        'results': [
            {
                'qid': '12114360a674b17b48e9302ad4a79c6f44ef6548',
                'qid_data': [
                    {
                        'bbox': [11, 9, 185, 234],
                        'color': 'Mostly red gray, with some yellow.',
                        'labels': 'Diet Coke',
                        'meta': {},
                        'obj_id': 'OBJ_ID1'
                    },
                    {
                        'bbox': [12, 86, 179, 158],
                        'color': 'Mostly red gray, with some yellow.',
                        'labels': 'Orangina',
                        'meta': {},
                        'obj_id': 'OBJ_ID2'}
                ]
            }
        ]
    }
}

The API flow

We illustrate here three scenarios that show how the Query and Update APIs are used in practice.

The simplest scenario is one where the client first issues a Query API to post an image to our server, then issues an update API that returns the QID along with the labels once the image is successfully processed. The API flow is illustrated below.

The time taken by the IQ Engines labeling engine to extract labels in an image is variable. In some cases when the image is particularly complex, the processing time can be longer than the Update API time out. To ensure that the client can retrieve the result as soon as the image is processed, the recommended behavior is to issue another Update API call right after it times out. The corresponding API flow is illustrated below.

In the third scenario, we illustrate a case where the results are not obtained in the order that they have been queried. The QID(s) of the successfully processed images will be returned by the update API call. The client then uses these QIDs to issue result API requests. The API flow is illustrated below.

API Documentation Version 1.2

API Reference