BUNSAR Search
API Reference V2
AUTHENTICATION
Bunsar API requires an authentication token for each API request. Tokens are marked as
“consumed” after the requests to prevent a request to be replayed by an attacker.
An API key / API password pair is required to generate an authentication token. The token must
be generated at “server side” to keep the API password confident.
Below is the process of token generation;
Concatenate the userId1, the apiKey2, and the nonce3 in a single string,
o 1: userId is your user’s unique id.
o 2: apiKey is your company’s Bunsar API key.
o 3: nonce is a timestamp concatenated with a random number
Encrypt the concatenated string with HMAC/SHA14 algorithm using your apiPass5.
o 4: HMAC/SHA1 output must be base64 encoded.
o 5: apiPass is your API password.
Parameters
Field name Required? Description Sample Value
apiKey YES API key acme
userId NO Unique Identifier for End 123
User
nonce YES Current DateTime in (%Y 2021031712021517161081
%m%d%H%M%S) format
concatenated with
8 digit random number
token YES userId + apiKey + nonce Concatenated String:
are string concatenated 123acme2021031712021517161081
without separator; the Api Password: pass
resulting string is then SHA1+HMAC encrpyted Base64 String:
SHA1+HMAC encrypted RsXC67MKU_8mKvLamfjo2NmOZl0=
with your secret API
password and base64
encoded.
Sample Pyhton 3 Script:
from hashlib import sha1
from datetime import datetime
import random
import hmac
import base64
userId = '123'
apiKey = 'acme'
apiPass = 'pass'
nonce = [Link]().strftime("%Y%m%d%H%M%S") + str([Link](0,99999999)).zfill(8)
data = (userId + apiKey + nonce).encode()
# Url Safe Token
token = base64.urlsafe_b64encode([Link]([Link](), data, sha1).digest()).decode()
print("Token : {}".format(token))
IMAGE UPLOAD
In order to use Automatic Object Detection feature, the image must be uploaded to server first to
get a list of detected objects. If AutoDetect feature won’t be used, the image can be uploaded
within the search request.
API URL : [Link]
Method : POST
Content Type : Multipart
Parameters :
Field Name Required ? Description
userId NO See Authentication Section
apiKey YES See Authentication Section
nonce YES See Authentication Section
token YES See Authentication Section
image YES Image file to be uploaded
autodetect YES Turn on/off object detection.
0: Skip detection
1: Detect objects (Default)
{
“success”: integer, // 1=succeeded 0=failed
“errorCode”: integer, // see error codes
“errorDesc”: string, // error description (ony available in debug mode)
“filename”: string, // filename generated by server *TOBE USED in SEARCH call
“result” : obj array // search result by product categories
}
Sample Response:
{
"success": 1,
"hash": "fe6eb38e5b1206533a3fd9758f2f68158287d27d",
"filename": "99_20240405_154457_77729",
"imageRatio": 0.6666666666666666,
"dimensions": [ 564, 846 ],
"results": [
{
"categoryIndex": 4,
"categoryTitle": "Bottomwear",
"categoryName": "bottom",
"detectedObjectNo": 4,
"gender": "f"
},
{
"categoryIndex": 2,
"categoryTitle": "Topwear",
"categoryName": "top",
"detectedObjectNo": 1,
"gender": "f"
},
{
"categoryIndex": 6,
"categoryTitle": "Accs.",
"categoryName": "accessory",
"detectedObjectNo": 6,
"gender": "f"
},
{
"categoryIndex": 3,
"categoryTitle": "Footwear",
"categoryName": "shoes",
"detectedObjectNo": 3,
"gender": "f"
},
{
"categoryIndex": 3,
"categoryTitle": "Footwear",
"categoryName": "shoes",
"detectedObjectNo": 2,
"gender": "f"
},
{
"categoryIndex": 6,
"categoryTitle": "Accs.",
"categoryName": "accessory",
"detectedObjectNo": 7,
"gender": "f"
}
],
"totalProcessingTime": 5.380936
}
SEARCH
API URL : [Link]
Method : POST
Content Type : Multipart
Parameters :
Field Name Required ? Description
userId NO See Authentication Section
apiKey YES See Authentication Section
nonce YES See Authentication Section
token YES See Authentication Section
filename YES Filename of an already uploaded image
gender YES f : female, m : male,
fc: female child, mc: male child,
fb : female baby, mb : male baby
detectedObjectNo YES detectedObjectNo of an already uploaded image
maxResults NO Maximum nb of Search Results Category
range: 1 – 50, integer
default: 10
Sample Response:
{
"success": 1,
"filename": "99_20240405_154457_77729",
"results": [
{
"categoryIndex": "4",
"categoryName": "bottom",
"categoryTitle": "Bottomwear",
"products": [
{
"retailerSKU": "200660768",
"retailerCode": "dığer"
},
{
"retailerSKU": "200605726",
"retailerCode": "dığer"
},
{
"retailerSKU": "201033025",
"retailerCode": "dığer"
},
{
"retailerSKU": "200761315",
"retailerCode": "dığer"
},
{
"retailerSKU": "200597468",
"retailerCode": "dığer"
},
{
"retailerSKU": "200847956",
"retailerCode": "dığer"
}
]
}
],
"totalProcessingTime": 0.493607
}
RELEVANTOUTFITS
API URL : [Link]
Method : GET
Content Type : Multipart
Parameters :
Field Name Required ? Description
userId NO See Authentication Section
apiKey YES See Authentication Section
nonce YES See Authentication Section
token YES See Authentication Section
filename YES Filename of an already uploaded image
gender YES f : female, m : male,
fc: female child, mc: male child,
fb : female baby, mb : male baby
detectedObjectNo YES detectedObjectNo of an already uploaded image
maxResults NO Maximum nb of Search Results Category
range: 1 – 50, integer
default: 10
Sample Response:
{
"success": 1,
"filename": "99_20240405_123931_78444",
"outfits": [
[
{
"retailerSKU": "200899754",
"displayOrder": 1,
"similarItems": [
{
"retailerSKU": "200762803"
},
{
"retailerSKU": "200762804"
},
{
"retailerSKU": "200913074"
},
{
"retailerSKU": "200574389"
},
{
"retailerSKU": "200705809"
}
]
},
{
"retailerSKU": "100352259",
"displayOrder": 4,
"similarItems": [
{
"retailerSKU": "101365479"
},
....
]
},
....
],
[
....
],
....
],
"totalProcessingTime": 0.621029
}