.. _swagger: Data processing workflow ======================== |data_workflow| - merchant feed - instyle.ai batch processing - api serving results This section describes the data flow from eshop to our platform and back. .. |data_workflow| image:: _static/data_workflow.png :width: 600px 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 |authorize 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_key`` - **Authorization (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_key`` - **Authorization (OAuth2, implicit)** -- use your ``client_id``, ``username`` and ``password`` to login - **None Authorization (apiKey)** -- skip, used for service only .. |authorize button| image:: _static/authorize.png :width: 100 .. |swagger| image:: _static/swagger.png :width: 800px Endpoints --------- Catalog V2 ########## |swagger| 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 .. code-block:: curl 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 .. code-block:: json { "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