Search API v2

This method of the Image Recognition API sends an image recognition request from a client application (such as mobile apps or your own server).

URL

https://search.craftar.net/v2/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.
app_id: a string identifying the application.
version: a string identifying the SDK version.
(optional) bboxes: if set to true the response will include bounding boxes. By default it’s false.
(optional) embed_custom: if set to true 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: if set to true the response tracking data will be embedded (if present). Otherwise, it will be sent as an url. By default it’s false.

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

Request examples

The example uses query image query.jpg, collection token afe34dbe14890fac, App ID com.catchoom.test and SDK version ARSDK-1.

Curl example

curl https://search.craftar.net/v2/search -F "token=afe34dbe14890fac" -F "image=@query.jpg" -F "app_id=com.catchoom.test" -F "version=ARSDK-1"

1	curl https://search.craftar.net/v2/search -F "token=afe34dbe14890fac" -F "image=@query.jpg" -F "app_id=com.catchoom.test" -F "version=ARSDK-1"

Python example

import catchoom
catchoom.search(token="afe34dbe14890fac", filename="query.jpg", app_id="com.catchoom.test", version="ARSDK-1")

1 2	import catchoom catchoom.search(token="afe34dbe14890fac", filename="query.jpg", app_id="com.catchoom.test", version="ARSDK-1")

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:

search_time: the time in milliseconds it took to CraftAR to process the query.
collection: general information for the collection where the query was performed:
- uuid: the collection id.
- pubkey: the public key that can be used to verify the tracking data’s signature.
- image_template: a template URL that can be used to find the thumbnail for an image with its id.
- app_id: the provided App ID.
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.
  - images: list with the UUID for all the images inside the item.
  - trackable: true if the item is trackable, false otherwise.
  - (optional) url: the item url (if it exists).
  - (optional) custom: the item custom data (if it exists).
  - (optional) tracking: the signed tracking data (if it is a trackable item).
  - (optional) content: the content (if it exists)
- image: the id for the best matching reference image among all images representing the item
- 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

{
  "search_time": 95,
  "collection": {
    "uuid": "dde84e1e72004808b5b0c490f2e78e23",
    "pubkey": "-----BEGIN PUBLIC KEY----- ... -----END PUBLIC KEY-----",
    "image_template": "https://crs-beta-catchoom.s3.amazonaws.com/cache/collections/{0}/images/{1}_{2}_thumb_120.jpe",
    "app_id": "com.catchoom.test"
  },
  "results":[
    {
      "item":{
        "uuid":"b01c52771bd54b5d8e05cd626db99504",
        "name":"Example Item",
        "images": [
          "83401c67067b4a7cbc3b6addccc9aa79",
          "233062ceaaaf4e998cc64bf8b8406bac"
        ],
        "trackable": true,
        "url":"http://example/url",
        "tracking": "<Signed tracking data>",
        "custom":"https://example.com/custom_data.json"
        "content": {
          "contents_v2": [],
          "version": 2
        }
      },
      "image": "83401c67067b4a7cbc3b6addccc9aa79",
      "score":100,
      "bbox":[
        [0.56, 0.31],
        [0.73, 0.16],
        [0.87, 0.51],
        [1.04, 0.36]
      ]
    }
  ]
}

{

"search_time": 95,

"collection": {

"uuid": "dde84e1e72004808b5b0c490f2e78e23",

"pubkey": "-----BEGIN PUBLIC KEY----- ... -----END PUBLIC KEY-----",

"image_template": "https://crs-beta-catchoom.s3.amazonaws.com/cache/collections/{0}/images/{1}_{2}_thumb_120.jpe",

"app_id": "com.catchoom.test"

"results":[

{

"item":{

"uuid":"b01c52771bd54b5d8e05cd626db99504",

"name":"Example Item",

"images": [

"83401c67067b4a7cbc3b6addccc9aa79",

"233062ceaaaf4e998cc64bf8b8406bac"

"trackable": true,

"url":"http://example/url",

"tracking": "<Signed tracking data>",

"custom":"https://example.com/custom_data.json"

"content": {

"contents_v2": [],

"version": 2

}

"image": "83401c67067b4a7cbc3b6addccc9aa79",

"score":100,

"bbox":[

[0.56, 0.31],

[0.73, 0.16],

[0.87, 0.51],

[1.04, 0.36]

]

}

]

}

Failure

{
    "error": {
        "code": "IMAGE_TOO_LARGE",
        "message": "Image file size is too large"
    }
}

{

"error": {

"code": "IMAGE_TOO_LARGE",

"message": "Image file size is too large"

}