Image Recognition

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

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

Quick Start

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

The following example uses a POST request to analyze the image in the specified file for logos.

curl -X POST https://api.havenondemand.com/1/api/sync/recognizeimages/v1 --form "image_type=complex_3d" --form "file=@aviva.jpg"

The API returns the name of the logo in the database that was detected, 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.

{
  "object": [
    {
      "name": "Aviva plc",
      "unique_name": "AV",
      "db": "corporatelogos",
      "confidence": 89,
      "corners": [
        {
          "x": 38,
          "y": 60
        },
        {
          "x": 298,
          "y": 58
        },
        {
          "x": 317,
          "y": 215
        },
        {
          "x": 23,
          "y": 217
        }
      ]
    }
  ]
}

For a list of file formats that you can use for image 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 Image Recognition API can be expanded to match objects from other data sets. If you are interested in using this functionality with other data sets, please contact us.

Synchronous
https://api.havenondemand.com/1/api/sync/recognizeimages/v1
Asynchronous
https://api.havenondemand.com/1/api/async/recognizeimages/v1
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 The image file to process.
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
image_type
enum Information about the image that you are submitting. Default value: complex_2d.
indexes
enum The image database that contains the objects that you want to recognize. See Corporate Logo Training Set. Default value: corporatelogos.
match_image
array<string> A list of unique names of images to match from the specified database.
Enumeration Types

This API's parameters use the enumerations described below:

image_type
Information about the image that you are submitting.
simple Flat image, simple background
Your image is a flat, 2D image where the object that 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.
indexes
The image database that contains the objects that you want to recognize.
corporatelogos Corporate Logos
A data set that contains logos for over 750 companies.

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.
Image Recognition Response {
object ( array[Object] ) Details of a recognized object in the image.
page_count ( integer , optional) The total number of pages in the document.
}
Image Recognition Response:Object {
corners ( array[Corners] ) The positions of the corners of a quadrilateral bounding box containing the recognized object.
db ( enum<Db> ) The name of the recognition database that the recognized object is stored in.
name ( string ) The name of the recognized logo.
unique_name ( string ) The unique name of the logo recognized from the database.
confidence ( number ) Confidence score (0-100) for the recognized logo
page_num ( integer , optional) The page in the document that the object was found on.
}
enum<Image Recognition Response:Object:Db> {
'corporatelogos' Corporate logos.
}
Image Recognition Response:Object: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.
{
    "properties": {
        "object": {
            "items": {
                "properties": {
                    "corners": {
                        "items": {
                            "properties": {
                                "x": {
                                    "type": "integer"
                                },
                                "y": {
                                    "type": "integer"
                                }
                            },
                            "required": [
                                "x",
                                "y"
                            ],
                            "type": "object"
                        },
                        "minItems": 1,
                        "type": "array"
                    },
                    "db": {
                        "enum": [
                            "corporatelogos"
                        ]
                    },
                    "name": {
                        "type": "string"
                    },
                    "unique_name": {
                        "type": "string"
                    },
                    "confidence": {
                        "type": "number"
                    },
                    "page_num": {
                        "type": "integer"
                    }
                },
                "required": [
                    "unique_name",
                    "name",
                    "db",
                    "corners",
                    "confidence"
                ],
                "type": "object"
            },
            "type": "array"
        },
        "page_count": {
            "type": "integer"
        }
    },
    "required": [
        "object"
    ],
    "type": "object"
}
https://api.havenondemand.com/1/api/sync/recognizeimages/v1
/api/api-example/1/api/sync/recognizeimages/v1
Examples
See this API for yourself - select one of our examples below.
Parameters
Required
Select file Change Remove
Optional
Name Type Value
image_type
enum
indexes
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 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.