Recommender

In order to use Recommender API, you should install EPICA for Shopify application from Shopify AppStore and enable the recommender widget.

In all examples {write_key} can be obtained in EPICA Dashboard.

Version

Purpose

Get recommender API version

Endpoint

1 /api/v1/recommender/{write_key}/version

Auth

1 None

Method

1 GET

Request example

1 /api/v1/recommender/bb8716aa9cf17a3f8e0c11e43ecbdd0c/version

Response example

1 {"update_time":"2019-05-18 18:55:27","dates_range":{"from":"2018-11-20","to":"2019-05-14"},"version":"0.0.3"}

Errors

  • 500: server error.

Curl Example

1 curl -X GET https://api.epica.ai/api/v1/recommender/bb8716aa9cf17a3f8e0c11e43ecbdd0c/version

Segments

There you can see all available segments of the recommender. Segment here is a type of recommender.

Purpose

Get recommender segments

Endpoint

1 /api/v1/recommender/{write_key}/segments

Auth

1 None

Method

1 GET

Request example

1 /api/v1/recommender/bb8716aa9cf17a3f8e0c11e43ecbdd0c/segments

Response example

1 {"segments":["general","last_viewed","most_popular","trending","new_arrivals","complementary"]}

Errors

  • 500: server error.

Curl Example

1 curl -X GET https://api.epica.ai/api/v1/recommender/bb8716aa9cf17a3f8e0c11e43ecbdd0c/segments

Products

There you can make requests to get recommended products (general segment) for the particular user or other products according to the segments below.

Purpose

Get product items from different segments

Endpoint

1 /api/v1/recommender/{write_key}/products

Auth

1 None

Method

1 POST

Request example

1 /api/v1/recommender/bb8716aa9cf17a3f8e0c11e43ecbdd0c/products

Body parameters

  • anonymous_ids - a list of users to process

  • fields - a list of return fields

  • filters - to apply filters by categories or tags

  • complementary_sku - a product sku for further processing

  • segment - to select type of return items ("general", "last_viewed", "most_popular", "trending", "new_arrivals", "complementary")

  • n_items - the amount of returned items

Request data example

1 { "segment": "general", "anonymous_ids": [ "c5e8a219-3052-43a9-813e-21800140f67b" ], "filters": { "categories": [ { "value": "Toys", "condition": "equal" } ] }, "n_items": 2 }

Response example

1  { "schema": "shopify_epicababies", "segment": "general", "buckets": [ { "anonymous_id": "c5e8a219-3052-43a9-813e-21800140f67b", "items": [ { "image": "https://cdn.shopify.com/s/files/1/0063/0613/6162/products/product-image-579779468.jpg?v=1548724729", "active": true, "description": "Slime Kit \r\nMake Your Own Kids Gloop Sensory Play Science DIY Toy Game\n¬†\n\nAdd a bold, glittery \r\n\tpop to your projects and homemade slime!\nSafe, waschable, \r\n\tnon-toxic and no-run formula\nMake super \r\n\tcool slime, clear goo slime, color-changing slime, and glitter slimes, and \r\n\tmore!\nFor kids \r\n\tages 6 and up, and for parents too! Adult supervision is recommended.\nIt's perfect as a birthday or holiday gift, or \r\n\tfor play dates, after-school, or rainy day fun. And it's educational and \r\n\tkeeps children away from screens\n\n\nFeatures:\n\nMade of high quality \r\n\tmaterial,strong safe and non-toxic.\nWith enough material to make \r\n\ta crystal mud or a snow mud.\nHome or school activities \r\n\tfor boys and girls.\nCultivate the creativity of \r\n\tchildren,educational and keeps the kids away from screens.\nEasy step to make different \r\n\ttextured slime.\nProviding hours of fun for \r\n\tkids ages 6 and up.\n\n\nSpecifications:\n\nType: Slime Kit\nWeight: 106g\nCase Size: 3*8*4cm(L*W*H)\nSuitable for the Crowd: \r\n\tKid(6+ Years)\n\n\nPackage Included:\n\n1x Slime Activator Borax \r\n\t(6g)\n1x Bottle Of Slime Glue \r\n\t(50ml)\n1x Measuring Cup\n1x Small Scoop (Black)\n1x Bamboo Sticks\n1xPower\n\n How to playÔºö\n\nPrepare the required \r\n\tmaterials\nAdd a spoonful of Borax into \r\n\twarm water and stir to dilute\nThe glue and warm water by \r\n\t1:2 ratio were poured into the container, stirring evenly\nThen add Neon Purple and \r\n\tGlitter and stir evenly\nThen pour the diluted Borax \r\n\tsolution into the container\nThe solution in the \r\n\tcontainer is stirred until the paste is complete\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n", "discount": "4.77", "created_at": "2018-11-27T13:36:33", "title": "Slime Kit Make Your Own Kids Gloop Sensory Play Science DIY Toy Game", "url": "https://epicababies.myshopify.com/products/slime-kit-make-your-own-kids-gloop-sensory-play-science-diy-toy-game?variant=18131028967522", "tags": [ "0" ], "score": 3.1152028496730098, "updated_at": "2019-02-11T11:16:40", "price": "6.36", "options": "Yellow", "id": "1904867410018", "categories": [ "Toys" ], "sku": "1904867410018_18131028967522", "discount_percent": "33", "brand": "Vtech" }, { "image": "https://cdn.shopify.com/s/files/1/0063/0613/6162/products/product-image-164375651.jpg?v=1548724983", "active": true, "description": "Model Number: SZ007-SZ015 Dimensions: 29*9*5 Shape: Animal1 Gender: Unisex Features: Soft,Stuffed Warning: don't eat it Age Range: < 3 years old,0-12 Months,13-24 Months Size: 29*9*5 Package: Separates Material: Cloth Brand Name: sozzy Place of Origin: Guangdong, China (Mainland)", "discount": "7.0", "created_at": "2018-10-12T12:36:05", "title": "Mobil Stroller Hanging Toy", "url": "https://epicababies.myshopify.com/products/1pcs-new-infant-toys-mobile-baby-plush-sozzy-bed-wind-chimes-rattles-bell-toy-stroller-for-newborn-wholesale?variant=15740652912738", "tags": [ "Stroller Accesories" ], "score": 1.1764385214195543, "updated_at": "2018-12-03T13:24:25", "price": "7.0", "options": "Deer", "id": "1707635114082", "categories": [ "Test collection 2 (automated)", "Toys" ], "sku": "1707635114082_15740652912738", "discount_percent": "0", "brand": "epicababies" } ] } ] }

Errors

  • 400: bad request. It means that you send an incorrect json or wrong parameters inside.

  • 500: server error.

Curl Example

1 curl -H "Content-Type: application/json" -d '{data}' -X POST https://api.epica.ai/api/v1/recommender/bb8716aa9cf17a3f8e0c11e43ecbdd0c/products

Categories

You can make requests to get the recommended categories (general segment) for the particular user or other ones according to the segments below.

Purpose

Get category items from different segments

Endpoint

1 /api/v1/recommender/{write_key}/categories

Auth

1 None

Method

1 POST

Request example

1 /api/v1/recommender/bb8716aa9cf17a3f8e0c11e43ecbdd0c/categories

Body parameters

  • anonymous_ids - a list of users to process

  • fields - a list of return fields

  • segment - to select type of return items ("general", "most_popular", "trending")

  • n_items - the amount of returned items

Request data example

1 { "segment": "most_popular", "anonymous_ids": [ "c5e8a219-3052-43a9-813e-21800140f67b" ], "n_items": 3 }

Response example

1 { "schema": "shopify_epicababies", "segment": "most_popular", "buckets": [ { "anonymous_id": "c5e8a219-3052-43a9-813e-21800140f67b", "items": [ { "score": 59, "updated_at": "2019-05-03T11:15:01", "created_at": "2018-10-16T14:29:46.456057", "id": "3", "title": "Halloween Shop", "url": "https://epicababies.myshopify.com/collections/halloween-shop" }, { "score": 46, "updated_at": "2019-05-03T11:15:01", "created_at": "2018-10-16T14:29:46.456057", "id": "2", "title": "Diaper Bags", "url": "https://epicababies.myshopify.com/collections/diaper-bags" }, { "score": 41, "updated_at": "2019-05-23T19:00:04", "created_at": "2018-10-16T14:29:46.456057", "id": "6", "title": "Home page", "url": "https://epicababies.myshopify.com/collections/frontpage" } ] } ] }

Errors

  • 400: bad request. It means that you send an incorrect json or wrong parameters inside.

  • 500: server error.

Curl Example

1 curl -H "Content-Type: application/json" -d '{data}' -X POST https://api.epica.ai/api/v1/recommender/bb8716aa9cf17a3f8e0c11e43ecbdd0c/categories

 Accessing by config

You can make requests to get recommended products by pre-created configurations (check IDs in Shopify app UI) specifying a config_id.

Purpose

Accessing the recommender using the config

Endpoint

1 /api/v1/recommender/{write_key}/configs/{config_id}

Auth

1 None

Method

1 POST

Request example

1 /api/v1/recommender/bb8716aa9cf17a3f8e0c11e43ecbdd0c/configs/epica-6344223609186037

Request data example

1 {"anonymous_ids":["7e1d1841-114d-4c43-9a8a-eb207b27593f"]}

Response example

1 {"schema": "shopify_epicababies", "segment": "general", "buckets": [...]}

Errors

  • 500: server error.

Curl Example

1 curl -H "Content-Type: application/json" -d '{data}' -X POST https://api.epica.ai/api/v1/recommender/bb8716aa9cf17a3f8e0c11e43ecbdd0c/configs/epica-6344223609186037