Recognition as a Service

Artificial Intelligence (AI) is a branch of computing that involves training computers to do things that normally require human intelligence. Machine Learning (ML) is a subset of AI which involves computers learning from and finding patterns in data in order to then be able to make predictions on new data by themselves.

Recognition Services™ can use for many scenarios, such as sentiment analysis, price prediction, product recommendation, sales forecasting, image classification, object detection and tracking, and more — it can easily integrate machine learning into your web, mobile, desktop, gaming, and IoT apps.

Run Recognition Services™ in the cloud or on-premises with containers — no third party services or infrastructure required. Apply it to diverse scenarios, like mobility or transport management related to image analysis, where data security and low latency are paramount.

The ability to process data all the way to the endpoints ensures maximum compliance with General Data Protection Regulation — GDPR — data protection standards and regulations, and the complex business processes built on this platform also meet these requirements.

Recognition Services™ API introduction

Requests

Any tool that is fluent in HTTP can communicate with the API simply by requesting the correct URI. Requests should be made using the HTTPS protocol so that traffic is encrypted. The interface responds to different methods depending on the action required.

HTTP statuses

Along with the HTTP methods that the API responds to, it will also return standard HTTP statuses, including error codes. In the event of a problem, the status will contain the error code, while the body of the response will usually contain additional information about the problem that was encountered. In general, if the status returned is in the 200 range, it indicates that the request was fulfilled successfully and that no error was encountered. Return codes in the 400 range typically indicate that there was an issue with the request that was sent. Among other things, this could mean that you did not authenticate correctly, that you are requesting an action that you do not have authorization for, that the object you are requesting does not exist, or that your request is malformed. If you receive a status in the 500 range, this generally indicates a server-side problem. This means that we are having an issue on our end and cannot fulfill your request currently.

Responses

When a request is successful, a response body will typically be sent back in the form of a JSON object. An exception to this is when a DELETE request is processed, which will result in a successful HTTP 204 status and an empty response body. Inside of this JSON object, the resource root that was the target of the request will be set as the key. This will be the singular form of the word if the request operated on a single object, and the plural form of the word if a collection was processed. The value of these keys will generally be a JSON object for a request on a single object and an array of objects for a request on a collection of objects.

Curl examples

Throughout this document, some example API requests will be given using the curl command. This will allow us to demonstrate the various endpoints in a simple, textual format.

The first variable that you should set to get started is your OAuth authorization token. If you need access to the headers of a response through curl, you can pass the -i flag to display the header information along with the body. If you are only interested in the header, you can instead pass the -I flag, which will exclude the response body entirely.

Parameters

There are two different ways to pass parameters in a request with the API.

When passing parameters to create or update an object, parameters should be passed as a JSON object containing the appropriate attribute names and values as key-value pairs. When you use this format, you should specify that you are sending a JSON object in the header. This is done by setting the Content-Type header to application/json. This ensures that your request is interpreted correctly.

When passing parameters to filter a response on GET requests, parameters can be passed using standard query attributes. In this case, the parameters would be embedded into the URI itself by appending a ? to the end of the URI and then setting each attribute with an equal sign. Attributes can be separated with a &. Tools like curl can create the appropriate URI when given parameters and values; this can also be done using the -F flag and then passing the key and value as an argument. The argument should take the form of a quoted string with the attribute being set to a value with an equal sign.

Sample request

Curl example
curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.recognition.services/v1/objectdetection/person"

Request headers
Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Request body
{
  "id": 512190,
  "name": "My image of persons",
  "fingerprint": "1baa2c4ae9f668dc871ff6a970c82d16715693da",
  "image": "QUJDLTEyMw=="
}

Sample response

Response headers
content-type: application/json; charset=utf-8
status: 200 OK

Response body for single object
{
  "object": {
   "id": 512190,
   "name": "My image of persons",
   "started_at": "2019-12-04T15:24:21Z",
   "finished_at": "2019-12-04T15:24:21Z",
   "person_upper_left_coordinate": "100,100",
   "person_bottom_right_coordinate": "500,300",
   "confidence": "0.673"
  }
}

Response body for an object collection
{
  "objects": [
   {
    "id": 512190,
    ...
   },
   {
    "id": 512190,
    ...
   }
  ]
}

Sample request

Curl example
curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.recognition.services/v1/objectdetection/licenseplatenumber"

Request headers
Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Request body
{
  "id": 512190,
  "name": "My image",
  "fingerprint": "1baa2c4ae9f668dc871ff6a970c82d16715693da",
  "image": "QUJDLTEyMw=="
}

Sample response

Response headers
content-type: application/json; charset=utf-8
status: 200 OK

Response body for single object
{
  "object": {
   "id": 512190,
   "name": "My image",
   "started_at": "2019-12-04T15:24:21Z",
   "finished_at": "2019-12-04T15:24:21Z",
   "car_upper_left_coordinate": "100,100",
   "car_bottom_right_coordinate": "500,300",
   "car_color": "red",
   "license_plate_upper_left_coordinate": "200,200",
   "license_plate_bottom_right_coordinate": "300,250",
   "license_plate_color": "white",
   "license_plate_number": "PXO755",
   "license_plate_country_code": "S,Sweden"
  }
}

Response body for an object collection
{
  "objects": [
   {
    "id": 512190,
    ...
   },
   {
    "id": 512190,
    ...
   }
  ]
}