Request parameters

Sample request

Sample POST request using cURL:

curl -F "img=@image.jpg;type=image/jpg" -F "api_key=API_KEY" \
    -F "api_sig=SIGNATURE" -F "time_stamp=20090612111832" \
    http://api.iqengines.com/v1.2/query/

Return values

A successful request to the Query API will result in a response of the following format:

{
    'data': {
        'error': 0
    }
}

Webhook

If you have specified a webhook URI in your Query API request, we will use it to post the results as soon as we have identified your image’s visual content. For instance, if you have sent us an image that has been associated the a qid QID, and IQ Engines’ image recognition engine has extracted the labels “Diet Coke” from the image, the results is a JSON encoded string

{
    "api_key": "API_KEY",
    "qid": "QID",
    "qid_data": {
         "color": "Mostly red gray.",
         "labels": "Diet Coke"
    }
}

If you specified an extra argument (e.g. “hello world”) in your Query API request, the extra parameter is also part of the response

{
    "api_key": "API_KEY",
    "extra": "hello world";
    "qid": "QID",
    "qid_data": {
        "color": "Mostly red gray.",
        "labels": "Diet Coke"
    }
}

The initial stage of the image recognition engine is to determine whether there is a match between your image and one of the images in our database of labeled images. This step is done automatically using computer vision. If you have your own dataset of labeled images you can use the Training API to search against your images as well. If we detect a match we also return additional information such as the bounding box of the region where we detected the object in your image (bbox), the object identification (obj_id), and the object metadata (meta). The metadata may contain additional information such as the product SKU. If you use the Training API, then you can provide your own metadata.

{
    "api_key": "API_KEY",
    "extra": "hello world";
    "qid": "QID",
    "qid_data": {
        "bbox": [0, 2, 315, 209],
        "color": "Mostly red gray.",
        "labels": "Diet Coke"
        "meta": {},
        "obj_id": "OBJ_ID"
    }
}

If you would like to practice using the Webhook service but don’t want to setup a webserver to process the results quite yet, we recommend that you use the excellent Postbin service: http://www.postbin.org/. You can obtain a URL in no time, use it as your webhook parameter, and then visualize the results!

Multiple Object Matches

Our image recognition engine has the ability to detect several objects in an image. By default, the response is only comprised of the strongest match. If you want the ability to retrieve all the objects that are identified, then you can pass the optional argument multiple_results in your Query API request. The qid_data field in the response becomes a list of all the objects that are present in your image. For instance, if we detect in your image a can of diet coke, and a can of orangina, then the response looks like

{
  "api_key": "API_KEY",
  "qid": "QID",
  "qid_data": [
    {
      "bbox": [34, 10, 162, 221],
      "color": "Mostly red gray, with some yellow.",
      "labels": "Diet Coke",
      "meta": {},
      "obj_id": "OBJ_ID1"
    },
    {
      "bbox": [12, 92, 174, 108],
      "color": "Mostly red gray, with some yellow.",
      "labels": "Orangina",
      "meta": {},
      "obj_id": "OBJ_ID2"
    }
  ]
}