Object Recognition

Recognizes a known set of corporate logos within target media.

The Object Recognition API matches logos in a media file that you provide against a database of corporate logos.

The public dataset contains a library of corporate logos, which you can match against. When you submit a media file to the API, Haven OnDemand searches your media for sections that match the logos in the database.

The API returns the name of the logo in the database that was detected (based on the stock ticker for the company that owns the logo), and the location of the object in your media. 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 media files, see Supported Media Formats.

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

The Object Recognition API can be expanded to match objects from other datasets. If you are interested in using this functionality with other datasets, please contact us

Quick Start

You can upload a media file to the API as a file, in which case you must use a POST method.

curl -X POST http://api.havenondemand.com/1/api/async/recognizeobjects/v1 --form "file=@hpe.mp4"

You can also input a URL or a Haven OnDemand object store reference.

If you provide a URL, it must link directly to a media file. You cannot link to a page with an embedded media (such as a news page or YouTube link).

http://api.havenondemand.com/1/api/async/recognizeobjects/v1?url=https://www.havenondemand.com/sample-content/videos/hpe.mp4

You can provide an image or video in many common formats. For a full list of supported media formats, see Supported Media Formats.

Note: Because input files for this API can be large and take a long time to process, the API runs only in asynchronous mode. See Get the Results.

Note: This API has rate and duration limits:

  • Input files are truncated after 1 minute.
  • The processing terminates after two hours and returns only what it has completed within that time.

For more information, see Rate Limiting, Quotas, Data Expiry, and Maximums.

Get the Results

The asynchronous mode returns a job-id, which you can then use to extract your results. There are two methods for this:

  • Use /1/job/status/ to get the status of the job, including results if the job is finished.
  • Use /1/job/result/, which waits until the job has finished and then returns the result.

    Note: Because /result has to wait for the job to finish before it can return a response, using it for longer operations such as processing a large video file can result in an HTTP request timeout response. The /result method returns a response either when the result is available, or after 120 seconds, whichever is sooner. If the job is not complete after 120 seconds, the /result method returns a code 7010 (job result request timeout) response. This means that your asynchronous job is still in progress. To avoid the timeout, use /status instead.

Results

The results contain position coordinates for recognized objects, these are relative to the upper left corner of the frame and are expressed in pixels (unless the source is a PDF where the units are expressed as points).

When the input is a video, the results contain time information. The time information is in seconds (milliseconds appear as a decimal, for example 3.5).


"items": [
{
    "object_identity": {
        "name": "Hewlett Packard Enterprise",
        "confidence": 99
    },
	"source_region_coordinates": [
		{
			"x": 42,
			"y": 11,
			"unit": "pixels"
		},
		{
			"x": 307,
			"y": 7,
			"unit": "pixels"
		},
		{
			"x": 306,
			"y": 189,
			"unit": "pixels"
		},
		{
			"x": 44,
			"y": 182,
			"unit": "pixels"
		}
	],
	"start_time_offset": 0.067,
	"end_time_offset": 2.139,
	"time_offset": 0.067
}, {
    "object_identity": {
    "name": "Amphenol Corporation",
    "confidence": 20
    },
    "source_region_coordinates": [
    {
    "x": 51,
    "y": 112,
    "unit": "pixels"
    },
    {
    "x": 164,
    "y": 99,
    "unit": "pixels"
    },
    {
    "x": 177,
    "y": 151,
    "unit": "pixels"
    },
    {
    "x": 62,
    "y": 142,
    "unit": "pixels"
    }
    ],
    "start_time_offset": 2.106,
    "end_time_offset": 2.139,
    "time_offset": 2.106
    }
}]

Filter Out Unwanted Responses

You can specify a minimum confidence score, to exclude objects with lower confidence values from the results. For example:

http://api.havenondemand.com/1/api/async/recognizeobjects/v1?url=https://www.havenondemand.com/sample-content/videos/hpe.mp4&minimum_confidence=80

{
"items": [
{
    "object_identity": {
        "name": "Hewlett Packard Enterprise",
        "confidence": 99
    },
	"source_region_coordinates": [
		{
			"x": 42,
			"y": 11,
			"unit": "pixels"
		},
		{
			"x": 307,
			"y": 7,
			"unit": "pixels"
		},
		{
			"x": 306,
			"y": 189,
			"unit": "pixels"
		},
		{
			"x": 44,
			"y": 182,
			"unit": "pixels"
		}
	],
	"start_time_offset": 0.067,
	"end_time_offset": 2.139,
	"time_offset": 0.067
}]
Asynchronous
https://api.havenondemand.com/1/api/async/recognizeobjects/v1

This API supports only asynchronous invocation.

Authentication

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

Parameter Description
apikey The API key to use to authenticate the API request.
Parameters

This API accepts the following parameters:

Required
Name Type Description
file
binary A media file that contains the objects to recognize. Multipart POST only.
reference
string A Haven OnDemand reference obtained from either the Expand Container or Store Object API. The corresponding document is passed to the API.
url
string A publicly accessible HTTP URL from which the image can be retrieved.
Optional
Name Type Description
minimum_confidence
integer The minimum confidence value (0-100) that each result returned must have. Default value: 50.

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.

Asynchronous Use

Additional requests are required to get the result if this API is invoked asynchronously.

You can use /1/job/status/<job-id> to get the status of the job, including results if the job is finished.

You can also use /1/job/result/<job-id>, which waits until the job has finished and then returns the result.

Model
This is an abstract definition of the response that describes each of the properties that might be returned.
Object Recognition Response {
source_information ( Source_information , optional) Metadata information about a media file
items ( array[Items] ) An array of recognized objects.
}
Object Recognition Response:Source_information {
mime_type ( string ) MIME type of the document.
video_information ( Video_information , optional) Information about the video track if one is present.
audio_information ( Audio_information , optional) Information about the audio track if one is present.
image_information ( Image_information , optional) Information about the image track if one is present.
document_information ( Document_information , optional) Information about the document track. This is only available if the source media is a multi-page image, presentation file, or PDF.
}
Object Recognition Response:Source_information:Video_information {
width ( integer ) The width of the video in pixels.
height ( integer ) The height of the video in pixels.
codec ( string ) The algorithm used to encode the video.
pixel_aspect_ratio ( string ) The aspect ratio of pixels in the video. For example, if the video is made up of square pixels this value is 1:1.
}
Object Recognition Response:Source_information:Audio_information {
codec ( string ) The algorithm used to encode the audio.
sample_rate ( integer ) The frequency at which the audio was sampled.
channels ( integer ) The number of channels present in the audio. For example, for stereo this value is 2.
}
Object Recognition Response:Source_information:Image_information {
width ( integer ) The width of the image in pixels.
height ( integer ) The height of the image in pixels.
}
Object Recognition Response:Source_information:Document_information {
page_count ( integer ) The estimated number of pages in the document.
}
Object Recognition Response:Items {
start_time_offset ( number , optional) Time from the start of the video to where the object first appears. This value is expressed as a non integer number. This is only available if the source media is a video.
end_time_offset ( number , optional) Time from the start of the video to where the object is no longer visible. This value is expressed as a non integer number. This is only available if the source media is a video.
time_offset ( number , optional) Time offset from the start of the video to where the object was detected. This value is expressed as a non integer number. This is only available if the source media is a video.
page ( integer , optional) The page (1-based index) in the document where the object is located. This is only available if the source media is a multi-page image, presentation file, or PDF.
source_region_coordinates ( array[Source_region_coordinates] ) An array of coordinates (relative to the top left of the source) that represents the bounding region where the object can be found. If the source media is a video then this region is where the object was found at time_offset in the input source.
object_identity ( Object_identity ) An identity match for the object.
}
Object Recognition Response:Items:Source_region_coordinates {
x ( integer ) The horizontal co-ordinate that makes up part of a region.
y ( integer ) The vertical co-ordinate that makes up part of a region.
unit ( enum<Unit> ) The unit in which x and y are expressed.
}
enum<Object Recognition Response:Items:Source_region_coordinates:Unit> {
'pixels' Pixels.
'points' Points in the PDF co-ordinate system.
}
Object Recognition Response:Items:Object_identity {
name ( string ) The name of the identified object.
confidence ( number ) A value (0-100) of confidence for the identified object.
}
Model Schema
This is a JSON schema that describes the syntax of the response. See json-schema.org for a complete reference.
{
    "properties": {
        "source_information": {
            "properties": {
                "mime_type": {
                    "type": "string"
                },
                "video_information": {
                    "properties": {
                        "width": {
                            "type": "integer",
                            "minimum": 1
                        },
                        "height": {
                            "type": "integer",
                            "minimum": 1
                        },
                        "codec": {
                            "type": "string"
                        },
                        "pixel_aspect_ratio": {
                            "type": "string"
                        }
                    },
                    "type": "object",
                    "required": [
                        "width",
                        "height",
                        "codec",
                        "pixel_aspect_ratio"
                    ]
                },
                "audio_information": {
                    "properties": {
                        "codec": {
                            "type": "string"
                        },
                        "sample_rate": {
                            "type": "integer"
                        },
                        "channels": {
                            "type": "integer"
                        }
                    },
                    "type": "object",
                    "required": [
                        "codec",
                        "sample_rate",
                        "channels"
                    ]
                },
                "image_information": {
                    "properties": {
                        "width": {
                            "type": "integer",
                            "minimum": 1
                        },
                        "height": {
                            "type": "integer",
                            "minimum": 1
                        }
                    },
                    "type": "object",
                    "required": [
                        "width",
                        "height"
                    ]
                },
                "document_information": {
                    "properties": {
                        "page_count": {
                            "type": "integer"
                        }
                    },
                    "type": "object",
                    "required": [
                        "page_count"
                    ]
                }
            },
            "required": [
                "mime_type"
            ],
            "type": "object"
        },
        "items": {
            "items": {
                "properties": {
                    "start_time_offset": {
                        "type": "number",
                        "minimum": 0
                    },
                    "end_time_offset": {
                        "type": "number",
                        "minimum": 0
                    },
                    "time_offset": {
                        "type": "number",
                        "minimum": 0
                    },
                    "page": {
                        "type": "integer",
                        "minimum": 1
                    },
                    "source_region_coordinates": {
                        "items": {
                            "properties": {
                                "x": {
                                    "type": "integer",
                                    "minimum": 0
                                },
                                "y": {
                                    "type": "integer",
                                    "minimum": 0
                                },
                                "unit": {
                                    "enum": [
                                        "pixels",
                                        "points"
                                    ]
                                }
                            },
                            "required": [
                                "x",
                                "y",
                                "unit"
                            ],
                            "type": "object"
                        },
                        "minItems": 3,
                        "type": "array"
                    },
                    "object_identity": {
                        "properties": {
                            "name": {
                                "type": "string"
                            },
                            "confidence": {
                                "type": "number",
                                "minimum": 0,
                                "maximum": 100
                            }
                        },
                        "required": [
                            "name",
                            "confidence"
                        ],
                        "type": "object"
                    }
                },
                "required": [
                    "object_identity",
                    "source_region_coordinates"
                ],
                "type": "object"
            },
            "type": "array"
        }
    },
    "required": [
        "items"
    ],
    "type": "object"
}
https://api.havenondemand.com/1/api/async/recognizeobjects/v1
/api/api-example/1/api/async/recognizeobjects/v1
Examples
See this API for yourself - select one of our examples below.
Parameters
Required
Select file Change Remove
Optional
Name Type Value
minimum_confidence
integer

Note: This API will be invoked asynchronously.



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 Input
Rendered RawHtml Response
Result Display
Response Code:
Response Body:

			
Make this call with 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.