Search 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: 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 (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 and collection token afe34dbe14890fac
Curl example
|
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
|
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 seconds 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 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 tracking data (if it exists) signed for the provided App ID.
- (optional) content: the content (if it exists)
- image: the UUID 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).
- item: the recognized item:
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
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
|
{
"search_time": 95,
"results":[
{
"item":{
"uuid":"b01c52771bd54b5d8e05cd626db99504",
"name":"Example Item",
"images": [
"83401c67067b4a7cbc3b6addccc9aa79",
"233062ceaaaf4e998cc64bf8b8406bac"
],
"trackable": true,
"url":"http://example/url",
"tracking": "",
"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]
]
}
],
"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"
}
}
|
Failure
|
1
2
3
4
5
6
|
{
"error": {
"code": "IMAGE_TOO_LARGE",
"message": "Image file size is too large"
}
}
|