Image Recognition

Recognizes a known set of images in an image that you provide.

The Image Recognition API matches objects in an image that you provide against a database of objects.

The public dataset contains a library of images, such as corporate logos, which you can match against. When you submit an image to the API, IDOL OnDemand searches your image for sections that match the images in the database.

The API returns the name of the database object that was detected, some information about the object, and the location of the object in your image. The location is given as the coordinates of the corners of a box that surrounds the matching object.

For a list of file formats that you can use for image files, see Supported Image Formats.

For a list of corporate logos used in the training set for the API, see Corporate Logo Training Set.

Synchronous
https://api.idolondemand.com/1/api/sync/recognizeimages/v1
Asynchronous
https://api.idolondemand.com/1/api/async/recognizeimages/v1
Authentication

This API requires an authentication token to be supplied in the following parameter:

ParameterDescription
apikeyThe API key to use to authenticate the API request.
Input Source

This API accepts a single input source that can be supplied using one of the following parameters:

ParameterDescription
fileA file containing the image to process. Multi part POST only.
referenceAn IDOL OnDemand reference obtained from either the Expand Container or Store Object API. The corresponding image is passed to the API.
urlA publicly accessible HTTP URL from which the image can be retrieved.
Parameters

In addition to the above input source, this API accepts the following parameters:

NameTypeDescription
indexes
enum <indexes> The image database that contains the objects you want to recognize. Default value: corporatelogos
image_type
enum <image_type> Information about the image that you are submitting. Default value: complex_2d
match_image
array A list of unique names of images to match from the specified database.
All parameters for this API are optional.
Enumeration Types

This API's parameters use the enumerations described below:

indexes
The image database that contains the objects you want to recognize.
corporatelogos Corporate Logos
Corporate logos.
image_type
Information about the image that you are submitting.
simple Flat image, simple background
Your image is a flat, 2D image where the part you want to identify is the main object in the image.
complex_2d Flat image, complex background
Your image is flat, with a complex background around the object that you want to identify.
complex_3d Skewed/distorted image, complex background
Your image is not flat (that is, it is skewed or 3D), with a complex background around the object that you want to identify.

This API returns a JSON response that is described by the model below. This single model is presented both as an easy to read abstract definition and as the formal JSON schema.

Model
This is an abstract definition of the response that describes each of the properties that might be returned.
Image Recognition Response {
object (array[Object]) Details of a recognized object in the image.
}
Object {
unique_name (string) The unique name of the object recognized from the database.
name (string) The descriptive name of the recognized object.
db (enum<Db>) The name of the recognition database that the recognized object is stored in.
corners (array[Corners]) The positions of the corners of a quadrilateral bounding box containing the recognized object.
}
enum<Db> {
'corporatelogos' Corporate logos.
}
Corners {
x (integer) The horizontal position of the corner of the bounding box.
y (integer) The vertical position of the corner of the bounding box.
}
Model Schema
This is a JSON schema that describes the syntax of the response. See json-schema.org for a complete reference.
{
    "type": "object",
    "properties": {
        "object": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "unique_name": {
                        "type": "string"
                    },
                    "name": {
                        "type": "string"
                    },
                    "db": {
                        "enum": [
                            "corporatelogos"
                        ]
                    },
                    "corners": {
                        "type": "array",
                        "minItems": 1,
                        "items": {
                            "type": "object",
                            "properties": {
                                "x": {
                                    "type": "integer"
                                },
                                "y": {
                                    "type": "integer"
                                }
                            },
                            "required": [
                                "x",
                                "y"
                            ]
                        }
                    }
                },
                "required": [
                    "unique_name",
                    "name",
                    "db",
                    "corners"
                ]
            }
        }
    },
    "required": [
        "object"
    ]
}
https://api.idolondemand.com/1/api/sync/recognizeimages/v1
/developer/api/api-example/1/api/sync/recognizeimages/v1
Examples
See this API for yourself - select one of our examples below.
Input Source
ParameterValue
file
reference
url
Parameters
NameTypeValue
indexes
enum
image_type
enum
match_image
array
Add another value

ASync – Response An error occurred making the API request
Response Code:
Response Body

	

Making API Request…
Checking result of job

To try this API with your own data and use it in your own applications, you need an API Key. You can create an API Key from your account page - API Keys.

Output Refresh An error occurred making the API request View the raw output View Input
Rendered RawHtml Response
Result Display
Response Code:
Response Body:

		
Make this call with curl
curl


If you would like to provide us with more information then please use the box below:

We will use your submission to help improve our product.