Image Recognition API v0

Recognition API v0

This is an older version of the Recognition API. It is still supported, but it does not provide all the latest features.
We strongly encourage you to use the latest version of the Image Recognition API.

Image Recognition API v0

Table of Contents

1. Introduction
2. Recognition API

2.1. Search
2.2. Timestamp

3. References

1. Introduction

The Catchoom Recognition Service (CRS) is a web service that allows you to build a wide range of Image Recognition applications and services.

This document describes the Recognition API, and demonstrates how to send valid recognition queries to the CRS using REST requests. In other words, the Recognition API permits you to build a client application.

In addition to the REST APIs our Catchoom Python Library provides easy to use functions and scripts for recognition and upload of images.

2. Recognition API

The CRS Recognition API is conforming to the REST (Representational state transfer) constraints as discussed in [1]. Note that the URL of the web service may change for different versions of the recognition API. Therefore, we recommend to build the client app with this URL as a parameter.

2.1. Search

Search allows sending visual recognition queries from client applications (such as a mobile app or your own server).

Url format:

https://search.craftar.net/v0/search

1	https://search.craftar.net/v0/search

Method:

POST

Parameters:

Parameters are sent using multipart/form-data encoding:

token is a string uniquely identifying the collection to be searched. Tokens are used in the Recognition API and in the Catchoom Mobile Apps to specify which collection of images should be searched through. Currently tokens consist of 16 randomly generated characters. The easiest way to manage your tokens is by using the CRS web panel, but you can also do it via the Management API.
image is a query image data.
custom is an optional parameter indicating whether the recognition result should contain custom data. The default false value skips the custom data strings from the response. Setting the parameter to true value retrieves the custom data strings corresponding to the recognized items.
bboxes is an optional parameter indicating whether the recognition result should include bounding boxes. The default false value skips bounding boxes from the response. Setting the parameter to true value includes the bounding boxes in the results.

For more information regarding multipart/form-data encoding consult [2].

Returns:

The service responds with HTTP status code, and, in cases of successful recognitions, with a JSON response data corresponding to the recognized items (objects). The recognized items are ordered by their relevancy, i.e. the first item from the JSON array has the highest recognition score.

The response header HTTP status codes include:

“200 OK”
“400 Bad Request”
“401 Unauthorized”
“403 Forbidden”
“500 Internal Server Error”

If a valid request is correctly received, and there are no internal errors, the service responds with HTTP status code “200 OK”.

If no relevant items (objects) are found in the requested collection an HTTP status code “200 OK” is returned with an empty array i.e. [] in the JSON response.

When relevant objects are found in the searched collection, the JSON response consists of an ordered array of all relevant items, each with the following syntax:

[
  {
    "item_id":"b01c52771bd54b5d8e05cd626db99504",
    "image_id":"83401c67067b4a7cbc3b6addccc9aa79",
    "score":100,
    "metadata":{
      "name":"Amazing Item",
      "url":"http://example.com",
      "thumbnail":"http://example.com/987654321_th.jpg",
      "custom":"Data string related to the item"
    },
    "bbox":[
      [0.56, 0.31],
      [0.73, 0.16],
      [0.87, 0.51],
      [1.04, 0.36]
    ]
  }
]

[

{

"item_id":"b01c52771bd54b5d8e05cd626db99504",

"image_id":"83401c67067b4a7cbc3b6addccc9aa79",

"score":100,

"metadata":{

"name":"Amazing Item",

"url":"http://example.com",

"thumbnail":"http://example.com/987654321_th.jpg",

"custom":"Data string related to the item"

"bbox":[

[0.56, 0.31],

[0.73, 0.16],

[0.87, 0.51],

[1.04, 0.36]

]

}

]

where:

item_id represents a unique identifier of the recognized item.
image_id represents a unique identifier of the recognized image from the ones related to the item.
score represents the recognition score.
metadata.name represents an item name associated with the recognized item (usually a freely-defined name that is suitable for display in an app or website).
metadata.url stores an URL associated with the recognized item (optional string that a user can freely define).
metadata.thumbnail represents an URL to the thumbnail of the recognized image (URL not necessarily formatted as in the example).
metadata.custom represents custom data string associated with the recognized item (optional string that a user can freely define).
bbox represents the corresponding bounding box.

In case of a problem, the service returns an adequate HTTP status code. Additionally, the response data may contain a verbatim JSON error message to help identifying the problem. These messages are intended solely for debugging purposes and therefore client services are not expected to parse them.

Example request:

POST https://search.craftar.net/v0/search
Multipart encoded data:
Content-Type: multipart/form-data; boundary=AaB03x
--AaB03x
Content-Disposition: form-data; name="token"
afe34dbe14890fac
--AaB03x
Content-Disposition: file; name="image"; filename="query_image.jpg"
Content-Type: image/jpg
<actual binary content of file “query_image.jpg”, not shown here>
--AaB03x--

POST https://search.craftar.net/v0/search

Multipart encoded data:

Content-Type: multipart/form-data; boundary=AaB03x

--AaB03x

Content-Disposition: form-data; name="token"

afe34dbe14890fac

--AaB03x

Content-Disposition: file; name="image"; filename="query_image.jpg"

Content-Type: image/jpg

--AaB03x--

Example responses:

Example of a response to a successful recognition:

Response headers:

HTTP/1.1 200 OK
Content-Type: application/json

1 2	HTTP/1.1 200 OK Content-Type: application/json

Response data:

[
  {
    "item_id":"1000020",
    "image_id":"2000030",
    "score":100,
    "metadata":{
      "thumbnail":"http://example.com/2000030_th.jpg",
      "url":"http://example.com",
      "name":"Amazing item",
      "custom":null
    }
  }
]

[

{

"item_id":"1000020",

"image_id":"2000030",

"score":100,

"metadata":{

"thumbnail":"http://example.com/2000030_th.jpg",

"url":"http://example.com",

"name":"Amazing item",

"custom":null

}

]

Example of a response to a corrupt query image:

Response headers:

HTTP/1.1 400 Bad Request
Content-Type: application/json

1 2	HTTP/1.1 400 Bad Request Content-Type: application/json

Response data:

{"message" : "Matching Failed: query image received incorrectly."}

1	{"message" : "Matching Failed: query image received incorrectly."}

cURL example:

Recognition using query image “query_image.jpg” and collection identified by token “afe34dbe14890fac”:

curl -F "custom=true" -F "bboxes=true" -F "image=@query_image.jpg" -F "token=afe34dbe14890fac" https://search.craftar.net/v0/search

1	curl -F "custom=true" -F "bboxes=true" -F "image=@query_image.jpg" -F "token=afe34dbe14890fac" https://search.craftar.net/v0/search

2.2. Timestamp

Timestamp permits you to check whether a collection token is valid.

Tokens are used in the Recognition API and in the Catchoom Mobile Apps to specify which collection of images should be searched through. The easiest way to manage your tokens is by using the CRS web panel, but you can also do it via the Management API.

Url format:

https://search.craftar.net/v0/timestamp

1	https://search.craftar.net/v0/timestamp

Method:

POST

Parameters:

Parameters are sent using multipart/form-data encoding:

token is a string uniquely identifying the collection to be searched. Currently tokens consist of 16 randomly generated characters. The easiest way to manage your tokens is by using the CRS web panel, but you can also do it via the Management API.

For more information regarding multipart/form-data encoding consult [2].

Returns:

The service responds with HTTP status code and a JSON response data with the timestamp.

If a valid request is correctly received and there are no internal errors the service responds with HTTP status code “200 OK”. All possible status codes include:

“200 OK”
“400 Bad Request”
“401 Unauthorized”
“403 Forbidden”
“500 Internal Server Error”

In case the request is properly authenticated (the token is valid for the given collection) the response is as follows:

{"timestamp":"1347991533.91"}

1	{"timestamp":"1347991533.91"}

where:

timestamp server’s time expressed in the number of seconds since the Epoch.

Example request:

POST https://search.craftar.net/v0/timestamp
Multipart encoded data:
Content-Type: multipart/form-data; boundary=AaB03x
--AaB03x
Content-Disposition: form-data; name="token"
afe34dbe14890fac

POST https://search.craftar.net/v0/timestamp

Multipart encoded data:

Content-Type: multipart/form-data; boundary=AaB03x

--AaB03x

Content-Disposition: form-data; name="token"

afe34dbe14890fac

Example responses:

Example of a response to a successful recognition:

Response headers:

HTTP/1.1 200 OK
Content-Type: application/json

1 2	HTTP/1.1 200 OK Content-Type: application/json

Response data:

{"timestamp": "1347991723.36"}

1	{"timestamp": "1347991723.36"}

Example of a response to an invalid token:

Response headers:

HTTP/1.1 403 Forbidden
Content-Type: application/json

1 2	HTTP/1.1 403 Forbidden Content-Type: application/json

Response data:

{"message": "Invalid token received"}

1	{"message": "Invalid token received"}

cURL example:

Check if a token is valid:

curl -F "token=afe34dbe14890fac" https://search.craftar.net/v0/timestamp

1	curl -F "token=afe34dbe14890fac" https://search.craftar.net/v0/timestamp

3. References

[1] Fielding, Roy Thomas (2000), Architectural Styles and the Design of Network-based Software Architectures, Doctoral dissertation, University of California, Irvine.
[2] Multipart/form-data format: http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4.2