Cloud API Documentation
 Back to top

Recognition API - Face and Vehicle

Core Concepts

OBJECT

Objects are items that can be recognized by the API. Currently the API supports Objects with a type of Person, Vehicle, or Licenseplate, and future updates may include additional types. This document will use the names Object, Person, and Person Object interchangeably. Note that recognition of the Vehicle and Licenseplate object types are special cases addressed in the Vehicle Recognition section below.

IMAGE

Images play an important role in the Recognition API. For every Person Object that a developer creates, one or more Images of that Person should be uploaded to the system. Increased recognition accuracy can be achieved by uploading a wide variety of photos of the Person with their face turned in different directions and tilted in multiple angles.

GROUP

Groups can be thought of as categories that contain one or more Person Objects. Each Group has an ID, chosen by the developer, which is typically a friendly name for the Group (Friends, Employees, etc.). All recognition requests require that a Group be specified.

TRAINING

Training is a computer vision term that relates to the process of converting the features and metadata found in the Images into mathematical models that are used for recognition.

Introduction to Face Recognition

There are only three steps needed to start using the Recognition API: upload Images of a Person, assign that Person to a Group, and train the Group.

The first step is to upload one or more Images of a Person that should be recognized. When uploading the Images, a querystring parameter, objectID, is specified to create or associate the Image with a Person Object. To improve the accuracy of the Recognition API, multiple Images of the Person should be uploaded. The original source Images used will be securely archived by Sighthound to allow the developer to easily take advantage of new Recognition API features as they become available in the future.

After Images are uploaded for each Person, a Group needs to be created. A Group is a collection of Person Objects that helps categorize and filter the people for recognition requests (Friends, Employees, Celebrities, etc.). Each account can have unlimited Groups, and each Group can contain an unlimited number of Objects. Objects can be assigned to more than one Group.

The final step in preparing the Recognition API for use is to call the training endpoint for the Group. When Objects are added, edited, or removed from a Group, a call must be made to the Group Training endpoint before the Recognition API can use the new data.

Before proceeding, please ensure you have created a Sighthound Cloud API Token.

Usage Notes

API Base URL

Select the appropriate base URL for your environment and Cloud API account level. All Cloud accounts can use the free, development service for up to 5,000 API calls per month. Paid accounts (Basic, Pro, and Enterprise) have access to separate, production-ready servers.

  • Development: https://dev.sighthoundapi.com

  • Production (Paid Accounts): https://prod.sighthoundapi.com

General

  • Blurry scenes (possibly caused by camera settings or weather conditions) will reduce the accuracy of Object recognition.

  • Good lighting conditions are important for recognition, and accuracy will be impacted if the scene is too dark.

  • The angle of the camera to the object being recognized should be within 45 degrees for best results.

Face Recognition and Authentication

  • Performing face recognition or authentication on an image will return a name (objectId) for every face detected, including those of unknown people. You must use each face’s recognitionConfidence score to determine whether the returned name should be considered as correct. Confidence scores greater than 0.5 are fairly confident the name is right, whereas lower values are typically unknowns and should be handled as such.

  • Authentication is similar to performing a recognition on a group trained with just one object. Another way, Authentication is a shortcut to recognition of a particular person (or objectId) because group training is not a required step.

  • The faces in an image should be at least 100x100 pixels for good results, and higher resolutions improve recognition accuracy.

  • The system will handle faces occluded up to approximately 50%, given that the eyes are not occluded. Eyes in the Image are essential for reliable detection.

  • The system is able to handle frontal faces with a high degree of accuracy. Profile and rotated faces (maximum of 60 degrees, both in-plane and out-of-plane) are handled but are less accurate.

  • Wearable objects (e.g. glasses, cap, hat) should not cause problems as long as more than 50% of the face is visible, especially if several Images of the subject wearing the items are uploaded.

Image Management

Upload Images

Uploading multiple, high-quality, Images of the people to be recognized increases the accuracy of the system, and photos showing the faces in different angles should be used. A query string parameter, objectId, associates the Image with a Person Object. When uploading an Image of a Person for the first time, a new Person Object will be created using the objectId chosen by the developer. This objectId is typically the Person’s name or an identifier that correlates to a record in the developer’s own database. The original source Images used for enrollment will be securely archived by Sighthound to allow the developer to easily take advantage of new Recognition API features as they become available in the future.

Notes

  • Upload images that contain only one Person. If multiple people are found, the system will only use the largest face.

  • Supported image formats are JPEG, GIF, and PNG.

  • Images larger than 1920x1080 will be scaled to a size within those bounds while respecting aspect ratio.

  • The minimum size supported for detection of a face in the image is 40x40 pixels. For better results, use faces sized 100x100 pixels or higher.

  • IDs cannot start with underscore “_”, nor contain \n \r : \ | / ,

  • The max length for imageId and objectId is 128 characters.

  • IDs are case sensitive.

  • IDs must be unique across all Images in the developer’s account.

  • An image may not be uploaded with a previously used ID. To replace an imageId, first Delete the image.

  • An Object can be associated with up to 10,000 Images.

There are currently two ways to upload Images to the service: one uses a URL that points to an Image hosted on the internet, and the other allows for direct upload of an Image file:

Using Image URL
PUT/v1/image/{imageId}?objectId={objectId}&objectType=person&train=manual

Example URI

PUT https://dev.sighthoundapi.com/v1/image/imageId?objectId=id1&objectType=person&train=manual
URI Parameters
HideShow
imageId
string (required) 

Developer chosen, unique ID for the Image. URL encoded.

objectId
string (required) Example: id1

For a new Object, this is a developer chosen unique ID for the Object. For existing Objects, this is the ID used when the Object was created. URL encoded. A new Object will only be created if the objectType is detected in the uploaded photo.

objectType
string (required) 

The type of Object in the Image. Currently, “person” is the only option.

train
string (required) 

Specifies whether training will automatically happen after the Image is uploaded or that the Group Training endpoint must be called manually. Manual is the only available option at this time.

Request

Request Body Attributes (JSON)

  • image (string): A fully qualified path to an Image or a Base64 encoding of the Image.
Headers
Content-Type: application/json
X-Access-Token: developersOwnCloudAccessToken
Body
{
  "image": "http://www.example.com/path/to/image.jpg"
}
Response  200

Response Attributes (JSON)

  • image (object): Size and rotation information from original source Image

    • width (integer): Pixel width of source Image
    • height (integer): Pixel height of source Image
    • orientation (integer): EXIF code representing rotation and/or flipping of source Image needed to align the source photo with the detection coordinates. Only applicable for photos with EXIF data (e.g., photos taken on a mobile device). Defaults to 1 (no rotation or flip), else the value found in the image’s EXIF data and indicates that bounding vertices have been translated to match that coordinate space.
  • imageId (string): The unique, developer assigned, ID for the Image

  • objects (array): An array of Objects detected in the Image and their associated attributes. An empty array means no Objects were detected.

    • objectId (string): Unique, developer-generated, ID for the Object
    • objectType (string): The type of Object. Currently “person” is the only supported type
    • faceAnnotation (array): A list of objects that contain detection coordinates, confidence scores, and other attributes
      • bounding (object):
        • vertices (array): A list of objects that define coordinates of the vertices that surround the Object
          • x (integer): Horizontal pixel position of the vertex
          • y (integer): Vertical pixel position of the vertex
      • recognitionConfidence (decimal): A decimal value between 0.0 - 1.0 that represents the confidence that the given objectId is actually the Object recognized in the image.
      • attributes (object): describes attributes of the detected Object
        • system (object): System-generated attributes for the detected Object
          • frontal (boolean): Frontal is true if the face is looking at camera and false if it’s a profile view.
  • requestId (string): A server generated ID for the request

Headers
Content-Type: application/json
Body
{
  "image": {
    "width": 4752,
    "height": 3168,
    "orientation": 1
  },
  "imageId": "26121dc0-a8fa-11e5-a192-b7286ac1d828",
  "objects": [
    {
      "objectId": "John Doe",
      "objectType": "person",
      "faceAnnotation": {
        "bounding": {
          "vertices": [
            {
              "x": 88,
              "y": 67
            },
            {
              "x": 288,
              "y": 67
            },
            {
              "x": 288,
              "y": 267
            },
            {
              "x": 88,
              "y": 267
            }
          ]
        },
        "attributes": {
          "system": {
            "frontal": false
          }
        }
      }
    }
  ],
  "requestId": "807ed538577545da97516e8681c0d985"
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
    "error": "ERROR_MEDIA_DATA",
    "reason": "Content corrupt",
    "reasonCode": 40001
}

{
    "error": "ERROR_MEDIA_DATA",
    "reason": "Chunked data corrupt",
    "reasonCode": 40002
}

{
    "error": "ERROR_MEDIA_DATA",
    "reason": "Content data corrupt",
    "reasonCode": 40003
}

{
    "error": "ERROR_MEDIA_DATA",
    "reason": "Cannot identify image format",
    "reasonCode": 40012,
    "details": {
          "statusCode": 406,
          "statusMessage": "Cannot identify image format",
          "body": "image error cannot identify image file (-6)"
         }
}

{
    "error": "ERROR_MEDIA_DATA",
    "reason": "Contain unacceptable objectId:<wrong objectId>",
    "reasonCode": 40020
}

{
    "error":"ERROR_MEDIA_DATA",
    "reason":"Unknown enroll process parameter",
    "reasonCode":40030
}

{
    "error":"ERROR_MEDIA_DATA",
    "reason":"Duplicate imageId: <imageId>",
    "reasonCode":40033
}

From Image File
PUT/v1/image/{imageId}?objectId={objectId}&objectType=person&train=manual

Example URI

PUT https://dev.sighthoundapi.com/v1/image/imageId?objectId=id2&objectType=person&train=manual
URI Parameters
HideShow
imageId
string (required) 

Developer chosen, unique ID for the Image. URL encoded.

objectId
string (required) Example: id2

For a new Object, this is a developer chosen unique ID for the Object. For existing Objects, this is the ID used when the Object was created. URL encoded. A new Object will only be created if the objectType is detected in the uploaded photo.

objectType
string (required) 

The type of Object in the Image. Currently, “person” is the only option.

train
string (required) 

Specifies whether training will automatically happen after the Image is uploaded or that the Group Training endpoint must be called manually. Manual is the only available option at this time.

Request

Request Body Attributes

  • Binary Stream of an image file to upload
Headers
Content-Type: application/octet-stream
X-Access-Token: developersOwnCloudAccessToken
Body
< Image binary stream >
Response  200

Response Attributes (JSON)

  • image (object): Size and rotation information from original source Image

    • width (integer): Pixel width of source Image
    • height (integer): Pixel height of source Image
    • orientation (integer): EXIF code representing rotation and/or flipping of source Image needed to align the source photo with the detection coordinates. Only applicable for photos with EXIF data (e.g., photos taken on a mobile device). Defaults to 1 (no rotation or flip), else the value found in the image’s EXIF data and indicates that bounding vertices have been translated to match that coordinate space.
  • imageId (string): The unique, developer assigned, ID for the Image

  • objects (array): An array of Objects detected in the Image and their associated attributes. An empty array means no Objects were detected.

    • objectId (string): Unique, developer-generated, ID for the Object
    • objectType (string): The type of Object. Currently “person” is the only supported type
    • faceAnnotation (array): A list of objects that contain detection coordinates, confidence scores, and other attributes
      • bounding (object):
        • vertices (array): A list of objects that define coordinates of the vertices that surround the Object
          • x (integer): Horizontal pixel position of the vertex
          • y (integer): Vertical pixel position of the vertex
      • recognitionConfidence (decimal): A decimal value between 0.0 - 1.0 that represents the confidence that the given objectId is actually the Object recognized in the image.
      • attributes (object): describes attributes of the detected Object
        • system (object): System-generated attributes for the detected Object
          • frontal (boolean): Frontal is true if the face is looking at camera and false if it’s a profile view.
  • requestId (string): A server generated ID for the request

Headers
Content-Type: application/json
Body
{
  "image": {
    "width": 4752,
    "height": 3168,
    "orientation": 1
  },
  "imageId": "26121dc0-a8fa-11e5-a192-b7286ac1d828",
  "objects": [
    {
      "objectId": "John Doe",
      "objectType": "person",
      "faceAnnotation": {
        "bounding": {
          "vertices": [
            {
              "x": 88,
              "y": 67
            },
            {
              "x": 288,
              "y": 67
            },
            {
              "x": 288,
              "y": 267
            },
            {
              "x": 88,
              "y": 267
            }
          ]
        },
        "attributes": {
          "system": {
            "frontal": false
          }
        }
      }
    }
  ],
  "requestId": "807ed538577545da97516e8681c0d985"
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
    "error": "ERROR_MEDIA_DATA",
    "reason": "Content corrupt",
    "reasonCode": 40001
}

{
    "error": "ERROR_MEDIA_DATA",
    "reason": "Chunked data corrupt",
    "reasonCode": 40002
}

{
    "error": "ERROR_MEDIA_DATA",
    "reason": "Content data corrupt",
    "reasonCode": 40003
}

{
    "error": "ERROR_MEDIA_DATA",
    "reason": "Cannot identify image format",
    "reasonCode": 40012,
    "details": {
          "statusCode": 406,
          "statusMessage": "Cannot identify image format",
          "body": "image error cannot identify image file (-6)"
         }
}

{
    "error": "ERROR_MEDIA_DATA",
    "reason": "Contain unacceptable objectId:<wrong objectId>",
    "reasonCode": 40020
}

{
    "error":"ERROR_MEDIA_DATA",
    "reason":"Unknown enroll process parameter",
    "reasonCode":40030
}

{
    "error":"ERROR_MEDIA_DATA",
    "reason":"Duplicate imageId: <imageId>",
    "reasonCode":40033
}

Query an Image

Returns information for the specified imageId.

Query Image
GET/v1/image/{imageId}

Example URI

GET https://dev.sighthoundapi.com/v1/image/imageId
URI Parameters
HideShow
imageId
string (required) 

ID of the Image to return. URL encoded.

Request
Headers
Content-Type: application/json
X-Access-Token: developersOwnCloudAccessToken
Response  200

Response Attributes (JSON)

  • imageId (string): The unique, developer assigned, ID for the Image

  • timestamp (integer): Unix timestamp of when the Image was saved

Headers
Content-Type: application/json
Body
{
  "imageId": "id1",
  "timestamp": 1454796657
}
Response  404
HideShow

The provided imageId does not exist.

Response Attributes (JSON)

  • An empty object will be returned
Headers
Content-Type: application/json
Body
{}
Response  408
HideShow

An internal error occurred. Please try your request again.

Headers
Content-Type: application/json
Body
{
  "error": "ERROR_INTERNAL",
  "reason": "Unexpected internal error",
  "reasonCode": 40801
}

List All Images

Returns a paged list of details for all of the Images uploaded.

List All Images
GET/v1/image

Example URI

GET https://dev.sighthoundapi.com/v1/image
URI Parameters
HideShow
limit
integer (optional) Default: 25 

A developer can request more results be returned in a single response, but there is no guarantee requested limit will be honored and paging may still occur.

after
string (optional) Example: groupId25

When paging results, this is the imageId that is used as the starting point (exclusive) for the next page of records.

before
string (optional) Example: groupId100

When paging results, this is the imageId that is the ending point (exclusive) for the previous page of records.

Request
Headers
Content-Type: application/json
X-Access-Token: developersOwnCloudAccessToken
Response  200

Response Attributes (JSON)

  • images (array): An array of Images in the developer’s account

    • imageId (string): The unique, developer assigned, ID for the Image
    • timestamp (integer): Unix timestamp of when the Image was saved
  • paging (object): If paging is active, contains links to the previous and next results

    • previous (string): If more results are available before the current paging location, this contains the URL to call for the previous set of results. If there are no previous records, this property will not be returned.
    • next (string): If more results are available, this contains the URL to call for the next set of results. If there are no more results, this property will not be returned.
Headers
Content-Type: application/json
Body
{
    images: [
        {
            "imageId": "img1",
            "timestamp": 1454800572
       },
       {
            "imageId": "img2",
            "timestamp": 1454804172
        }
    ],
    "paging": {
            "previous": "https://<server>/v1/image?limit=50&amp;before=<imageId1>"
            "next": "https://<server>/v1/image?limit=50&amp;after=<imageId2>"
        }
    }
Response  404
HideShow

No Groups were found.

Response Attributes (JSON)

  • An empty object will be returned
Headers
Content-Type: application/json
Body
{}
Response  408
HideShow

An internal error occurred. Please try your request again.

Headers
Content-Type: application/json
Body
{
  "error": "ERROR_INTERNAL",
  "reason": "Unexpected internal error",
  "reasonCode": 40801
}

Delete an Image

Deletes an Image from the service. The Objects that were associated with the Image will not be deleted.

Delete an Image
DELETE/v1/image/{imageId}

Example URI

DELETE https://dev.sighthoundapi.com/v1/image/imageId
URI Parameters
HideShow
imageId
string (required) 

ID of the Image to delete. URL encoded.

Request
Headers
Content-Type: application/json
X-Access-Token: developersOwnCloudAccessToken
Response  204
Headers
Content-Type: application/json
Response  404
HideShow

The provided imageId does not exist.

Response Attributes (JSON)

  • An empty object will be returned
Headers
Content-Type: application/json
Body
{}
Response  408
HideShow

An internal error occurred. Please try your request again.

Headers
Content-Type: application/json
Body
{
  "error": "ERROR_INTERNAL",
  "reason": "Unexpected internal error",
  "reasonCode": 40801
}

Group Management

Create or Replace a Group

A new Group can be created using this endpoint, or an existing Group can have its contents replaced.

Notes

  • Group IDs cannot start with underscore “_”, nor contain \n \r : \ | / ,

  • There is currently a max length for IDs of 128 characters.

  • IDs are case sensitive.

  • IDs must be unique across Groups in the developer’s account.

Create/Replace a Group
PUT/v1/group/{groupId}

Example URI

PUT https://dev.sighthoundapi.com/v1/group/groupId
URI Parameters
HideShow
groupId
string (required) 

For a new Group, this is a developer chosen unique ID for the Group. For existing Groups, this is the ID of the Group to replace. URL encoded.

Request

Request Body Attributes (JSON)

  • objectIds (array): An array of objectId strings to include in the Group. If groupId does not already exist, it will be created and will include the objectIds. If groupId already exists, its contents will be fully replace with the given objectIds.
Headers
Content-Type: application/json
X-Access-Token: developersOwnCloudAccessToken
Body
{
  "objectIds": [
    "test1",
    "test2"
  ]
}
Response  200

Response Attributes (JSON)

  • groupId (string): The unique, developer assigned, ID strings for the Group

  • status (string): The Training status of the Group: “trained” means the group is ready to be used for recognition requests, “pending” means the Group Training endpoint should be called before using it for recognition requests.

  • objectIds (array): An array of objectId strings that are contained in the Group

Headers
Content-Type: application/json
Body
{
  "groupId": "group2",
  "status": "pending",
  "objectIds": [
    "test1",
    "test2"
  ]
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
    "error": "ERROR_MEDIA_DATA",
    "reason": "Content corrupt",
    "reasonCode": 40001
}

{
    "error": "ERROR_MEDIA_DATA",
    "reason": "Chunked data corrupt",
    "reasonCode": 40002
}

{
    "error": "ERROR_MEDIA_DATA",
    "reason": "Content data corrupt",
    "reasonCode": 40003
}

{
    "error": "ERROR_MEDIA_DATA",
    "reason": "Contain unacceptable groupId: <wrong groupId>",
    "reasonCode": 40022
}
Response  404
HideShow

The provided groupId does not exist.

Response Attributes (JSON)

  • An empty object will be returned
Headers
Content-Type: application/json
Body
{}
Response  408
HideShow

An internal error occurred. Please try your request again.

Headers
Content-Type: application/json
Body
{
  "error": "ERROR_INTERNAL",
  "reason": "Unexpected internal error",
  "reasonCode": 40801
}
Response  422
HideShow

The objectIds content was empty or wrong JSON data.

Headers
Content-Type: application/json
Body
{
  "error": "ERROR_UNPROCESSABLE",
  "reason": "objectIds array required",
  "reasonCode": 42210
}

List All Groups

Returns all Groups and includes their associated objectIds and training status.

List All Groups
GET/v1/group

Example URI

GET https://dev.sighthoundapi.com/v1/group
URI Parameters
HideShow
limit
integer (optional) Default: 25 

A developer can request more results be returned in a single response, but there is no guarantee requested limit will be honored and paging may still occur.

after
string (optional) Example: groupId25

When paging results, this is the groupId that is used as the starting point (exclusive) for the next page of records.

before
string (optional) Example: groupId100

When paging results, this is the groupId that is the ending point (exclusive) for the previous page of records.

Request
Headers
Content-Type: application/json
X-Access-Token: developersOwnCloudAccessToken
Response  200

Response Attributes (JSON)

  • groups (array): An array of Groups that exist in the developer’s account

    • groupId (string): The unique, developer assigned, ID strings for the Group
    • status (string): The Training status of the Group: “trained” means the group is ready to be used for recognition requests, “pending” means the Group Training endpoint should be called before using it for recognition requests.
    • objectIds (array): An array of objectId strings that are contained in the Group
  • paging (object): If paging is active, contains links to the previous and next results

    • previous (string): If more results are available before the current paging location, this contains the URL to call for the previous set of results. If there are no previous records, this property will not be returned.
    • next (string): If more results are available, this contains the URL to call for the next set of results. If there are no more results, this property will not be returned.
Headers
Content-Type: application/json
Body
{
    groups: [
        {
            "groupId":"group1",
            "status":"trained",
            "objectIds":[
                "test1",
                "test2",
                "test54"
            ]
       },
       {
            "groupId":"group2",
            "status":"pending",
            "objectIds":[
                "test1",
                "test2"
            ]
        }
    ],
    "paging": {
            "previous": "https://<server>/v1/group?limit=50&amp;before=<groupId1>"
            "next": "https://<server>/v1/group?limit=50&amp;after=<groupId2>"
        }
}
Response  404
HideShow

No Groups were found.

Response Attributes (JSON)

  • An empty object will be returned
Headers
Content-Type: application/json
Body
{}
Response  408
HideShow

An internal error occurred. Please try your request again.

Headers
Content-Type: application/json
Body
{
  "error": "ERROR_INTERNAL",
  "reason": "Unexpected internal error",
  "reasonCode": 40801
}

Get One Group

Returns the specified Group which includes objectIds contained in the Group and the training status.

Get Group
GET/v1/group/{groupId}

Example URI

GET https://dev.sighthoundapi.com/v1/group/groupId
URI Parameters
HideShow
groupId
string (required) 

ID of the Group to return. URL encoded.

Request
Headers
Content-Type: application/json
X-Access-Token: developersOwnCloudAccessToken
Response  200

Response Attributes (JSON)

  • groupId (string): The unique, developer assigned, ID strings for the Group

  • status (string): The Training status of the Group: “trained” means the group is ready to be used for recognition requests, “pending” means the Group Training endpoint should be called before using it for recognition requests.

  • objectIds (array): An array of objectId strings that are contained in the Group

Headers
Content-Type: application/json
Body
{
  "groupId": "group1",
  "status": "trained",
  "objectIds": [
    "test1",
    "test2",
    "test54"
  ]
}
Response  404
HideShow

The provided groupId does not exist.

Response Attributes (JSON)

  • An empty object will be returned
Headers
Content-Type: application/json
Body
{}
Response  408
HideShow

An internal error occurred. Please try your request again.

Headers
Content-Type: application/json
Body
{
  "error": "ERROR_INTERNAL",
  "reason": "Unexpected internal error",
  "reasonCode": 40801
}

Add Objects to a Group

Adds Objects to an existing Group.

Add Objects to Group
POST/v1/group/{groupId}

Example URI

POST https://dev.sighthoundapi.com/v1/group/groupId
URI Parameters
HideShow
groupId
string (required) 

ID of the Group to add Objects. URL encoded.

Request

Request Body Attributes (JSON)

  • objectIds (array): An array of objectId strings to add to an existing Group.
Headers
Content-Type: application/json
X-Access-Token: developersOwnCloudAccessToken
Body
{
  "objectIds": [
    "object 3",
    "object 4"
  ]
}
Response  200
Headers
Content-Type: application/json
Body
{
  "groupId": "group2",
  "status": "pending",
  "objectIds": [
    "object 1",
    "object 2",
    "object 3",
    "object 4"
  ]
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
    "error": "ERROR_MEDIA_DATA",
    "reason": "Content corrupt",
    "reasonCode": 40001
}

{
    "error": "ERROR_MEDIA_DATA",
    "reason": "Chunked data corrupt",
    "reasonCode": 40002
}

{
    "error": "ERROR_MEDIA_DATA",
    "reason": "Content data corrupt",
    "reasonCode": 40003
}

{
    "error": "ERROR_MEDIA_DATA",
    "reason": "Contain unacceptable objectId: <wrong objectId>",
    "reasonCode": 40022
}
Response  404
HideShow

The provided groupId does not exist.

Response Attributes (JSON)

  • An empty object will be returned
Headers
Content-Type: application/json
Body
{}
Response  408
HideShow

An internal error occurred. Please try your request again.

Headers
Content-Type: application/json
Body
{
  "error": "ERROR_INTERNAL",
  "reason": "Unexpected internal error",
  "reasonCode": 40801
}
Response  422
HideShow

The objectIds content was empty or wrong JSON data.

Headers
Content-Type: application/json
Body
{
  "error": "ERROR_UNPROCESSABLE",
  "reason": "objectIds array required",
  "reasonCode": 42210
}
Response  422
HideShow

One or more of the objectIds provided does not exist.

Headers
Content-Type: application/json
Body
{
  "error": "ERROR_UNPROCESSABLE",
  "reason": "Nonexist objectId(s):<list of objectIds>",
  "reasonCode": 42212
}

Remove Objects From a Group

Removes Objects from a Group.

Remove Objects From Group
DELETE/v1/group/{groupId}

Example URI

DELETE https://dev.sighthoundapi.com/v1/group/groupId
URI Parameters
HideShow
groupId
string (required) 

ID of the Group to remove Objects from. URL encoded.

Request

Request Body Attributes (JSON)

  • objectIds (array): An array of objectId strings to remove from a Group.
Headers
Content-Type: application/json
X-Access-Token: developersOwnCloudAccessToken
Body
{
  "objectIds": [
    "test3",
    "test4"
  ]
}
Response  204
Headers
Content-Type: application/json
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
    "error": "ERROR_MEDIA_DATA",
    "reason": "Content corrupt",
    "reasonCode": 40001
}

{
    "error": "ERROR_MEDIA_DATA",
    "reason": "Chunked data corrupt",
    "reasonCode": 40002
}

{
    "error": "ERROR_MEDIA_DATA",
    "reason": "Content data corrupt",
    "reasonCode": 40003
}

{
    "error": "ERROR_MEDIA_DATA",
    "reason": "Contain unacceptable objectId: <wrong objectId>",
    "reasonCode": 40022
}
Response  404
HideShow

The provided groupId does not exist.

Response Attributes (JSON)

  • An empty object will be returned
Headers
Content-Type: application/json
Body
{}
Response  408
HideShow

An internal error occurred. Please try your request again.

Headers
Content-Type: application/json
Body
{
  "error": "ERROR_INTERNAL",
  "reason": "Unexpected internal error",
  "reasonCode": 40801
}
Response  422
HideShow

The objectIds content was empty or wrong JSON data.

Headers
Content-Type: application/json
Body
{
  "error": "ERROR_UNPROCESSABLE",
  "reason": "objectIds array required",
  "reasonCode": 42210
}
Response  422
HideShow

One or more of the objectIds provided does not exist.

Headers
Content-Type: application/json
Body
{
  "error": "ERROR_UNPROCESSABLE",
  "reason": "Nonexist objectId(s):<list of objectIds>",
  "reasonCode": 42212
}

Delete a Group

Deletes a Group from the service. The Objects that were members of the Group will not be deleted.

Delete a Group
DELETE/v1/group/{groupId}/all

Example URI

DELETE https://dev.sighthoundapi.com/v1/group/groupId/all
URI Parameters
HideShow
groupId
string (required) 

ID of the Group to delete. URL encoded.

Request
Headers
Content-Type: application/json
X-Access-Token: developersOwnCloudAccessToken
Response  204
Headers
Content-Type: application/json
Response  404
HideShow

The provided groupId does not exist.

Response Attributes (JSON)

  • An empty object will be returned
Headers
Content-Type: application/json
Body
{}
Response  408
HideShow

An internal error occurred. Please try your request again.

Headers
Content-Type: application/json
Body
{
  "error": "ERROR_INTERNAL",
  "reason": "Unexpected internal error",
  "reasonCode": 40801
}

Train the Group

Trains the Group so it can be used for recognition requests. NOTE: This is a synchronous request that can take a few seconds (or a few minutes) to complete based on how many Images are in the Objects and Group.

Train Group
POST/v1/group/{groupId}/training

Example URI

POST https://dev.sighthoundapi.com/v1/group/groupId/training
URI Parameters
HideShow
groupId
string (required) 

ID of the Group to train for recognition use. URL encoded.

Request
Headers
X-Access-Token: developersOwnCloudAccessToken
Response  200

Response Attributes (JSON)

  • groupId (string): The unique, developer assigned, ID strings for the Group

  • status (string): The Training status of the Group: “trained” means the group is ready to be used for recognition requests, “pending” means the Group Training endpoint should be called before using it for recognition requests.

  • objectIds (array): An array of objectId strings that are contained in the Group

Headers
Content-Type: application/json
Body
{
  "groupId": "group1",
  "status": "trained",
  "objectIds": [
    "test1",
    "test2"
  ]
}
Response  404
HideShow

The provided groupId does not exist.

Response Attributes (JSON)

  • An empty object will be returned
Headers
Content-Type: application/json
Body
{}
Response  408
HideShow

An internal error occurred. Please try your request again.

Headers
Content-Type: application/json
Body
{
  "error": "ERROR_INTERNAL",
  "reason": "Unexpected internal error",
  "reasonCode": 40801
}

Object Management

Get an Object

Returns the requested Object.

Get Object
GET/v1/object/{objectId}

Example URI

GET https://dev.sighthoundapi.com/v1/object/objectId
URI Parameters
HideShow
objectId
string (required) 

ID of the Object to return. URL encoded.

Request
Headers
Content-Type: application/json
X-Access-Token: developersOwnCloudAccessToken
Response  200

Response Attributes (JSON)

  • objectId (string): The unique, developer assigned, ID for the Object

  • objectType (string): The type of Object. “person” is the only available option.

  • imageIds (array): An array of imageId strings that correlate to the Object

Headers
Content-Type: application/json
Body
{  
    "objectId":"obj1",
    "objectType: "person",
    "imageIds":[  
        "image1",
        "image2"
    ]
}
Response  404
HideShow

The provided objectId does not exist.

Response Attributes (JSON)

  • An empty object will be returned
Headers
Content-Type: application/json
Body
{}
Response  408
HideShow

An internal error occurred. Please try your request again.

Headers
Content-Type: application/json
Body
{
  "error": "ERROR_INTERNAL",
  "reason": "Unexpected internal error",
  "reasonCode": 40801
}

List All Objects

Returns a paged list of all Objects.

List All Objects
GET/v1/object

Example URI

GET https://dev.sighthoundapi.com/v1/object
URI Parameters
HideShow
limit
integer (optional) Default: 25 

A developer can request more results be returned in a single response, but there is no guarantee requested limit will be honored and paging may still occur.

after
string (optional) Example: groupId25

When paging results, this is the objectId that is used as the starting point (exclusive) for the next page of records.

before
string (optional) Example: groupId100

When paging results, this is the objectId that is the ending point (exclusive) for the previous page of records.

Request
Headers
Content-Type: application/json
X-Access-Token: developersOwnCloudAccessToken
Response  200

Response Attributes (JSON)

  • objects (array): An array of Objects that exist in the developer’s account

    • objectId (string): The unique, developer assigned, ID for the Object
    • imageIds (array): An array of imageId strings that correlate to the Object
  • paging (object): If paging is active, contains links to the previous and next results

    • previous (string): If more results are available before the current paging location, this contains the URL to call for the previous set of results. If there are no previous records, this property will not be returned.
    • next (string): If more results are available, this contains the URL to call for the next set of results. If there are no more results, this property will not be returned.
Headers
Content-Type: application/json
Body
{
   "objects":[  
        {  
            "objectId":"obj1",
            "imageIds":[  
                "image1",
                "image2"
            ]
        },
        {  
            "objectId":"obj2",
            "imageIds":[  
                "image3",
                "image4"
            ]
        }
    ],
    "paging": {
            "previous": "https://<server>/v1/object?limit=50&amp;before=<objectId1>"
            "next": "https://<server>/v1/object?limit=50&amp;after=<objectId2>"
    }
}
Response  404
HideShow

No Objects were found.

Response Attributes (JSON)

  • An empty object will be returned
Headers
Content-Type: application/json
Body
{}
Response  408
HideShow

An internal error occurred. Please try your request again.

Headers
Content-Type: application/json
Body
{
  "error": "ERROR_INTERNAL",
  "reason": "Unexpected internal error",
  "reasonCode": 40801
}

Remove an Image from an Object

Disassociates an Image from an Object. The Image is not deleted.

Remove Image From Object
DELETE/v1/object/{objectId}/image/{imageId}

Example URI

DELETE https://dev.sighthoundapi.com/v1/object/objectId/image/imageId
URI Parameters
HideShow
objectId
string (required) 

ID of the Object from which to remove the Image. URL encoded.

imageId
string (required) 

ID of the Image to remove from the Object. URL encoded.

Request
Headers
Content-Type: application/json
X-Access-Token: developersOwnCloudAccessToken
Response  204
Headers
Content-Type: application/json
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "ERROR_MEDIA_DATA",
  "reason": "Contain unacceptable objectId: <wrong objectId>",
  "reasonCode": 40022
}
Response  404
HideShow

The provided objectId or imageId does not exist.

Response Attributes (JSON)

  • An empty object will be returned
Headers
Content-Type: application/json
Body
{}
Response  408
HideShow

An internal error occurred. Please try your request again.

Headers
Content-Type: application/json
Body
{
  "error": "ERROR_INTERNAL",
  "reason": "Unexpected internal error",
  "reasonCode": 40801
}

List Groups of an Object

Returns all Groups associated with a given objectId.

List Groups of an Object
GET/v1/object/{objectId}/group

Example URI

GET https://dev.sighthoundapi.com/v1/object/objectId/group
URI Parameters
HideShow
objectId
string (required) 

ID of the Object. URL encoded.

limit
integer (optional) Default: 25 

A developer can request more results be returned in a single response, but there is no guarantee requested limit will be honored and paging may still occur.

after
string (optional) Example: groupId25

When paging results, this is the groupId that is used as the starting point (exclusive) for the next page of records.

before
string (optional) Example: groupId100

When paging results, this is the groupId that is the ending point (exclusive) for the previous page of records.

Request
Headers
Content-Type: application/json
X-Access-Token: developersOwnCloudAccessToken
Response  200

Response Attributes (JSON)

  • groups (array): An array of Groups that the Object is contained in

    • groupId (string): The unique, developer assigned, ID strings for the Group
    • status (string): The Training status of the Group: “trained” means the group is ready to be used for recognition requests, “pending” means the Group Training endpoint should be called before using it for recognition requests.
  • paging (object): If paging is active, contains links to the previous and next results

    • previous (string): If more results are available before the current paging location, this contains the URL to call for the previous set of results. If there are no previous records, this property will not be returned.
    • next (string): If more results are available, this contains the URL to call for the next set of results. If there are no more results, this property will not be returned.
Headers
Content-Type: application/json
Body
{
    groups: [
        {
            "groupId":"group1",
            "status":"trained",
       },
       {
            "groupId":"group2",
            "status":"pending",
        }
    ],
    "paging": {
            "previous": "https://<server>/v1/object/{objectId}/group?limit=50&amp;before=<groupId1>"
            "next": "https://<server>/v1/object/{objectId}/group?limit=50&amp;after=<groupId2>"
        }
}

Delete an Object

Deletes an Object from the service. The Images and Groups that were associated with the Object will not be deleted.

Delete an Object
DELETE/v1/object/{objectId}

Example URI

DELETE https://dev.sighthoundapi.com/v1/object/objectId
URI Parameters
HideShow
objectId
string (required) 

ID of the Object to delete. URL encoded.

Request
Headers
Content-Type: application/json
X-Access-Token: developersOwnCloudAccessToken
Response  204
Headers
Content-Type: application/json
Response  404
HideShow

The provided objectId does not exist.

Response Attributes (JSON)

  • An empty object will be returned
Headers
Content-Type: application/json
Body
{}
Response  408
HideShow

An internal error occurred. Please try your request again.

Headers
Content-Type: application/json
Body
{
  "error": "ERROR_INTERNAL",
  "reason": "Unexpected internal error",
  "reasonCode": 40801
}

Recognition

Perform Recognition

Performs face recognition on all of the faces detected in a submitted Image. One groupId is required to be specified in the request and only the Object IDs contained within the Group will be matched and returned. If no Group is specified, an error will be returned.

Important: Performing face recognition on an image will return a name (objectId) for every face detected, including those of unknown people. You must use each face’s recognitionConfidence score to determine whether the returned name should be considered as correct. Confidence scores greater than 0.5 are fairly confident the name is right, whereas lower values are typically unknowns and should be handled as such.

Using Image URL
POST/v1/recognition?groupId={groupId}

Example URI

POST https://dev.sighthoundapi.com/v1/recognition?groupId=friends
URI Parameters
HideShow
groupId
string (required) Example: friends

groupId containing the Objects that will be used for recognition. URL encoded.

Request

Request Body Attributes (JSON)

  • image (string): A fully qualified path to an image hosted on the internet to run recognition on
Headers
Content-Type: application/json
X-Access-Token: developersOwnCloudAccessToken
Body
{
  "image": "http://www.example.com/path/to/image.jpg"
}
Response  200

Response Attributes (JSON)

  • image (object): Size and rotation information of the provided image

    • width (integer): Pixel width of image
    • height (integer): Pixel height of image
    • orientation (integer): EXIF code representing rotation and/or flipping of source Image needed to align the source photo with the detection coordinates. Only applicable for photos with EXIF data (e.g., photos taken on a mobile device). Defaults to 1 (no rotation or flip), else the value found in the image’s EXIF data and indicates that bounding vertices have been translated to match that coordinate space.
  • objects (array): A list of objects recognized in the image

    • objectId (string): The objectId of the recognized object
    • objectType (string): The type of Object detected. “person” is currently the only option.
    • faceAnnotation (array): A list of objects that contain detection coordinates, confidence scores, and other attributes
      • bounding (object):
        • vertices (array): A list of objects that define coordinates of the vertices that surround the Object
          • x (integer): Horizontal pixel position of the vertex
          • y (integer): Vertical pixel position of the vertex
      • recognitionConfidence (decimal): A decimal value between 0.0 - 1.0 that represents the confidence that the given objectId is actually the Object recognized in the image.
      • attributes (object): describes attributes of the detected Object
        • system (object): System-generated attributes for the detected Object
          • frontal (boolean): Frontal is true if the face is looking at camera and false if it’s a profile view.
  • requestId (string): A server generated ID for the request

Headers
Content-Type: application/json
Body
{
    "image": { 
        "width":256, 
        "height":256, 
        "orientation":1 
    },
    "objects":
    [
        { 
            "objectId": "John Doe",
            "objectType": "person", 
            "faceAnnotation": {
                "bounding": {
                    "vertices": [
                        {"x": 38,"y": 17},
                        {"x": 238,"y": 17},
                        {"x": 238,"y": 217},
                        {"x": 38,"y": 217}
                    ]
                },
                "recognitionConfidence": 0.9812,
                "attributes": {
                    "system": {
                        "frontal": false
                    } 
                }
            }
        },
        { 
            "objectId": "Jane Doe",
            "objectType": "person", 
            "faceAnnotation": {
                "bounding": {
                    "vertices": [
                        {"x": 88,"y": 67},
                        {"x": 288,"y": 67},
                        {"x": 288,"y": 267},
                        {"x": 88,"y": 267}
                    ]
                },
                "recognitionConfidence": 0.9252,
                "attributes": {
                    "system": {
                        "frontal": false
                    } 
                }
            }
        },
    ],
    "requestId": "d80f1f5040284a34bd454d09fbb28c5f"
}

Uploading Image
POST/v1/recognition?groupId={groupId}

Example URI

POST https://dev.sighthoundapi.com/v1/recognition?groupId=friends
URI Parameters
HideShow
groupId
string (required) Example: friends

groupId containing the Objects that will be used for recognition. URL encoded.

Request

Request Body Attributes

  • Binary Stream of an image file to run recognition on
Headers
Content-Type: application/octet-stream
X-Access-Token: developersOwnCloudAccessToken
Body
< Image binary stream >
Response  200

Response Attributes (JSON)

  • image (object): Size and rotation information of the provided image

    • width (integer): Pixel width of image
    • height (integer): Pixel height of image
    • orientation (integer): EXIF code representing rotation and/or flipping of source Image needed to align the source photo with the detection coordinates. Only applicable for photos with EXIF data (e.g., photos taken on a mobile device). Defaults to 1 (no rotation or flip), else the value found in the image’s EXIF data and indicates that bounding vertices have been translated to match that coordinate space.
  • objects (array): A list of objects recognized in the image

    • objectId (string): The objectId of the recognized object
    • objectType (string): The type of Object detected. “person” is currently the only option.
    • faceAnnotation (array): A list of objects that contain detection coordinates, confidence scores, and other attributes
      • bounding (object):
        • vertices (array): A list of objects that define coordinates of the vertices that surround the Object
          • x (integer): Horizontal pixel position of the vertex
          • y (integer): Vertical pixel position of the vertex
      • recognitionConfidence (decimal): A decimal value between 0.0 - 1.0 that represents the confidence that the given objectId is actually the Object recognized in the image.
      • attributes (object): describes attributes of the detected Object
        • system (object): System-generated attributes for the detected Object
          • frontal (boolean): Frontal is true if the face is looking at camera and false if it’s a profile view.
  • requestId (string): A server generated ID for the request

Headers
Content-Type: application/json
Body
{
    "image": { 
        "width":256, 
        "height":256, 
        "orientation":1 
    },
    "objects":
    [
        { 
            "objectId": "John Doe",
            "objectType": "person", 
            "faceAnnotation": {
                "bounding": {
                    "vertices": [
                        {"x": 38,"y": 17},
                        {"x": 238,"y": 17},
                        {"x": 238,"y": 217},
                        {"x": 38,"y": 217}
                    ]
                },
                "recognitionConfidence": 0.9812,
                "attributes": {
                    "system": {
                        "frontal": false
                    } 
                }
            }
        },
        { 
            "objectId": "Jane Doe",
            "objectType": "person", 
            "faceAnnotation": {
                "bounding": {
                    "vertices": [
                        {"x": 88,"y": 67},
                        {"x": 288,"y": 67},
                        {"x": 288,"y": 267},
                        {"x": 88,"y": 267}
                    ]
                },
                "recognitionConfidence": 0.9252,
                "attributes": {
                    "system": {
                        "frontal": false
                    } 
                }
            }
        },
    ],
    "requestId": "d80f1f5040284a34bd454d09fbb28c5f"
}

Authentication

Perform Authentication

Performs face authentication on all of the faces detected in a submitted Image. This is similar to performing a recognition on a group trained with just one object. Another way, Authentication is a shortcut to recognition of a particular person (or objectId). One objectId is required to be specified in the request and only that objectId will be matched and returned. If no objectId is specified, an error will be returned. The objectIdID must correspond to at least one previously uploaded image.

Important: Performing authentication on an image will return a name (objectId) for every face detected, including those of unknown people. You must use each face’s recognitionConfidence score to determine whether the returned name should be considered as correct. Confidence scores greater than 0.5 are fairly confident the name is right, whereas lower values are typically unknowns and should be handled as such.

Using Image URL
POST/v1/recognition?objectId={objectId}

Example URI

POST https://dev.sighthoundapi.com/v1/recognition?objectId=id1
URI Parameters
HideShow
objectId
string (required) Example: id1

objectId used when the Object was created. URL encoded.

Request

Request Body Attributes (JSON)

  • image (string): A fully qualified path to an image hosted on the internet to run recognition on
Headers
Content-Type: application/json
X-Access-Token: developersOwnCloudAccessToken
Body
{
  "image": "http://www.example.com/path/to/image.jpg"
}
Response  200

Response Attributes (JSON)

  • image (object): Size and rotation information of the provided image

    • width (integer): Pixel width of image
    • height (integer): Pixel height of image
    • orientation (integer): EXIF code representing rotation and/or flipping of source Image needed to align the source photo with the detection coordinates. Only applicable for photos with EXIF data (e.g., photos taken on a mobile device). Defaults to 1 (no rotation or flip), else the value found in the image’s EXIF data and indicates that bounding vertices have been translated to match that coordinate space.
  • objects (array): A list of Objects recognized in the image (Just one Object in the case of authentication)

    • objectId (string): The objectId of the recognized object
    • objectType (string): The type of Object detected. “person” is currently the only option.
    • faceAnnotation (array): A list of objects that contain detection coordinates, confidence scores, and other attributes
      • bounding (object):
        • vertices (array): A list of objects that define coordinates of the vertices that surround the Object
          • x (integer): Horizontal pixel position of the vertex
          • y (integer): Vertical pixel position of the vertex
      • recognitionConfidence (decimal): A decimal value between 0.0 - 1.0 that represents the confidence that the given objectId is actually the Object recognized in the image.
      • attributes (object): describes attributes of the detected Object
        • system (object): System-generated attributes for the detected Object
          • frontal (boolean): Frontal is true if the face is looking at camera and false if it’s a profile view.
  • requestId (string): A server generated ID for the request

Headers
Content-Type: application/json
Body
{
    "image": { 
        "width":256, 
        "height":256, 
        "orientation":1 
    },
    "objects":
    [
        { 
            "objectId": "id1",
            "objectType": "person", 
            "faceAnnotation": {
                "bounding": {
                    "vertices": [
                        {"x": 38,"y": 17},
                        {"x": 238,"y": 17},
                        {"x": 238,"y": 217},
                        {"x": 38,"y": 217}
                    ]
                },
                "recognitionConfidence": 0.9812,
                "attributes": {
                    "system": {
                        "frontal": false
                    } 
                }
            }
        },
    ],
    "requestId": "d80f1f5040284a34bd454d09fbb28c5f"
}

Uploading Image
POST/v1/recognition?objectId={objectId}

Example URI

POST https://dev.sighthoundapi.com/v1/recognition?objectId=id1
URI Parameters
HideShow
objectId
string (required) Example: id1

objectId used when the Object was created. URL encoded.

Request

Request Body Attributes

  • Binary Stream of an image file to run recognition on
Headers
Content-Type: application/octet-stream
X-Access-Token: developersOwnCloudAccessToken
Body
< Image binary stream >
Response  200

Response Attributes (JSON)

  • image (object): Size and rotation information of the provided image

    • width (integer): Pixel width of image
    • height (integer): Pixel height of image
    • orientation (integer): EXIF code representing rotation and/or flipping of source Image needed to align the source photo with the detection coordinates. Only applicable for photos with EXIF data (e.g., photos taken on a mobile device). Defaults to 1 (no rotation or flip), else the value found in the image’s EXIF data and indicates that bounding vertices have been translated to match that coordinate space.
  • objects (array): A list of Objects recognized in the image (Just one Object in the case of authentication)

    • objectId (string): The objectId of the recognized object
    • objectType (string): The type of Object detected. “person” is currently the only option.
    • faceAnnotation (array): A list of objects that contain detection coordinates, confidence scores, and other attributes
      • bounding (object):
        • vertices (array): A list of objects that define coordinates of the vertices that surround the Object
          • x (integer): Horizontal pixel position of the vertex
          • y (integer): Vertical pixel position of the vertex
      • recognitionConfidence (decimal): A decimal value between 0.0 - 1.0 that represents the confidence that the given objectId is actually the Object recognized in the image.
      • attributes (object): describes attributes of the detected Object
        • system (object): System-generated attributes for the detected Object
          • frontal (boolean): Frontal is true if the face is looking at camera and false if it’s a profile view.
  • requestId (string): A server generated ID for the request

Headers
Content-Type: application/json
Body
{
    "image": { 
        "width":256, 
        "height":256, 
        "orientation":1 
    },
    "objects":
    [
        { 
            "objectId": "id1",
            "objectType": "person", 
            "faceAnnotation": {
                "bounding": {
                    "vertices": [
                        {"x": 38,"y": 17},
                        {"x": 238,"y": 17},
                        {"x": 238,"y": 217},
                        {"x": 38,"y": 217}
                    ]
                },
                "recognitionConfidence": 0.9812,
                "attributes": {
                    "system": {
                        "frontal": false
                    } 
                }
            }
        },
    ],
    "requestId": "d80f1f5040284a34bd454d09fbb28c5f"
}

Vehicle Recognition

Perform Vehicle Recognition

Performs recognition on all of the vehicles detected in a submitted Image.

The objectType “vehicle” is required. Uploading of images for enrollment, Image Management, Group Management, and Object Management are not supported for Vehicle Recogniton.

The vehicles in an image should be at least 200 pixels wide for good results. For best recognition results, camera pitch angle should be less than 30 degrees. Frontal and rear vehicle views give better recognition results than side views.

Vehicle Recognition includes most North American passenger vehicle models built 1990 and later.

Using Image URL
POST/v1/recognition?objectType=vehicle

Example URI

POST https://dev.sighthoundapi.com/v1/recognition?objectType=vehicle
Request

Request Body Attributes (JSON)

  • image (string): A fully qualified path to an image hosted on the internet to run recognition on
Headers
Content-Type: application/json
X-Access-Token: developersOwnCloudAccessToken
Body
{
  "image": "http://www.example.com/path/to/image.jpg"
}
Response  200

Response Attributes (JSON)

  • image (object): Size and rotation information of the provided image

    • width (integer): Pixel width of image
    • height (integer): Pixel height of image
    • orientation (integer): EXIF code representing rotation and/or flipping of source Image needed to align the source photo with the detection coordinates. Only applicable for photos with EXIF data (e.g., photos taken on a mobile device). Defaults to 1 (no rotation or flip), else the value found in the image’s EXIF data and indicates that bounding vertices have been translated to match that coordinate space.
  • objects (array): A list of objects recognized in the image

    • objectType (string): The type of Object detected. The expected value is “vehicle”.
    • objectId (string): Unique identifier of the recognized object.
    • vehicleAnnotation (object): A list of objects that contain detection coordinates, confidence scores, and other attributes
      • bounding (object):
        • vertices (array): A list of objects that define coordinates of the vertices that surround the Object
          • x (integer): Horizontal pixel position of the vertex
          • y (integer): Vertical pixel position of the vertex
      • recognitionConfidence (decimal): A decimal value between 0.0 - 1.0 that represents the confidence that the given objectId is actually the Object recognized in the image.
      • attributes (object):
        • system (object): System-generated attributes for the detected Object
          • make (object): List of attributes for the vehicle make (e.g. “BMW” or “Toyota”)
            • name (string): The name for the parent field
            • confidence (float): Confidence that the name field is correct
          • model (object): List of attributes for the vehicle model (e.g. “3 Series” or “Tacoma”)
            • name (string): The name for the parent field
            • confidence (float): Confidence that the name field is correct
          • color (object): List of attributes for the vehicle color (e.g. “blue” or “silver/grey”)
            • name (string): The name for the parent field
            • confidence (float): Confidence that the name field is correct
          • vehicleType (string): Vehicle body type (e.g. “car”, “truck”, “suv”, “motorcycle”, “bus”)
  • requestId (string): A server generated ID for the request

Headers
Content-Type: application/json
Body
{
  "image": {
    "width": 2016,
    "orientation": 1,
    "height": 1512
  },
  "objects": [
    {
      "vehicleAnnotation": {
        "bounding": {
          "vertices": [
            {
              "y": 512,
              "x": 78
            },
            {
              "y": 512,
              "x": 2016
            },
            {
              "y": 1184,
              "x": 2016
            },
            {
              "y": 1184,
              "x": 78
            }
          ]
        },
        "attributes": {
          "system": {
            "color": {
              "confidence": 0.9968,
              "name": "silver/grey"
            },
            "make": {
              "confidence": 0.8508,
              "name": "BMW"
            },
            "model": {
              "confidence": 0.8508,
              "name": "3 Series"
            },
            "vehicleType": "car"
          }
        },
        "recognitionConfidence": 0.8508
      },
      "objectId": "_vehicle_f3c3d26b-c568-4d98-b6db-b96659fd7766",
      "objectType": "vehicle"
    }
  ],
  "requestId": "d25b5e5d22f6431498065e9a25134d59"
}

Uploading Image
POST/v1/recognition?objectType=vehicle

Example URI

POST https://dev.sighthoundapi.com/v1/recognition?objectType=vehicle
Request

Request Body Attributes

  • Binary Stream of an image file to run recognition on
Headers
Content-Type: application/octet-stream
X-Access-Token: developersOwnCloudAccessToken
Body
< Image binary stream >
Response  200

Response Attributes (JSON)

  • image (object): Size and rotation information of the provided image

    • width (integer): Pixel width of image
    • height (integer): Pixel height of image
    • orientation (integer): EXIF code representing rotation and/or flipping of source Image needed to align the source photo with the detection coordinates. Only applicable for photos with EXIF data (e.g., photos taken on a mobile device). Defaults to 1 (no rotation or flip), else the value found in the image’s EXIF data and indicates that bounding vertices have been translated to match that coordinate space.
  • objects (array): A list of objects recognized in the image

    • objectType (string): The type of Object detected. The expected value is “vehicle”.
    • objectId (string): Unique identifier of the recognized object.
    • vehicleAnnotation (object): A list of objects that contain detection coordinates, confidence scores, and other attributes
      • bounding (object):
        • vertices (array): A list of objects that define coordinates of the vertices that surround the Object
          • x (integer): Horizontal pixel position of the vertex
          • y (integer): Vertical pixel position of the vertex
      • recognitionConfidence (decimal): A decimal value between 0.0 - 1.0 that represents the confidence that the given objectId is actually the Object recognized in the image.
      • attributes (object):
        • system (object): System-generated attributes for the detected Object
          • make (object): List of attributes for the vehicle make (e.g. “BMW” or “Toyota”)
            • name (string): The name for the parent field
            • confidence (float): Confidence that the name field is correct
          • model (object): List of attributes for the vehicle model (e.g. “3 Series” or “Tacoma”)
            • name (string): The name for the parent field
            • confidence (float): Confidence that the name field is correct
          • color (object): List of attributes for the vehicle color (e.g. “blue” or “silver/grey”)
            • name (string): The name for the parent field
            • confidence (float): Confidence that the name field is correct
          • vehicleType (string): Vehicle body type (e.g. “car”, “truck”, “suv”, “motorcycle”, “bus”)
  • requestId (string): A server generated ID for the request

Headers
Content-Type: application/json
Body
{
  "image": {
    "width": 2016,
    "orientation": 1,
    "height": 1512
  },
  "objects": [
    {
      "vehicleAnnotation": {
        "bounding": {
          "vertices": [
            {
              "y": 512,
              "x": 78
            },
            {
              "y": 512,
              "x": 2016
            },
            {
              "y": 1184,
              "x": 2016
            },
            {
              "y": 1184,
              "x": 78
            }
          ]
        },
        "attributes": {
          "system": {
            "color": {
              "confidence": 0.9968,
              "name": "silver/grey"
            },
            "make": {
              "confidence": 0.8508,
              "name": "BMW"
            },
            "model": {
              "confidence": 0.8508,
              "name": "3 Series"
            },
            "vehicleType": "car"
          }
        },
        "recognitionConfidence": 0.8508
      },
      "objectId": "_vehicle_f3c3d26b-c568-4d98-b6db-b96659fd7766",
      "objectType": "vehicle"
    }
  ],
  "requestId": "d25b5e5d22f6431498065e9a25134d59"
}

Vehicle and License Plate Recognition

Performs recognition on all of the vehicles and their associated license plates detected in a submitted Image. This is similar to the above Vehicle Recognition, but also includes License Plate detection and recognition and pairing with Vehicles. This operation can be noticeably slower than Vehicle Recogntion alone. When License Plates are paired with Vehicles, any detected Vehicle that does not have an associated License Plate will be more closely examined for a missed license plate.

The paired objectType “vehicle,licenseplate” is required. Uploading of images for enrollment, Image Management, Group Management, and Object Management are not supported for Vehicle and License Plate Recogniton.

The vehicles in an image should be at least 200 pixels wide, and license plates in an image should be at least 80 pixels high for good results.

License plate character recognition is limited in its ability to find and recognize all characters. The response does not indicate whether any characters may have been missed. For example, a response including a string of “CCC24” could be for a license plate containing any or other of these variations: “CCC243”, “0CCC24”, “CCC124”. The confidence for the string is derived from the confidence for each individual character, so the confidence value also does not indicate missed characters.

Using Image URL
POST/v1/recognition?objectType=vehicle,licenseplate

Example URI

POST https://dev.sighthoundapi.com/v1/recognition?objectType=vehicle,licenseplate
Request

Request Body Attributes (JSON)

  • image (string): A fully qualified path to an image hosted on the internet to run recognition on
Headers
Content-Type: application/json
X-Access-Token: developersOwnCloudAccessToken
Body
{
  "image": "http://www.example.com/path/to/image.jpg"
}
Response  200

Response Attributes (JSON)

  • image (object): Size and rotation information of the provided image

    • width (integer): Pixel width of image
    • height (integer): Pixel height of image
    • orientation (integer): EXIF code representing rotation and/or flipping of source Image needed to align the source photo with the detection coordinates. Only applicable for photos with EXIF data (e.g., photos taken on a mobile device). Defaults to 1 (no rotation or flip), else the value found in the image’s EXIF data and indicates that bounding vertices have been translated to match that coordinate space.
  • objects (array): A list of objects recognized in the image

    • objectType (string): The type of Object detected. The expected value is “vehicle”.
    • objectId (string): Unique identifier of the recognized object.
    • vehicleAnnotation (object): A list of objects that contain detection coordinates, confidence scores, and other attributes
      • bounding (object):
        • vertices (array): A list of objects that define coordinates of the vertices that surround the Object
          • x (integer): Horizontal pixel position of the vertex
          • y (integer): Vertical pixel position of the vertex
      • recognitionConfidence (decimal): A decimal value between 0.0 - 1.0 that represents the confidence that the given objectId is actually the Object recognized in the image.
      • attributes (object):
        • system (object): System-generated attributes for the detected Object
          • make (object): List of attributes for the vehicle make (e.g. “BMW” or “Toyota”)
            • name (string): The name for the parent field
            • confidence (float): Confidence that the name field is correct
          • model (object): List of attributes for the vehicle model (e.g. “3 Series” or “Tacoma”)
            • name (string): The name for the parent field
            • confidence (float): Confidence that the name field is correct
          • color (object): List of attributes for the vehicle color (e.g. “blue” or “silver/grey”)
            • name (string): The name for the parent field
            • confidence (float): Confidence that the name field is correct
          • vehicleType (string): Vehicle body type (e.g. “car”, “truck”, “suv”, “motorcycle”, “bus”)
      • licenseplate (object):
        • bounding (object):
          • vertices (array): A list of objects that define coordinates of the vertices that surround the Object
            • x (integer): Horizontal pixel position of the vertex
            • y (integer): Vertical pixel position of the vertex
        • attributes (object):
          • system (object): System-generated attributes for the detected Object
            • region (object): The country or state of the license plate
              • name (string): Country or state (e.g. “Florida” or “Germany”)
              • confidence (float): Confidence for the region
            • string (object): The license plate characters as a group
              • name (string): All characters in one string
              • confidence (float): Confidence for the string of characters
            • characters (array): List of attributes for each character recognized in the license plate
              • bounding (object):
                • vertices (array): A list of objects that define coordinates of the vertices that surround the Object
                  • x (integer): Horizontal pixel position of the vertex
                  • y (integer): Vertical pixel position of the vertex
              • index (integer): The index of this character within the string of license plate characters
              • confidence (float): Confidence that the character field is correct
              • character (string): The character
  • requestId (string): A server generated ID for the request

Headers
Content-Type: application/json
Body
{
    "image": { 
    "width":2016,
    "orientation":1,
    "height":1512
},
"objects":[  
    {  
        "vehicleAnnotation":{  
            "bounding":{  
                "vertices":[  
                    {  "x":430, "y":286 },
                    {  "x":835, "y":286 },
                    {  "x":835, "y":559 },
                    {  "x":430, "y":559 }
                ]
            },
            "attributes":{  
            "system":{  
                "color":{  
                    "confidence":0.9968,
                    "name":"silver/grey"
                },
                "make":{  
                    "confidence":0.8508,
                    "name":"BMW"
                },
                "model":{  
                    "confidence":0.8508,
                    "name":"3 Series"
                },
                "vehicleType":"car"
            }
            },
            "recognitionConfidence":0.8508
            "licenseplate":{
                "bounding":{
                    "vertices":[
                        { "x":617, "y":452 },
                        { "x":743, "y":452 },
                        { "x":743, "y":482 },
                        { "x":617, "y":482 }
                    ]
                },
                "attributes":{
                    "system":{
                        "region":{
                            "name":"Florida",
                            "confidence":0.9994
                        },
                        "string":{
                            "name":"RTB2",
                            "confidence":0.999
                        },
                        "characters":[
                            {
                                "bounding":{
                                    "vertices":[
                                        { "y":455, "x":637 },
                                        { "y":455, "x":649 },
                                        { "y":473, "x":649 },
                                        { "y":473, "x":637 }
                                    ]
                                },
                                "index":0,
                                "confidence":0.9999,
                                "character":"R"
                            },
                            {
                                "bounding":{
                                    "vertices":[
                                        { "y":455, "x":648 },
                                        { "y":455, "x":661 },
                                        { "y":473, "x":661 },
                                        { "y":473, "x":648 }
                                    ]
                                },
                                "index":1,
                                "confidence":0.9999,
                                "character":"T"
                            },
                            {
                                "bounding":{  
                                    "vertices":[  
                                        { "y":455, "x":671 },
                                        { "y":455, "x":684 },
                                        { "y":474, "x":684 },
                                        { "y":474, "x":671 }
                                    ]
                                },
                                "index":2,
                                "confidence":0.9996,
                                "character":"B"
                            },
                            {
                                "bounding":{
                                    "vertices":[
                                        { "y":456, "x":683 },
                                        { "y":456, "x":696 },
                                        { "y":474, "x":696 },
                                        { "y":474, "x":683 }
                                    ]
                                },
                                "index":3,
                                "confidence":0.9995,
                                "character":"2"
                            }
                        ]
                    }
                }
            },
        },
        "objectId":"_vehicle_f3c3d26b-c568-4d98-b6db-b96659fd7766",
        "objectType":"vehicle"
    }
],
"requestId":"d25b5e5d22f6431498065e9a25134d59"
}

Uploading Image
POST/v1/recognition?objectType=vehicle,licenseplate

Example URI

POST https://dev.sighthoundapi.com/v1/recognition?objectType=vehicle,licenseplate
Request

Request Body Attributes

  • Binary Stream of an image file to run recognition on
Headers
Content-Type: application/octet-stream
X-Access-Token: developersOwnCloudAccessToken
Body
< Image binary stream >
Response  200

Response Attributes (JSON)

  • image (object): Size and rotation information of the provided image

    • width (integer): Pixel width of image
    • height (integer): Pixel height of image
    • orientation (integer): EXIF code representing rotation and/or flipping of source Image needed to align the source photo with the detection coordinates. Only applicable for photos with EXIF data (e.g., photos taken on a mobile device). Defaults to 1 (no rotation or flip), else the value found in the image’s EXIF data and indicates that bounding vertices have been translated to match that coordinate space.
  • objects (array): A list of objects recognized in the image

    • objectType (string): The type of Object detected. The expected value is “vehicle”.
    • objectId (string): Unique identifier of the recognized object.
    • vehicleAnnotation (object): A list of objects that contain detection coordinates, confidence scores, and other attributes
      • bounding (object):
        • vertices (array): A list of objects that define coordinates of the vertices that surround the Object
          • x (integer): Horizontal pixel position of the vertex
          • y (integer): Vertical pixel position of the vertex
      • recognitionConfidence (decimal): A decimal value between 0.0 - 1.0 that represents the confidence that the given objectId is actually the Object recognized in the image.
      • attributes (object):
        • system (object): System-generated attributes for the detected Object
          • make (object): List of attributes for the vehicle make (e.g. “BMW” or “Toyota”)
            • name (string): The name for the parent field
            • confidence (float): Confidence that the name field is correct
          • model (object): List of attributes for the vehicle model (e.g. “3 Series” or “Tacoma”)
            • name (string): The name for the parent field
            • confidence (float): Confidence that the name field is correct
          • color (object): List of attributes for the vehicle color (e.g. “blue” or “silver/grey”)
            • name (string): The name for the parent field
            • confidence (float): Confidence that the name field is correct
          • vehicleType (string): Vehicle body type (e.g. “car”, “truck”, “suv”, “motorcycle”, “bus”)
      • licenseplate (object):
        • bounding (object):
          • vertices (array): A list of objects that define coordinates of the vertices that surround the Object
            • x (integer): Horizontal pixel position of the vertex
            • y (integer): Vertical pixel position of the vertex
        • attributes (object):
          • system (object): System-generated attributes for the detected Object
            • region (object): The country or state of the license plate
              • name (string): Country or state (e.g. “Florida” or “Germany”)
              • confidence (float): Confidence for the region
            • string (object): The license plate characters as a group
              • name (string): All characters in one string
              • confidence (float): Confidence for the string of characters
            • characters (array): List of attributes for each character recognized in the license plate
              • bounding (object):
                • vertices (array): A list of objects that define coordinates of the vertices that surround the Object
                  • x (integer): Horizontal pixel position of the vertex
                  • y (integer): Vertical pixel position of the vertex
              • index (integer): The index of this character within the string of license plate characters
              • confidence (float): Confidence that the character field is correct
              • character (string): The character
  • requestId (string): A server generated ID for the request

Headers
Content-Type: application/json
Body
{
    "image": { 
    "width":2016,
    "orientation":1,
    "height":1512
},
"objects":[  
    {  
        "vehicleAnnotation":{  
            "bounding":{  
                "vertices":[  
                    {  "x":430, "y":286 },
                    {  "x":835, "y":286 },
                    {  "x":835, "y":559 },
                    {  "x":430, "y":559 }
                ]
            },
            "attributes":{  
            "system":{  
                "color":{  
                    "confidence":0.9968,
                    "name":"silver/grey"
                },
                "make":{  
                    "confidence":0.8508,
                    "name":"BMW"
                },
                "model":{  
                    "confidence":0.8508,
                    "name":"3 Series"
                },
                "vehicleType":"car"
            }
            },
            "recognitionConfidence":0.8508
            "licenseplate":{
                "bounding":{
                    "vertices":[
                        { "x":617, "y":452 },
                        { "x":743, "y":452 },
                        { "x":743, "y":482 },
                        { "x":617, "y":482 }
                    ]
                },
                "attributes":{
                    "system":{
                        "region":{
                            "name":"Florida",
                            "confidence":0.9994
                        },
                        "string":{
                            "name":"RTB2",
                            "confidence":0.999
                        },
                        "characters":[
                            {
                                "bounding":{
                                    "vertices":[
                                        { "y":455, "x":637 },
                                        { "y":455, "x":649 },
                                        { "y":473, "x":649 },
                                        { "y":473, "x":637 }
                                    ]
                                },
                                "index":0,
                                "confidence":0.9999,
                                "character":"R"
                            },
                            {
                                "bounding":{
                                    "vertices":[
                                        { "y":455, "x":648 },
                                        { "y":455, "x":661 },
                                        { "y":473, "x":661 },
                                        { "y":473, "x":648 }
                                    ]
                                },
                                "index":1,
                                "confidence":0.9999,
                                "character":"T"
                            },
                            {
                                "bounding":{  
                                    "vertices":[  
                                        { "y":455, "x":671 },
                                        { "y":455, "x":684 },
                                        { "y":474, "x":684 },
                                        { "y":474, "x":671 }
                                    ]
                                },
                                "index":2,
                                "confidence":0.9996,
                                "character":"B"
                            },
                            {
                                "bounding":{
                                    "vertices":[
                                        { "y":456, "x":683 },
                                        { "y":456, "x":696 },
                                        { "y":474, "x":696 },
                                        { "y":474, "x":683 }
                                    ]
                                },
                                "index":3,
                                "confidence":0.9995,
                                "character":"2"
                            }
                        ]
                    }
                }
            },
        },
        "objectId":"_vehicle_f3c3d26b-c568-4d98-b6db-b96659fd7766",
        "objectType":"vehicle"
    }
],
"requestId":"d25b5e5d22f6431498065e9a25134d59"
}

License Plate Recognition

Performs recognition on all of the license plates detected in a submitted Image. This is similar to Vehicle and License Plate Recognition. Note: No pairing of vehicles and license plates is attempted (as in the above Vehicle and License Plate Recogition), so the deeper search for license plates within vehicles is also not done. This can leave more license plates undetected than in the comparable call requesting both Vehicle and License Plate detection and recognition.

The objectType “licenseplate” is required. Uploading of images for enrollment, Image Management, Group Management, and Object Management are not supported for License Plate Recogniton.

The license plates in an image should be at least 80 pixels high for good results.

License plate character recognition is limited in its ability to find and recognize all characters. The response does not indicate whether any characters may have been missed. For example, a response including a string of “CCC24” could be for a license plate containing any or other of these variations: “CCC243”, “0CCC24”, “CCC124”. The confidence for the string is derived from the confidence for each individual character, so the confidence value also does not indicate missed characters.

The “region” field returns country or US State classification - including these countries: Belgium, France, Germany, Italy, Netherlands, UK.

Using Image URL
POST/v1/recognition?objectType=licenseplate

Example URI

POST https://dev.sighthoundapi.com/v1/recognition?objectType=licenseplate
Request

Request Body Attributes (JSON)

  • image (string): A fully qualified path to an image hosted on the internet to run recognition on
Headers
Content-Type: application/json
X-Access-Token: developersOwnCloudAccessToken
Body
{
  "image": "http://www.example.com/path/to/image.jpg"
}
Response  200

Response Attributes (JSON)

  • image (object): Size and rotation information of the provided image

    • width (integer): Pixel width of image
    • height (integer): Pixel height of image
    • orientation (integer): EXIF code representing rotation and/or flipping of source Image needed to align the source photo with the detection coordinates. Only applicable for photos with EXIF data (e.g., photos taken on a mobile device). Defaults to 1 (no rotation or flip), else the value found in the image’s EXIF data and indicates that bounding vertices have been translated to match that coordinate space.
  • objects (array): A list of objects recognized in the image

    • objectType (string): The type of Object detected. The expected value is “licenseplate”.
    • licenseplateAnnotation (object): A list of objects that contain detection coordinates, confidence scores, and other attributes
      • bounding (object):
        • vertices (array): A list of objects that define coordinates of the vertices that surround the Object
          • x (integer): Horizontal pixel position of the vertex
          • y (integer): Vertical pixel position of the vertex
      • attributes (object):
        • system (object): System-generated attributes for the detected Object
          • region (object): The country or state of the license plate
            • name (string): Country or state (e.g. “Florida” or “Germany”)
            • confidence (float): Confidence for the region
          • string (object): The license plate characters as a group
            • name (string): All characters in one string
            • confidence (float): Confidence for the string of characters
          • characters (array): List of attributes for each character recognized in the license plate
            • bounding (object):
              • vertices (array): A list of objects that define coordinates of the vertices that surround the Object
                • x (integer): Horizontal pixel position of the vertex
                • y (integer): Vertical pixel position of the vertex
            • index (integer): The index of this character within the string of license plate characters
            • confidence (float): Confidence that the character field is correct
            • character (string): The character
  • requestId (string): A server generated ID for the request

Headers
Content-Type: application/json
Body
{
  "image": {
    "width": 2016,
    "orientation": 1,
    "height": 1512
  },
  "objects": [
    {
      "licenseplateAnnotation": {
        "bounding": {
          "vertices": [
            {
              "x": 617,
              "y": 452
            },
            {
              "x": 743,
              "y": 452
            },
            {
              "x": 743,
              "y": 482
            },
            {
              "x": 617,
              "y": 482
            }
          ]
        },
        "attributes": {
          "system": {
            "region": {
              "name": "Florida",
              "confidence": 0.9994
            },
            "string": {
              "name": "RTB2",
              "confidence": 0.999
            },
            "characters": [
              {
                "bounding": {
                  "vertices": [
                    {
                      "y": 455,
                      "x": 637
                    },
                    {
                      "y": 455,
                      "x": 649
                    },
                    {
                      "y": 473,
                      "x": 649
                    },
                    {
                      "y": 473,
                      "x": 637
                    }
                  ]
                },
                "index": 0,
                "confidence": 0.9999,
                "character": "R"
              },
              {
                "bounding": {
                  "vertices": [
                    {
                      "y": 455,
                      "x": 648
                    },
                    {
                      "y": 455,
                      "x": 661
                    },
                    {
                      "y": 473,
                      "x": 661
                    },
                    {
                      "y": 473,
                      "x": 648
                    }
                  ]
                },
                "index": 1,
                "confidence": 0.9999,
                "character": "T"
              },
              {
                "bounding": {
                  "vertices": [
                    {
                      "y": 455,
                      "x": 671
                    },
                    {
                      "y": 455,
                      "x": 684
                    },
                    {
                      "y": 474,
                      "x": 684
                    },
                    {
                      "y": 474,
                      "x": 671
                    }
                  ]
                },
                "index": 2,
                "confidence": 0.9996,
                "character": "B"
              },
              {
                "bounding": {
                  "vertices": [
                    {
                      "y": 456,
                      "x": 683
                    },
                    {
                      "y": 456,
                      "x": 696
                    },
                    {
                      "y": 474,
                      "x": 696
                    },
                    {
                      "y": 474,
                      "x": 683
                    }
                  ]
                },
                "index": 3,
                "confidence": 0.9995,
                "character": "2"
              }
            ]
          }
        }
      },
      "objectType": "licenseplate"
    }
  ],
  "requestId": "d25b5e5d22f6431498065e9a25134d59"
}

Uploading Image
POST/v1/recognition?objectType=licenseplate

Example URI

POST https://dev.sighthoundapi.com/v1/recognition?objectType=licenseplate
Request

Request Body Attributes

  • Binary Stream of an image file to run recognition on
Headers
Content-Type: application/octet-stream
X-Access-Token: developersOwnCloudAccessToken
Body
< Image binary stream >
Response  200

Response Attributes (JSON)

  • image (object): Size and rotation information of the provided image

    • width (integer): Pixel width of image
    • height (integer): Pixel height of image
    • orientation (integer): EXIF code representing rotation and/or flipping of source Image needed to align the source photo with the detection coordinates. Only applicable for photos with EXIF data (e.g., photos taken on a mobile device). Defaults to 1 (no rotation or flip), else the value found in the image’s EXIF data and indicates that bounding vertices have been translated to match that coordinate space.
  • objects (array): A list of objects recognized in the image

    • objectType (string): The type of Object detected. The expected value is “licenseplate”.
    • licenseplateAnnotation (object): A list of objects that contain detection coordinates, confidence scores, and other attributes
      • bounding (object):
        • vertices (array): A list of objects that define coordinates of the vertices that surround the Object
          • x (integer): Horizontal pixel position of the vertex
          • y (integer): Vertical pixel position of the vertex
      • attributes (object):
        • system (object): System-generated attributes for the detected Object
          • region (object): The country or state of the license plate
            • name (string): Country or state (e.g. “Florida” or “Germany”)
            • confidence (float): Confidence for the region
          • string (object): The license plate characters as a group
            • name (string): All characters in one string
            • confidence (float): Confidence for the string of characters
          • characters (array): List of attributes for each character recognized in the license plate
            • bounding (object):
              • vertices (array): A list of objects that define coordinates of the vertices that surround the Object
                • x (integer): Horizontal pixel position of the vertex
                • y (integer): Vertical pixel position of the vertex
            • index (integer): The index of this character within the string of license plate characters
            • confidence (float): Confidence that the character field is correct
            • character (string): The character
  • requestId (string): A server generated ID for the request

Headers
Content-Type: application/json
Body
{
  "image": {
    "width": 2016,
    "orientation": 1,
    "height": 1512
  },
  "objects": [
    {
      "licenseplateAnnotation": {
        "bounding": {
          "vertices": [
            {
              "x": 617,
              "y": 452
            },
            {
              "x": 743,
              "y": 452
            },
            {
              "x": 743,
              "y": 482
            },
            {
              "x": 617,
              "y": 482
            }
          ]
        },
        "attributes": {
          "system": {
            "region": {
              "name": "Florida",
              "confidence": 0.9994
            },
            "string": {
              "name": "RTB2",
              "confidence": 0.999
            },
            "characters": [
              {
                "bounding": {
                  "vertices": [
                    {
                      "y": 455,
                      "x": 637
                    },
                    {
                      "y": 455,
                      "x": 649
                    },
                    {
                      "y": 473,
                      "x": 649
                    },
                    {
                      "y": 473,
                      "x": 637
                    }
                  ]
                },
                "index": 0,
                "confidence": 0.9999,
                "character": "R"
              },
              {
                "bounding": {
                  "vertices": [
                    {
                      "y": 455,
                      "x": 648
                    },
                    {
                      "y": 455,
                      "x": 661
                    },
                    {
                      "y": 473,
                      "x": 661
                    },
                    {
                      "y": 473,
                      "x": 648
                    }
                  ]
                },
                "index": 1,
                "confidence": 0.9999,
                "character": "T"
              },
              {
                "bounding": {
                  "vertices": [
                    {
                      "y": 455,
                      "x": 671
                    },
                    {
                      "y": 455,
                      "x": 684
                    },
                    {
                      "y": 474,
                      "x": 684
                    },
                    {
                      "y": 474,
                      "x": 671
                    }
                  ]
                },
                "index": 2,
                "confidence": 0.9996,
                "character": "B"
              },
              {
                "bounding": {
                  "vertices": [
                    {
                      "y": 456,
                      "x": 683
                    },
                    {
                      "y": 456,
                      "x": 696
                    },
                    {
                      "y": 474,
                      "x": 696
                    },
                    {
                      "y": 474,
                      "x": 683
                    }
                  ]
                },
                "index": 3,
                "confidence": 0.9995,
                "character": "2"
              }
            ]
          }
        }
      },
      "objectType": "licenseplate"
    }
  ],
  "requestId": "d25b5e5d22f6431498065e9a25134d59"
}