NAV
shell ruby python javascript php

Introduction

"For ruby install using the below command."

[sudo] gem install artifacia
"Then require the gem."

require 'artifacia'

api_key = <your api_key>

client = Client.new(api_key)
"For python install using the below command."

[sudo] pip install artifacia
"Then import the package."

from artifacia import artifacia

api_key = <your api_key>

client = artifacia.Client(api_key)
"For node install using the below command."

[sudo] npm install artifacia --save
"Then require the package."

"use strict";

var client = require("artifacia");

var api_key = <your api_key>;

client.artifacia(api_key);
"For php install using the below command."

composer require artifacia/artifacia-client-php
"Then require the package"

<?php

require __DIR__ . '/vendor/autoload.php';

$api_key = <your api_key>;

use Artifacia\Client;

$client = new Client($api_key);

Welcome to the Artifacia API!

This documentation will give you an overview of Artifacia APIs and how to use them to provide relevant product recommendations to your users based on visual attributes of product images and user behavioural data.

The API is organized around REST. All requests to the API are made over SSL. All request and response bodies, including errors, are encoded in JSON.

We have also built various language bindings to make integration with Artifacia APIs easier. You can choose one of the supported languages from the tab on the top right.

Artifacia API currently provides three types of recommendations namely Similar Product, Cross Product and Personalized Recommendation.

Base url : https://api.artifacia.com/v1

To play around with a few examples, we recommend Postman, our preferred REST client. Once you get the necessary credentials under the Authentication tab on the left, you can simply click the button below to import a pre-made collection of examples.

Authentication

Authentication is done using the api_key which you can find from here.

Requests are authenticated using HTTP basic auth.

Getting Started

Artifacia APIs are organized around REST. We use HTTP verbs, HTTP authentication which will make it easier to integrate with our smart recommendation system.

Get started by following steps:

Authentication : You can request the credentials under the Authentication tab.

Data Management:You can upload the catalogue item data and user interaction data by using our data management APIs.

Get Recommendations: Once your data is processed by our system, you will receive a notification from us and after that your website or app can start making relevant product suggestions to your users APIs.

Data Management

Upload Catalogue Data

Add Items

Sample Request:

$ curl -H api_key:T3NTN2FRbmxZU3BuN3JOQ0JUMHowd1R1YmY4a2RZYzY -H "Content-Type: application/json" -X POST \
-d'{"features":["vr"], "details":[{"prodid": 11145, "url": \
"http://cdn3.bombayelectric.in/7957/gallery/DSC00977-edit.jpg",\
"category": "Dress","pattern": "Animal Print", \
"color": "Blue","material": \
"Cotton", "length":"Full Length"},{"prodid": 1135,"url": \
"http://cdn3.bombayelectric.in/7957/gallery/DSC00977-edit.jpg", \
"category":"Tops","pattern":"Animal Print","color":"Black",\
"length":"Full Length","material":"Polyester",\
} ]}' https://api.artifacia.com/v1/items
sample_data = File.read("sample_data.json")
data_indexing_response = client.upload_item_data(sample_data)
puts data_indexing_response
import json
sample_data = json.load(open("sample_data.json","rb"))
data_indexing_response = client.upload_item_data(sample_data)
print data_indexing_response
var sample_data = require("./sample_data.json");
client.upload_item_data(sample_data,function(result){console.log(result)});
<?php

$data = file_get_contents("./sample_data.json");
$data_indexing_response = $client->upload_item_data($data);
echo $data_indexing_response;

Sample response:

 {
    "status": "success",
    "status_code": 200,
    "message": "items are successfully inserted"
 }

The following method allows you to add products from your catalogue and their metadata to the database whatever metadata you have in your catalogue. It is not necessary to give all the attributes given below. To quickly check this API you can use the sample data

HTTP Request

POST   https://api.artifacia.com/v1/items

Request Parameters

Parameter Type Description
details
required
list List of dictionaries containing details of the item
prodid
required
string Unique identifier for the item
url
required
string Front “Facing” Url of the image
category
required
string Item type to which the product id belongs
features
required
list Features that you want. Accepted values “vr”, “cpr”
color string Colors of the product
pattern string Patterns such as solid, stripes, floral
length string Length such as mini, full
material string Fabric of the product
size string Size of the item
price string Price of the items
brand string Brand name of the item
discount string Discount for the given item
style string Style of the given item

Note:- vr = Visual Recommendation cpr = Cross Product Recommendation

Response Parameters

Parameter Type Description
status string “success” or “failure” for the respective situations
status_code integer Numerical code representing success or failure of the request
error string Description about the error
message string Detailed description if the request is successful

Delete Items

Sample Request:

$ curl -H api_key:T3NTN2FRbmxZU3BuN3JOQ0JUMHowd1R1YmY4a2RZYzY -H "Content-Type: application/json" -X DELETE \
-d'{"prodids":[1, 112, 3, 2234, 3233]}' \
https://api.artifacia.com/v1/items
sample_data = File.read("sample_items_data_to_delete.json")
data_indexing_response = client.delete_item_data(sample_data)
puts data_indexing_response
import json
sample_data = json.load(open("sample_items_data_to_delete.json","rb"))
data_indexing_response = client.delete_item_data(sample_data)
print data_indexing_response
var sample_data = requrie("./sample_items_data_to_delete.json");
client.delete_item_data(sample_data,function(result){console.log(result)});
<?php

$data = file_get_contents("./sample_items_data_to_delete.json");
$data_indexing_response = $client->delete_item_data($data);
echo $data_indexing_response;

Sample response:

 {
    "status": "success",
    "status_code": 200,
    "message": "items are successfully deleted from the database"
 }

The following method allows you to delete products and their metadata from the database. To check the API or see the sample data structure you can have a look at the sample data

HTTP Request

DELETE   https://api.artifacia.com/v1/items

Request Parameters

Parameter Type Description
prodids
required
list List of prodids to delete

Response Parameters

Parameter Type Description
status string “success” or “failure”
status_code integer Numerical code representing success or failure of a request
error string Description about the error
message string Detailed description for the successful request
not_present_ids list List of ProdIds which does not exist in the database

Upload User History

Add Purchased Items

Sample Request:

$ curl -H api_key:T3NTN2FRbmxZU3BuN3JOQ0JUMHowd1R1YmY4a2RZYzY -H "Content-Type: application/json" -X POST \
-d'{"items":[2, 3, 7]}' https://api.artifacia.com/v1/users/121/purchased_items
user_id = 1223
sample_data = File.read("sample_purchased_items.json")
data_indexing_response = client.upload_user_purchased_items(user_id, sample_data)
puts data_indexing_response
import json

user_id = 1232
sample_data = json.load(open("sample_purchased_items.json","rb"))
data_indexing_response = client.upload_user_purchased_items(user_id, sample_data)
print data_indexing_response
var user_id = 1232
var sample_data = requrie("./sample_purchased_items.json");
client.upload_user_purchased_items(user_id, sample_data,function(result){console.log(result)});
<?php

$user_id = 1234
$data = file_get_contents("./sample_purchased_items.json");
$data_indexing_response = $client->upload_user_purchased_items($user_id, $data);
echo $data_indexing_response;

Sample response:

 {
    "status": "success",
    "status_code": 200,
    "message": "successfully added"
 }

This API will help to add new purchase items for a set of users. To check the API or see the sample data structure you can have a look at the sample data

HTTP Request

POST   https://api.artifacia.com/v1/users/{user_id}/purchased_items

Request Parameters

Parameter Type Description
items
required
list Nested objects containing list of purchased items ids to be added for a given user id
user_id
required
integer Unique Id of the user for which purchased items are required to added

Response Parameters

Parameter Type Description
status string “success” or “failure”
status_code integer Numerical code representing success or failure of a request
error string Description about the error
message string Detailed description about successful request

Add Viewed Items

Sample Request:

$ curl -H api_key:T3NTN2FRbmxZU3BuN3JOQ0JUMHowd1R1YmY4a2RZYzY -H "Content-Type: application/json" -X POST \
-d'{"items":[2, 3, 7]}' https://api.artifacia.com/v1/users/1212/viewed_items
user_id = 1232
sample_data = File.read("sample_viewed_items.json")
data_indexing_response = client.upload_user_viewed_items(user_id, sample_data)
puts data_indexing_response
import json

user_id = 1232
sample_data = json.load(open("sample_viewed_items.json","rb"))
data_indexing_response = client.upload_user_viewed_items(user_id, sample_data)
print data_indexing_response
var user_id = 1232
var sample_data = requrie("./sample_viewed_items.json");
client.upload_user_viewed_items(user_id, sample_data,function(result){console.log(result)});
<?php

$user_id = 1232
$data = file_get_contents("./sample_viewed_items.json");
$data_indexing_response = $client->upload_user_viewed_items($user_id, $data);
echo $data_indexing_response;

Sample response:

 {
    "status": "success",
    "status_code": 200,
    "message": "successfully added"
 }

This API will help to add recently viewed items for a set of users. To check the API or see the sample data structure you can have a look at the sample data

HTTP Request

POST   https://api.artifacia.com/v1/users/{user_id}/viewed_items

Request Parameters

Parameter Type Description
items
required
list Nested objects containing list of recently viewed items ids to be added for a given user id
user_id
required
integer Unique Id of the user for which purchased items are required to added

Response Parameters

Parameter Type Description
status string “success” or “failure”
status_code integer Numerical code representing success or failure of a request
error string Description about the error
message string Detailed description about successful request

Data Upload Limits

There are certain limits imposed on you when using the API. Please familiarize yourself with the limits below.

  * Data should be in JSON format.

  * Maximum number of records in a batch should be 500.

  * Maximum batch size per upload should be 200 KB.

  * Maximum record size should be 369 bytes.

Recommendations

Visual Recommendations

Sample Request:

$ curl -H api_key:T3NTN2FRbmxZU3BuN3JOQ0JUMHowd1R1YmY4a2RZYzY -H "Content-Type: application/json" -X POST \
-d'{"filter":{"color":1, "pattern":1}}'https://api.artifacia.com/v1/recommendation/similar/2314/4
sample_prod_id = 2761
num = 4
filters = {"color" => 1, "pattern" => 1}
query_response = client.get_visual_recommendation(sample_prod_id, num, filters)
puts query_response
sample_prod_id = 2761
num = 4
filters = {"color":1, "pattern":1}
query_response = client.get_visual_recommendation(sample_prod_id, num, filters)
print query_response

var sample_prod_id = 2709;
var num = 4;
var filters = {'color':1, 'pattern':1};
client.get_visual_recommendation(sample_prod_id, num,filters, function(result){console.log(result)});

<?php

$sample_prod_id = 2761;
$num = 4
$filters = array('color' => 1, 'pattern' => 1);
$query_response = $client->get_visual_recommendation($sample_prod_id, $num, $filters);
echo $query_response;

Sample response:

 {
    "status": "success",
    "status_code": 200,
    "prod_ids": [111, 213, 543, 2344]
 }

The Visual Recommendation API provides an interface for retrieving similar products for a given product id. It provides a “More Like This” array of other products that are visually similar to the one selected by the user.

HTTP Request

POST   https://api.artifacia.com/v1/recommendation/similar/{prodid}/{num}

Request Parameters

Parameter Type Description
prodid
required
string Product Id for which visually similar/recommended product Ids are to be shown
num integer The number of results to be returned
filter string Filters to customize the results

Filter

An explicit filter can be applied in your request to prioritize on one of the attributes of your catalogue data. For example, if you want to prioritize based on color only you can set color=1 as part of the filter payload in your query as follows:

filter = {"color":1}

Similarly, if you want to prioritize based on multiple attributes like color, pattern, material etc. you can set color = 1, pattern = 1, material = 1 as part of the filter payload in your query as follows:

filter = {"color":1, "pattern":1, "material":1}

Response Parameters

Parameter Type Description
status string “success” or “failure” for the respective situations
status_code integer Numerical code representing success or failure of the request
error string Description about the error
prod_ids list List of recommended product ids for the given prod id

Cross Product Recommendations

Sample Request:

$ curl -H api_key:T3NTN2FRbmxZU3BuN3JOQ0JUMHowd1R1YmY4a2RZYzY -H "Content-Type: application/json" -X GET \
https://api.artifacia.com/v1/recommendation/collections/3214/4
sample_prod_id = 2761
num = 4
query_response = client.get_cpr_recommendation(sample_prod_id, num)
puts query_response
sample_prod_id = 2761
num = 4
query_response = client.get_cpr_recommendation(sample_prod_id, num)
print query_response

var sample_prod_id = 2709;
var num = 4
client.get_cpr_recommendation(sample_prod_id,num,function(result){console.log(result)});

<?php

$sample_prod_id = 2761;
$num = 4
$query_response = $client->get_cpr_recommendation($sample_prod_id, $num);
echo $query_response;

Sample response:

 {
    "status": "success",
    "status_code": 200,
    "prod_ids": [12, 342, 45, 65]
 }

The Cross Product Recommendation API provides an interface to retrieve complementary products for a given product id. It provides a “You May Also Like” array of products that are visually complementary to the one selected by the user. It consumes a product id and returns a list of product ids which are complementory to the query product id.

HTTP Request

GET   https://api.artifacia.com/v1/recommendation/collections/{prod_id}/{num}

Request Paramaters

Parameter Type Description
prodid
required
string Product Id for which complimentary product Ids are to be shown
num integer The number of results to be returned

Response Parameters

Parameter Type Description
status string “success” or “failure”
status_code integer Numerical code representing success or failure of a request
error string Description about the error
prod_ids list Product Id for which complimentary product Ids are to be shown

Personalized Recommendations

Sample Request:

$ curl -H api_key:T3NTN2FRbmxZU3BuN3JOQ0JUMHowd1R1YmY4a2RZYzY -H "Content-Type: application/json" -X GET \
https://api.artifacia.com/v1/recommendation/user/453/4
sample_user_id = 2761
num = 4
query_response = client.get_smart_recommendation(sample_user_id, num)
puts query_response
sample_user_id = 2761
num = 4
query_response = client.get_smart_recommendation(sample_user_id, num)
print query_response

var sample_user_id = 2709;
var num = 4
client.get_smart_recommendation(sample_user_id,num,function(result){console.log(result)});

<?php

$sample_prod_id = 2761;
$num = 4
$query_response = $client->get_smart_recommendation($sample_prod_id, $num);
echo $query_response;

Sample response:

 {
    "status": "success",
    "status_code": 200,
    "prod_ids": [22, 123, 456, 89]
 }

The Personalized Recommendation API provides an interface to retrieve personalized recommendations for a given user based on user interaction data. This API lets you make use of our advanced visual recommendation feature together with the data that you have to provide very targeted product suggestions.

The API consumes a user id and produces a list of product ids in which the user might be interested in based on their browsing history.

HTTP Request

GET   https://api.artifacia.com/v1/recommendation/user/{user_id}/{num}

Request Parameters

Parameter Type Description
userid
required
string User Id for which recommendations are to be shown
num integer The number of results to be returned

Response Parameters

Parameter Type Description
status string “success” or “failure”
status_code integer Numerical code representing success or failure of a request
error string Description about the error
prod_ids list List of recommended product ids for a given userid

Errors

The Artifacia API uses the following error codes:

Error Code Meaning
200 Success – Your request is successfully processed
400 Bad Request – Your request is not in proper format
401 Unauthorized – Your api_key didn’t match
404 Not Found – The specified prod id is not found
405 Method Not Allowed – You tried to access the Artifacia API with an invalid method
406 Not Acceptable – You requested a format that isn’t json
500 Internal Server Error – We had a problem with our server. Try again later.