Integration

Data processing workflow

data_workflow

  • Eshop publishes merchant feed

  • We periodically download the feed and precompute results for all services

  • The results are served back to eshop though the API

Interactive 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

Endpoints

Historically there was a lot of endpoints available in our api serving various use cases. Recently, we made an effort to simplify the api for the most common use-cases. The result was CatalogV2 that aggregates all of instyle.ai’s results and merges them with original data from merchant feed.

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

Examples

Following examples showcase some (not all) of the serializer combinations for single entity (product, look, item) The perspectives and serializers work analogically in list endpoints.

  • product

    • own attributes expanded

      curl -X GET "https://api.instyle.ai/recommendation-api/docs/v2/products/695353?product_serializer=expand&look_serializer=none&item_serializer=none"
      -H  "accept: application/json" -H  "x-api-key: $API_KEY" -H  "Authorization: None"
      

      Response

      {
        "product_id": "695353",
        "brand": "Trendyol",
        "category_paths": [
          [
            "Ženy"
          ],
          [
            "Ženy",
            "Ženy oblečenie"
          ],
          [
            "Ženy",
            "Ženy oblečenie",
            "Topy"
          ],
          [
            "Ž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"
      }
      
    • fully expanded

      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",
            "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"
              },
              {
                "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"
              },
              {
                "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"
              }
            ]
          }
        ]
      }
      
    • ids only for all entities

      curl -X GET "https://api.instyle.ai/recommendation-api/docs/v2/products/695353?product_serializer=id&look_serializer=id&item_serializer=id"
      -H  "accept: application/json" -H  "x-api-key: $API_KEY" -H  "Authorization: None"
      

      Response

      {
        "product_id": "695353",
        "looks": [
          {
            "look_id": "695353",
            "items": [
              {
                "item_id": "695353-4154161"
              },
              {
                "item_id": "695353-4154159"
              },
              {
                "item_id": "695353-4154157"
              },
              {
                "item_id": "695353-4154155"
              }
            ]
          }
        ]
      }
      
  • look

    • own attributes expanded

      curl -X GET "https://api.instyle.ai/recommendation-api/docs/v2/looks/695353?product_serializer=none&look_serializer=expand&item_serializer=none"
      -H  "accept: application/json" -H  "x-api-key: $API_KEY" -H  "Authorization: None"
      

      Response

      {
        "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": {
          "image_order": null,
          "related_looks": {
            "similarity": [
              "695353",
              "1565304",
              "950593",
              "950592",
              "1363674",
              "1444524",
              "1527207",
              "1565306",
              "1424586",
              "1444600",
              "1565307",
              "1439140",
              "1569380",
              "1363672",
              "1255684",
              "1573876",
              "1363302",
              "1444522",
              "1444529",
              "1583439"
            ],
            "similarity_b": [
              "695353",
              "1565304",
              "950593",
              "950592",
              "1363674",
              "1444524",
              "1527207",
              "1565306",
              "1424586",
              "1444600",
              "1565307",
              "1439140",
              "1569380",
              "1363672",
              "1255684",
              "1573876",
              "1363302",
              "1444522",
              "1444529",
              "1583439"
            ],
            "style-with": [
              "1063779",
              "804829",
              "1438725",
              "1054859",
              "1076878",
              "1529549",
              "1330440"
            ]
          },
          "related_outfits": {
            "shop_the_look": [
              "female-formal182832564",
              "female-formal208709698"
            ]
          },
          "tags_hash": "918dc83885335641e3554579eff13b3e",
          "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
            },
            "dominant-colors": {
              "#181819": 0.97,
              "#3f3d3d": 0.01
            },
            "palette-colors": {
              "#000000": 0.97,
              "#bebebe": 0.02
            },
            "pattern.simple": {
              "yes": 0.01,
              "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.97,
              "no": 0.03
            },
            "pattern.logo": {
              "no": 1
            },
            "pattern.imageText": {
              "no": 1
            }
          },
          "tags_argmax": {
            "neckline": "V_neck",
            "top_length": "above_the_hip",
            "top_fit": "tight",
            "top_collar": "none",
            "sleeve": "zero_sleeve",
            "dominant-colors": "#181819",
            "palette-colors": "#000000",
            "pattern.simple": "no",
            "pattern.floral": "no",
            "pattern.other": "no",
            "pattern.square": "no",
            "pattern.animal": "no",
            "pattern.stripes": "no",
            "pattern.dots": "yes",
            "pattern.logo": "no",
            "pattern.imageText": "no"
          },
          "color_variant": null
        },
        "color": "No color",
        "item_group_enabled": "1",
        "color_group_id": "234157",
        "image_link_box": "https://i.factcool.com/cache2/410x615/catalog/products/tmp/ty/TPRAW18FZ0181R48B22_4_org_zoom.jpg"
      }
      
    • fully expanded

      curl -X GET "https://api.instyle.ai/recommendation-api/docs/v2/looks/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",
            "Ženy oblečenie"
          ],
          [
            "Ženy",
            "Ženy oblečenie",
            "Topy"
          ],
          [
            "Ž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",
        "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": {
          "image_order": null,
          "related_looks": {
            "similarity": [
              "695353",
              "1565304",
              "950593",
              "950592",
              "1363674",
              "1444524",
              "1527207",
              "1565306",
              "1424586",
              "1444600",
              "1565307",
              "1439140",
              "1569380",
              "1363672",
              "1255684",
              "1573876",
              "1363302",
              "1444522",
              "1444529",
              "1583439"
            ],
            "similarity_b": [
              "695353",
              "1565304",
              "950593",
              "950592",
              "1363674",
              "1444524",
              "1527207",
              "1565306",
              "1424586",
              "1444600",
              "1565307",
              "1439140",
              "1569380",
              "1363672",
              "1255684",
              "1573876",
              "1363302",
              "1444522",
              "1444529",
              "1583439"
            ],
            "style-with": [
              "1063779",
              "804829",
              "1438725",
              "1054859",
              "1076878",
              "1529549",
              "1330440"
            ]
          },
          "related_outfits": {
            "shop_the_look": [
              "female-formal182832564",
              "female-formal208709698"
            ]
          },
          "tags_hash": "918dc83885335641e3554579eff13b3e",
          "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
            },
            "dominant-colors": {
              "#181819": 0.97,
              "#3f3d3d": 0.01
            },
            "palette-colors": {
              "#000000": 0.97,
              "#bebebe": 0.02
            },
            "pattern.simple": {
              "yes": 0.01,
              "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.97,
              "no": 0.03
            },
            "pattern.logo": {
              "no": 1
            },
            "pattern.imageText": {
              "no": 1
            }
          },
          "tags_argmax": {
            "neckline": "V_neck",
            "top_length": "above_the_hip",
            "top_fit": "tight",
            "top_collar": "none",
            "sleeve": "zero_sleeve",
            "dominant-colors": "#181819",
            "palette-colors": "#000000",
            "pattern.simple": "no",
            "pattern.floral": "no",
            "pattern.other": "no",
            "pattern.square": "no",
            "pattern.animal": "no",
            "pattern.stripes": "no",
            "pattern.dots": "yes",
            "pattern.logo": "no",
            "pattern.imageText": "no"
          },
          "color_variant": null
        },
        "color": "No color",
        "item_group_enabled": "1",
        "color_group_id": "234157",
        "is_dropship": null,
        "image_link_box": "https://i.factcool.com/cache2/410x615/catalog/products/tmp/ty/TPRAW18FZ0181R48B22_4_org_zoom.jpg",
        "items": [
          {
            "item_id": "695353-4154161",
            "size": "42",
            "price": "\n        24.99 EUR\n    ",
            "gtin": "TPRAW18FZ0181R48B34",
            "condition": "new",
            "availability": "in stock",
            "full_id": "234157-695353-4154161",
            "price_eur": "24.99",
            "second_price": "\n            33.99 EUR\n        ",
            "second_price_eur": "33.99",
            "third_price": null,
            "third_price_eur": null
          },
          {
            "item_id": "695353-4154159",
            "size": "40",
            "price": "\n        24.99 EUR\n    ",
            "gtin": "TPRAW18FZ0181R48B30",
            "condition": "new",
            "availability": "in stock",
            "full_id": "234157-695353-4154159",
            "price_eur": "24.99",
            "second_price": "\n            33.99 EUR\n        ",
            "second_price_eur": "33.99",
            "third_price": null,
            "third_price_eur": null
          },
          {
            "item_id": "695353-4154157",
            "size": "38",
            "price": "\n        24.99 EUR\n    ",
            "gtin": "TPRAW18FZ0181R48B26",
            "condition": "new",
            "availability": "in stock",
            "full_id": "234157-695353-4154157",
            "price_eur": "24.99",
            "second_price": "\n            33.99 EUR\n        ",
            "second_price_eur": "33.99",
            "third_price": null,
            "third_price_eur": null
          },
          {
            "item_id": "695353-4154155",
            "size": "36",
            "price": "\n        24.99 EUR\n    ",
            "gtin": "TPRAW18FZ0181R48B22",
            "condition": "new",
            "availability": "in stock",
            "full_id": "234157-695353-4154155",
            "price_eur": "24.99",
            "second_price": "\n            33.99 EUR\n        ",
            "second_price_eur": "33.99",
            "third_price": null,
            "third_price_eur": null
          }
        ]
      }
      
    • ids only for all entities

      curl -X GET "https://api.instyle.ai/recommendation-api/docs/v2/looks/695353?product_serializer=id&look_serializer=id&item_serializer=id"
      -H  "accept: application/json" -H  "x-api-key: $API_KEY" -H  "Authorization: None"
      

      Response

      {
        "product_id": "695353",
        "look_id": "695353",
        "items": [
          {
            "item_id": "695353-4154161"
          },
          {
            "item_id": "695353-4154159"
          },
          {
            "item_id": "695353-4154157"
          },
          {
            "item_id": "695353-4154155"
          }
        ]
      }
      
  • item

    • own attributes expanded

      curl -X GET "https://api.instyle.ai/recommendation-api/docs/v2/items/695353-4154161?product_serializer=none&look_serializer=none&item_serializer=expand"
      -H  "accept: application/json" -H  "x-api-key: $API_KEY" -H  "Authorization: None"
      

      Response

      {
        "item_id": "695353-4154161",
        "size": "42",
        "price": "\n        24.99 EUR\n    ",
        "gtin": "TPRAW18FZ0181R48B34",
        "condition": "new",
        "availability": "in stock",
        "full_id": "234157-695353-4154161",
        "price_eur": "24.99",
        "second_price": "\n            33.99 EUR\n        ",
        "second_price_eur": "33.99",
        "third_price": null,
        "third_price_eur": null
      }
      
    • fully expanded

      curl -X GET "https://api.instyle.ai/recommendation-api/docs/v2/items/695353-4154161?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",
            "Ženy oblečenie"
          ],
          [
            "Ženy",
            "Ženy oblečenie",
            "Topy"
          ],
          [
            "Ž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",
        "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": {
          "image_order": null,
          "related_looks": {
            "similarity": [
              "695353",
              "1565304",
              "950593",
              "950592",
              "1363674",
              "1444524",
              "1527207",
              "1565306",
              "1424586",
              "1444600",
              "1565307",
              "1439140",
              "1569380",
              "1363672",
              "1255684",
              "1573876",
              "1363302",
              "1444522",
              "1444529",
              "1583439"
            ],
            "similarity_b": [
              "695353",
              "1565304",
              "950593",
              "950592",
              "1363674",
              "1444524",
              "1527207",
              "1565306",
              "1424586",
              "1444600",
              "1565307",
              "1439140",
              "1569380",
              "1363672",
              "1255684",
              "1573876",
              "1363302",
              "1444522",
              "1444529",
              "1583439"
            ],
            "style-with": [
              "1063779",
              "804829",
              "1438725",
              "1054859",
              "1076878",
              "1529549",
              "1330440"
            ]
          },
          "related_outfits": {
            "shop_the_look": [
              "female-formal182832564",
              "female-formal208709698"
            ]
          },
          "tags_hash": "918dc83885335641e3554579eff13b3e",
          "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
            },
            "dominant-colors": {
              "#181819": 0.97,
              "#3f3d3d": 0.01
            },
            "palette-colors": {
              "#000000": 0.97,
              "#bebebe": 0.02
            },
            "pattern.simple": {
              "yes": 0.01,
              "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.97,
              "no": 0.03
            },
            "pattern.logo": {
              "no": 1
            },
            "pattern.imageText": {
              "no": 1
            }
          },
          "tags_argmax": {
            "neckline": "V_neck",
            "top_length": "above_the_hip",
            "top_fit": "tight",
            "top_collar": "none",
            "sleeve": "zero_sleeve",
            "dominant-colors": "#181819",
            "palette-colors": "#000000",
            "pattern.simple": "no",
            "pattern.floral": "no",
            "pattern.other": "no",
            "pattern.square": "no",
            "pattern.animal": "no",
            "pattern.stripes": "no",
            "pattern.dots": "yes",
            "pattern.logo": "no",
            "pattern.imageText": "no"
          },
          "color_variant": null
        },
        "color": "No color",
        "item_group_enabled": "1",
        "color_group_id": "234157",
        "image_link_box": "https://i.factcool.com/cache2/410x615/catalog/products/tmp/ty/TPRAW18FZ0181R48B22_4_org_zoom.jpg",
        "item_id": "695353-4154161",
        "size": "42",
        "price": "24.99 EUR",
        "gtin": "TPRAW18FZ0181R48B34",
        "condition": "new",
        "availability": "in stock",
        "full_id": "234157-695353-4154161",
        "price_eur": "24.99",
        "second_price": "\n            33.99 EUR\n        ",
        "second_price_eur": "33.99",
        "third_price": null,
        "third_price_eur": null
      }
      
    • ids only for all entities

      curl -X GET "https://api.instyle.ai/recommendation-api/docs/v2/items/695353-4154161?product_serializer=id&look_serializer=id&item_serializer=id"
      -H  "accept: application/json" -H  "x-api-key: $API_KEY" -H  "Authorization: None"
      

      Response

      {
        "product_id": "695353",
        "look_id": "695353",
        "item_id": "695353-4154161"
      }
      

Recommendations

Static or personalized

We distinguish two types of recommendations

  • personalized: results are tailored specifically to given customer e.g. last seen products (user or session identifier is required)

  • static: results are same for everyone e.g. category bestsellers

Serializers

The recommendation results can be serialized as

  • id: result contains only ids of recommended looks (best performance)

  • expand: result looks are expanded with basic fields like title, price, image_url, (alpha version, not recommended for production)

Product detail page (PDP)

prp_recommenders

Examples

  • static recommendations with id serializer

    curl -X GET "https://api.instyle.ai/recommendation-api/v2/recommender/pdp/static/1419883?serializer=id"
    -H  "accept: application/json" -H  "x-api-key: $API_KEY" -H  "Authorization: None"
    

    Response

    {
      "similarity": [
        "1419883",
        "1026421",
        "1055089",
        "1063456",
        "870849",
        "1476917",
        "1384519",
        "1337751",
        "1586775",
        "916882",
        "1586696",
        "1476914",
        "1235632",
        "959240",
        "1395865",
        "1384726",
        "1395234",
        "1384734",
        "1377968",
        "1327749"
      ],
      "similarity_b": [
        "1419883",
        "1026421",
        "1055089",
        "1063456",
        "870849",
        "1476917",
        "1384519",
        "1337751",
        "1586775",
        "916882",
        "1586696",
        "1476914",
        "1235632",
        "959240",
        "1395865",
        "1384726",
        "1395234",
        "1384734",
        "1377968",
        "1327749"
      ]
    }
    
  • static recommendations with expand serializer

    curl -X GET "https://api.instyle.ai/recommendation-api/v2/recommender/pdp/static/1419883?serializer=expand"
    -H  "accept: application/json" -H  "x-api-key: $API_KEY" -H  "Authorization: None"
    

    Response

    {
      "similarity": [
        {
          "id": "1419883",
          "title": "GÄRDET - ECO pánská lehce zateplená lyžařská bunda - navy",
          "brand": "2117",
          "price": 124.99,
          "sizes": [
            "XL",
            "XXL"
          ],
          "image_url": "https://i.factcool.com/catalog/products/60/6d/89/60-6d-899b64857510923-navy.jpg",
          "link": "https://sk.factcool.com/index.php?route=product/product&product_id=1419883"
        },
        {
          "id": "1026421",
          "title": "Bunda lyžiarska pánska LOAP OTEL",
          "brand": "LOAP",
          "price": 125.99,
          "sizes": [
            "S"
          ],
          "image_url": "https://i.factcool.com/catalog/products/08/085ae0_lp00olm1922i05l.jpg",
          "link": "https://sk.factcool.com/index.php?route=product/product&product_id=1026421"
        },
        {
          "id": "1055089",
          "title": "Nevica Vail Ski Jacket Mens",
          "brand": "Nevica",
          "price": 98.99,
          "sizes": [
            "3XL",
            "L",
            "M",
            "S",
            "XL"
          ],
          "image_url": "https://i.factcool.com/catalog/products/1/f5/38/1-f5-38531cbb40851569_xxl.jpg",
          "link": "https://sk.factcool.com/index.php?route=product/product&product_id=1055089"
        }
      ],
      "similarity_b": [
        {
          "id": "1419883",
          "title": "GÄRDET - ECO pánská lehce zateplená lyžařská bunda - navy",
          "brand": "2117",
          "price": 124.99,
          "sizes": [
            "XL",
            "XXL"
          ],
          "image_url": "https://i.factcool.com/catalog/products/60/6d/89/60-6d-899b64857510923-navy.jpg",
          "link": "https://sk.factcool.com/index.php?route=product/product&product_id=1419883"
        },
        {
          "id": "1026421",
          "title": "Bunda lyžiarska pánska LOAP OTEL",
          "brand": "LOAP",
          "price": 125.99,
          "sizes": [
            "S"
          ],
          "image_url": "https://i.factcool.com/catalog/products/08/085ae0_lp00olm1922i05l.jpg",
          "link": "https://sk.factcool.com/index.php?route=product/product&product_id=1026421"
        },
        {
          "id": "1055089",
          "title": "Nevica Vail Ski Jacket Mens",
          "brand": "Nevica",
          "price": 98.99,
          "sizes": [
            "3XL",
            "L",
            "M",
            "S",
            "XL"
          ],
          "image_url": "https://i.factcool.com/catalog/products/1/f5/38/1-f5-38531cbb40851569_xxl.jpg",
          "link": "https://sk.factcool.com/index.php?route=product/product&product_id=1055089"
        }
      ]
    }
    
  • personalized recommendations with id serializer

    curl -X GET "https://api.instyle.ai/recommendation-api/v2/recommender/pdp/personalized/1419883?session_id=123&serializer=id"
    -H  "accept: application/json" -H  "x-api-key: $API_KEY" -H  "Authorization: None"
    

    Response

    {
      "last_seen": [
        "1419883",
        "1026421",
        "1055089",
        "1063456",
        "870849"
      ],
      "personalized": [
        "927331",
        "1129474",
        "1353956",
        "1510278",
        "1360846",
        "928878",
        "1491002",
        "925838",
        "1407215",
        "925839"
      ]
    }
    
  • personalized recommendations with expand serializer

    curl -X GET "https://api.instyle.ai/recommendation-api/v2/recommender/pdp/static/1419883?serializer=expand"
    -H  "accept: application/json" -H  "x-api-key: $API_KEY" -H  "Authorization: None"
    

    Response

    {
      "last_seen": [
        {
          "id": "1419883",
          "title": "GÄRDET - ECO pánská lehce zateplená lyžařská bunda - navy",
          "brand": "2117",
          "price": 124.99,
          "sizes": [
            "XL",
            "XXL"
          ],
          "image_url": "https://i.factcool.com/catalog/products/60/6d/89/60-6d-899b64857510923-navy.jpg",
          "link": "https://sk.factcool.com/index.php?route=product/product&product_id=1419883"
        },
        {
          "id": "1026421",
          "title": "Bunda lyžiarska pánska LOAP OTEL",
          "brand": "LOAP",
          "price": 125.99,
          "sizes": [
            "S"
          ],
          "image_url": "https://i.factcool.com/catalog/products/08/085ae0_lp00olm1922i05l.jpg",
          "link": "https://sk.factcool.com/index.php?route=product/product&product_id=1026421"
        },
        {
          "id": "1055089",
          "title": "Nevica Vail Ski Jacket Mens",
          "brand": "Nevica",
          "price": 98.99,
          "sizes": [
            "3XL",
            "L",
            "M",
            "S",
            "XL"
          ],
          "image_url": "https://i.factcool.com/catalog/products/1/f5/38/1-f5-38531cbb40851569_xxl.jpg",
          "link": "https://sk.factcool.com/index.php?route=product/product&product_id=1055089"
        }
      ],
      "personalized": [
        {
          "id": "927331",
          "title": "Bunda pánska Ombre C322",
          "brand": "Ombre",
          "price": 36.99,
          "sizes": [
            "L",
            "M",
            "S",
            "XL",
            "XXL"
          ],
          "image_url": "https://i.factcool.com/catalog/products/6/9a/906-9a-907ad44020210604094321_11455_1.jpg",
          "link": "https://sk.factcool.com/index.php?route=product/product&product_id=927331"
        },
        {
          "id": "1129474",
          "title": "Pánska bunda Lee Cooper Twin Zip Down",
          "brand": "Lee Cooper",
          "price": 36.99,
          "sizes": [
            "M",
            "S",
            "XL",
            "XS"
          ],
          "image_url": "https://i.factcool.com/cache2/1400x1400/products/Man/Bundy/2609111903507.jpg",
          "link": "https://sk.factcool.com/index.php?route=product/product&product_id=1129474"
        },
        {
          "id": "1353956",
          "title": "Ombre Clothing Men's mid-season quilted jacket C447",
          "brand": "Ombre",
          "price": 37.99,
          "sizes": [
            "M",
            "S",
            "XL"
          ],
          "image_url": "https://i.factcool.com/catalog/products/6/ec/b56-ec-b50b378d20210122081637_5902228405771.jpg",
          "link": "https://sk.factcool.com/index.php?route=product/product&product_id=1353956"
        }
      ]
    }
    

Category listing page (CLP)

TBD

Cart

TBD