Data processing workflow¶
merchant feed
instyle.ai batch processing
api serving results
This section describes the data flow from eshop to our platform and back.
OpenAPI docs¶
Visit the Interactive OpenApi specification using the link on top of the page
You should see an interactive list of endpoints with basic documentation
Don’t forget to “log-in” before trying out requests (details in next section).
Authorization¶
To authorize your requests inside the interactive docs click the button 
placed top right.
A modal window with available authorizations will pop up.
Service (read-only)¶
The most common way of authorization using only api-key.
Customer (apiKey) – use your
api_keyAuthorization (OAuth2, implicit) – skip, used for admin only
None Authorization (apiKey) – type in value
None
Admin¶
Not necessary in most cases. Enables modifying data like managing products or images on top of service privileges.
Customer (apiKey) – use your
api_keyAuthorization (OAuth2, implicit) – use your
client_id,usernameandpasswordto loginNone Authorization (apiKey) – skip, used for service only
Endpoints¶
Catalog V2¶
The simplified catalog is represented as hierarchy of three entities
- product
a model grouping all of its variants (colors, sizes, etc.)
has one or more looks, and one or more items
e.g. Nike Air Max 90 sneakers
- look
variant of the product that is visually distinct
has a parent product and one or more items
e.g. Nike Air Max 90 sneakers - Black
- item
concrete item that customer can purchase, usually a size variant of look (may include other attributes like condition - used or new)
has a parent look and a parent product
e.g. Nike Air Max 90 sneakers - Black - size 43
The api endpoints offer flexibility in
- perspective
query products, looks or items
- get or list
get a single entity by id or list through whole catalog
- entity serializers
- for each entity set how it will be represented in the response (none, id, expand)
none - entity won’t be included
id - only id will be included
expand - all data stored with this entity will be included
choose the least level necessary for each entity so that your response is small
Look results¶
The catalog endpoints serve both original data and our computed results. Currently our results are only look-related since we are processing the visual information. Therefore, all of our predictions are serialized in a single “results” object under expanded look. Here is simple description of the result fields (refer to example response bellow).
- related looks: list of recommended look ids for each recommender
similarity will recommend visually similar looks (alternatives)
style_with will recommend complimentary look ids to form an outfit
tags: most probable labels with their likelihoods for each tag
image order: suggested primary image and the second “flip” image for on-hover animation
Example product (fully expanded)¶
Request
curl -X GET "https://api.instyle.ai/recommendation-api/docs/v2/products/695353?product_serializer=expand&look_serializer=expand&item_serializer=expand"
-H "accept: application/json" -H "x-api-key: $API_KEY" -H "Authorization: None"
Response
{
"product_id": "695353",
"brand": "Trendyol",
"category_paths": [
[
"Ženy",
"Ženy oblečenie",
"Topy",
"Body"
]
],
"title": "Women"s Body Suit Trendyol Shiny",
"description": "<ul><li> 98% Polyester% 2 Sim </li><li> Model Measurements: Height: 1.78, Chest: 87, Waist: 60, Hip: 89, Size: S / 36/1 </li><li> <a href="http://www..com/Assets/file/Milla_Beden_Tablosu.jpg">Dimension Table</a> </li><li> Our products will be shipped with the TRENDYOL tag. </li></ul>",
"link": "https://sk.factcool.com/siyah-simli-yaka-dekolteli-body-1788629",
"google_product_category": "212",
"google_product_type": "Oblečení a doplňky > Oblečení > Košile a topy",
"gender": "female",
"adult": "no",
"mpn": "1788629",
"looks": [
{
"look_id": "695353",
"image_links": [
"https://i.factcool.com/catalog/products/tmp/ty/TPRAW18FZ0181R48B22_4_org_zoom.jpg",
"https://i.factcool.com/catalog/products/tmp/ty/TPRAW18FZ0181R48B20_2_org_zoom.jpg",
"https://i.factcool.com/catalog/products/tmp/ty/TPRAW18FZ0181R48B20_4_org_zoom.jpg",
"https://i.factcool.com/catalog/products/tmp/ty/TPRAW18FZ0181R48B20_1_org_zoom.jpg",
"https://i.factcool.com/catalog/products/tmp/ty/TPRAW18FZ0181R48B22_2_org_zoom.jpg",
"https://i.factcool.com/catalog/products/tmp/ty/TPRAW18FZ0181R48B22_3_org_zoom.jpg",
"https://i.factcool.com/catalog/products/tmp/ty/TPRAW18FZ0181R48B22_5_org_zoom.jpg"
],
"thumbnail_links": [
"https://i.factcool.com/catalog/products/tmp/ty/TPRAW18FZ0181R48B22_4_org_zoom.jpg?impolicy=298x298",
"https://i.factcool.com/catalog/products/tmp/ty/TPRAW18FZ0181R48B20_2_org_zoom.jpg?impolicy=298x298",
"https://i.factcool.com/catalog/products/tmp/ty/TPRAW18FZ0181R48B20_4_org_zoom.jpg?impolicy=298x298",
"https://i.factcool.com/catalog/products/tmp/ty/TPRAW18FZ0181R48B20_1_org_zoom.jpg?impolicy=298x298",
"https://i.factcool.com/catalog/products/tmp/ty/TPRAW18FZ0181R48B22_2_org_zoom.jpg?impolicy=298x298",
"https://i.factcool.com/catalog/products/tmp/ty/TPRAW18FZ0181R48B22_3_org_zoom.jpg?impolicy=298x298",
"https://i.factcool.com/catalog/products/tmp/ty/TPRAW18FZ0181R48B22_5_org_zoom.jpg?impolicy=298x298"
],
"results": {
"related_looks": {
"similarity": [
"695353",
"810047",
"809263",
"922176",
"920510",
"809265",
"822171",
"699503",
"918556",
"217967",
"695357",
"906781",
"935670",
"695149",
"700699",
"907249",
"935632",
"705789",
"705711",
"700589"
],
"style-with": [
"746401",
"223307",
"695229",
"934689",
"935010",
"211015",
"222727",
"713191",
"920567",
"921238"
]
},
"tags": {
"neckline": {
"asymmetric": 0.03,
"U_neck": 0.21,
"V_neck": 0.68,
"high": 0.02,
"sweetheart": 0.02,
"off_shoulder": 0.05
},
"top_length": {
"crop": 0.07,
"above_the_hip": 0.89,
"below_the_hip": 0.04
},
"top_fit": {
"regular": 0.3,
"tight": 0.6,
"peplum": 0.09
},
"top_collar": {
"none": 0.73,
"shirt": 0.05,
"polo": 0.03,
"banded": 0.1,
"decorated": 0.09
},
"sleeve": {
"zero_sleeve": 0.95,
"short": 0.03
},
"pattern.simple": {
"no": 0.99
},
"pattern.floral": {
"no": 1
},
"pattern.other": {
"yes": 0.02,
"no": 0.98
},
"pattern.square": {
"no": 1
},
"pattern.animal": {
"no": 1
},
"pattern.stripes": {
"no": 1
},
"pattern.dots": {
"yes": 0.98,
"no": 0.02
},
"pattern.logo": {
"no": 1
},
"pattern.imageText": {
"no": 1
},
"palette_colors": {
"#000000": 0.9,
"#bebebe": 0.07,
"#964b00": 0.03
},
"dominant_colors": {
"#161517": 0.9,
"#c1c2bf": 0.06,
"#392f2b": 0.02
}
},
"image_order": {
"suggested": {
"primary": {
"image_url": "https://i.factcool.com/catalog/products/tmp/ty/TPRAW18FZ0181R48B22_3_org_zoom.jpg",
"reason": "better_rotation"
},
"flip": {
"image_url": "https://i.factcool.com/catalog/products/tmp/ty/TPRAW18FZ0181R48B22_5_org_zoom.jpg",
"reason": "front_back"
}
}
}
},
"item_group_enabled": "1",
"color_group_id": "234157",
"supplier": {
"availability_min": "1",
"supplier_quantity": "6",
"availability_max": "1",
},
"items": [
{
"item_id": "695353-4154161",
"size": "42",
"price": "24.35 EUR",
"gtin": "TPRAW18FZ0181R48B34",
"condition": "new",
"availability": "in stock",
"full_id": "234157-695353-4154161",
"price_eur": "24.34536",
"supplier": {
"availability_min": "1",
"supplier_quantity": "2",
"is_dropship": "0",
"availability_max": "1",
}
},
{
"item_id": "695353-4154159",
"size": "40",
"price": "24.35 EUR",
"gtin": "TPRAW18FZ0181R48B30",
"condition": "new",
"availability": "in stock",
"full_id": "234157-695353-4154159",
"price_eur": "24.34536",
"supplier": {
"availability_min": "1",
"supplier_quantity": "4",
"is_dropship": "0",
"availability_max": "1",
}
},
{
"item_id": "695353-4154157",
"size": "38",
"price": "24.35 EUR",
"gtin": "TPRAW18FZ0181R48B26",
"condition": "new",
"availability": "in stock",
"full_id": "234157-695353-4154157",
"price_eur": "24.34536",
"supplier": {
"availability_min": "1",
"supplier_quantity": "6",
"is_dropship": "0",
"availability_max": "1",
}
}
]
}
]
}
# todo: examples # todo: describe results