logoCatchoom


Image Recognition API

The Image Recognition API allows you to integrate our cloud image recognition into your applications and services.

More specifically, the API conforms to the RESTful constrains and permits you to perform visual recognition against one of your collections of reference images by sending HTTP requests. The results are returned in JSON format.

We also provide Catchoom Python and Catchoom PHP libraries for consuming the HTTP API described here.

This article refers to version 1 (v1). Note that we still support older versions of our recognition API.

API requests:


It allows sending visual recognition requests from client applications (such as mobile apps or your own server).

URL

https://r.catchoom.com/v1/search

Method

POST

Parameters

  • token: the Token of the collection to be searched.
  • image: the query image, as binary image file in jpeg or png (without transparency) format.
  • (optional) bboxes: the response will include bounding boxes. By default it’s False.
  • (optional) embed_custom: the response custom data will be embedded. Otherwise, it will be sent as an url. By default it’s False. Note that embedding the custom data results in an additional latency. If you need to minimize response times we recommend getting just URLs (i.e. no embedding) and caching the data.
  • (optional) embed_tracking: the response tracking data will be embedded. Otherwise, it will be sent as an url. By default it’s False. Note that embedding the custom data results in an additional latency. If you need to minimize response times we recommend you getting just URLs (i.e. no embedding) and caching the data.

Note that the parameters must use multipart/form-data encoding.

Request examples

The example uses query image query.jpg and collection token afe34dbe14890fac

  • Curl example:
  • Python example

Response fields

The response contains a JSON dictionary with recognized items (objects) ordered by their scores, i.e. the first item has the highest score

The JSON dictionary has the following fields:

  • results: result list. If no items are recognized, this will be an empty JSON array.
    • item: the recognized item:
      • uuid: the item id.
      • name: the item name.
      • (optional) url: the item url (if it exists).
      • (optional) custom: the item custom data(if it exists).
      • (optional) tracking: the tracking data (if it exists)
      • (optional) content: the content (if it exists)
    • image: the best matching reference image among all images representing the item:
      • uuid: the image id.
      • thumb_120: a thumbnail of the image, 120×120 pixels.
    • score: the recognition score, representing the similarity between the query image and the matched reference image.
    • (optional) bbox: the bounding box (if exists).

In case of an error, in addition to an appropriate HTTP status code, the service will also return a much more specific and informative error codes in the JSON response. Check the documentation on Error codes in the recognition API for more detailed information.

Response examples

  • Success:
  • Failure:

 

↑ Top


Timestamp

It allows obtaining a timestamp giving you a convenient way to validate your collection token and to check network connectivity.

URL

https://r.catchoom.com/v1/timestamp

Method

POST

Parameters

Request example

The example uses collection token afe34dbe14890fac

  • Curl example:

Response fields

In case of an error, in addition to an appropriate HTTP status code, the service will also return a much more specific and informative error codes in the JSON response. Check the documentation on Error codes in the recognition API for more detailed information.

Response examples

  • Success:
  • Failure:

↑ Top