Search
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/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.
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/v1/search -F "token=afe34dbe14890fac" -F "image=@query.jpg"
|
Python example
|
1
2
|
import catchoom
catchoom.search(token="afe34dbe14890fac", filename="query.jpg")
|
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).
- 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
|
{
"results":[
{
"item":{
"uuid":"b01c52771bd54b5d8e05cd626db99504",
"name":"Example Item",
"url":"http://example/url",
"custom":"https://example.com/custom_data.json"
},
"image":{
"uuid":"83401c67067b4a7cbc3b6addccc9aa79",
"thumb_120":"https://example.com/thumb.jpe"
},
"score":100,
"bbox":[
[0.56, 0.31],
[0.73, 0.16],
[0.87, 0.51],
[1.04, 0.36]
]
}
]
}
|
Failure
|
1
2
3
4
5
6
|
{
"error": {
"code": "IMAGE_TOO_LARGE",
"message": "Image file size is too large"
}
}
|