NAV
bash javascript php

Overview

Welcome to GoPrediction Cloud API documentation. Get Postman Collection

API Authentication

We are use a simple solution to API authentication via a random token.

You can generate token in web interface.

Action Recommendation (AR)

This solution ideal for recommending products to customers based on their actions: views, likes, purchases, etc.

It works perfectly for first-time visitors, without re-train model.

Recommendations are made dynamically in real-time based on product IDs in the query.

How it works:

  1. Create new Action Recommendation instance in dashboard.
  2. Set URL to your product feed in instance.
  3. Collect actions via action method.
  4. Train data model.
  5. Get recommendations via query method.

AR JavaScript SDK

Use JavaScript SDK to communicate with GoPrediction API from frontend: https://cdn.goprediction.com/action-recommendation-api-2.8.min.js

You can include it from our CDN. After this, will be available variable ActionRecommendationApi.

Example:

ActionRecommendationApi.publicAccessKey = 'EzAQKfdFL6mdpSBy';

Before use it, set public access key.

_getCustomerIdentifier

Example:

var customer = ActionRecommendationApi._getCustomerIdentifier();

Method return unique ID of customer.

If it does not have it, a new one will be generated.

Customer identifier is stored in localStorage.

_setHistory

Example:

ActionRecommendationApi._setHistory({
    "product_id": 720,
    "action": "view"
});

Method save to localStorage last viewed/bought/liked/etc. product ID.

_getHistory

Example:

var productIds = ActionRecommendationApi._getHistory({
    "action": "view"
});

Method return array of product IDs, that customer recently viewed/bought/liked/etc.

view

Asynchronous:

ActionRecommendationApi.view({
    "customer": "YLPKEJzyO0S9d4h98SYnKWCToAMaLOGT",
    "product_id": 11823,
    "is_referrer": 0
}, function (response) {
    console.log(response);
});

Stores the customer product views by API.

purchase

Asynchronous:

ActionRecommendationApi.view({
    "customer": "YLPKEJzyO0S9d4h98SYnKWCToAMaLOGT",
    "product_id": 11823,
    "name": "Argus All-Weather Tank",
    "count": 1,
    "price": 3489,
}, function (response) {
    console.log(response);
});

Stores the customer purchases by API.

action

Asynchronous:

ActionRecommendationApi.action({
    "customer": "YLPKEJzyO0S9d4h98SYnKWCToAMaLOGT",
    "product_id": 11823
}, function (response) {
    console.log(response);
});

Storage customer action (view, buy, like, etc.) by API.

query

Asynchronous:

ActionRecommendationApi.query({
    "product_ids": [4582, 45, 5678],
    "count": 20
}, function (response) {
    console.log(response);
});

Synchronous:

var response = ActionRecommendationApi.query({
    "product_ids": [9927],
    "count": 20
});

Get recommendations by API.

AR JSON Feed

Example JSON:

{"items":[
    {
        "product_id": 12,
        "additional_fields": {
            "product_url": "https://devshop-71670.shoparena.pl/pl/p/Spodnica-TOP-SECRET%2C-kolekcja-SLIM/12",
            "title": "Spódnica TOP SECRET,  kolekcja SLIM",
            "price": "119.00",
            "image_url": "https://devshop-71670.shoparena.pl/userdata/gfx/a4138f864d018a2a29ab2e8209ff49ff.jpg"
        }
    },
    {
        "product_id": 13,
        "additional_fields": {
            "another_field": "data_here"
        }
    },
    {
        "product_id": 14
    }
]}

JSON feed is required.

Recommendation engine will return only products that included in feed.

JSON Parameters

Parameter Type Status Description
product_id int required Product ID.
additional_fields object optional Additional data of product.

Also, if you have GoogleShopping feed, you can use us converter:

https://cloud.goprediction.com/feed/converter/google-shopping?url=HERE_URL

This converter will return JSON product feed.

AR Action

Stores a customer action.

Use this method of storage customer's action on lifetime. For example from frontend via JavaScript.

Example request:

curl -X POST "https://cloud.goprediction.com/api/action-recommendation/action" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -d '{"public_access_key":"quia","customer":"omnis","product_id":6}'
const url = new URL("https://cloud.goprediction.com/api/action-recommendation/action");

let headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
}

let body = {
    "public_access_key": "quia",
    "customer": "omnis",
    "product_id": 6
}

fetch(url, {
    method: "POST",
    headers: headers,
    body: body
})
    .then(response => response.json())
    .then(json => console.log(json));

$client = new \GuzzleHttp\Client();
$response = $client->post("https://cloud.goprediction.com/api/action-recommendation/action", [
    'headers' => [
            "Content-Type" => "application/json",
            "Accept" => "application/json",
        ],
    'json' => [
            "public_access_key" => "quia",
            "customer" => "omnis",
            "product_id" => "6",
        ],
]);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200):

{
    "status": "success"
}

HTTP Request

POST api/action-recommendation/action

Body Parameters

Parameter Type Status Description
public_access_key string required Public Access Key.
customer string required Unique identifier of customer.
product_id integer required Unique identifier of product.

AR Purchase

Stores the customer purchases

Use this method for storage the customer purchases. For example, send this request in checkout page. This information will bill used for build metrics of purchases.

Its not required. But, if you use it, you also should use view method.

Example request:

curl -X POST "https://cloud.goprediction.com/api/action-recommendation/purchase" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -d '{"public_access_key":"6HpcgX00ipvvtrX1","customer":"ODmlFKGkm8XgSZhyn4OIDusbrWWz1i6v","product_id":3912,"price":3489,"name":"Argus All-Weather Tank","count":1}'
const url = new URL("https://cloud.goprediction.com/api/action-recommendation/purchase");

let headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
}

let body = {
    "public_access_key": "6HpcgX00ipvvtrX1",
    "customer": "ODmlFKGkm8XgSZhyn4OIDusbrWWz1i6v",
    "product_id": 3912,
    "price": 3489,
    "name": "Argus All-Weather Tank",
    "count": 1
}

fetch(url, {
    method: "POST",
    headers: headers,
    body: body
})
    .then(response => response.json())
    .then(json => console.log(json));

$client = new \GuzzleHttp\Client();
$response = $client->post("https://cloud.goprediction.com/api/action-recommendation/purchase", [
    'headers' => [
            "Content-Type" => "application/json",
            "Accept" => "application/json",
        ],
    'json' => [
            "public_access_key" => "6HpcgX00ipvvtrX1",
            "customer" => "ODmlFKGkm8XgSZhyn4OIDusbrWWz1i6v",
            "product_id" => "3912",
            "price" => "3489",
            "name" => "Argus All-Weather Tank",
            "count" => "1",
        ],
]);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200):

{
    "status": "success"
}

HTTP Request

POST api/action-recommendation/purchase

Body Parameters

Parameter Type Status Description
public_access_key string required Public Access Key.
customer string required Unique identifier of customer.
product_id integer required Unique identifier of product.
price integer required Price should be set in cents.
name string required Title of product.
count integer required Count of purchased product.

AR Query

Returns recommendations

Use this method for getting recommendations.

Example request:

curl -X GET -G "https://cloud.goprediction.com/api/action-recommendation/query?public_access_key=euA8JeCr3oKRptu3&product_ids=%5B112%5D&count=1" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"
const url = new URL("https://cloud.goprediction.com/api/action-recommendation/query");

    let params = {
            "public_access_key": "euA8JeCr3oKRptu3",
            "product_ids": "[112]",
            "count": "1",
        };
    Object.keys(params).forEach(key => url.searchParams.append(key, params[key]));

let headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
}

fetch(url, {
    method: "GET",
    headers: headers,
})
    .then(response => response.json())
    .then(json => console.log(json));

$client = new \GuzzleHttp\Client();
$response = $client->get("https://cloud.goprediction.com/api/action-recommendation/query", [
    'headers' => [
            "Content-Type" => "application/json",
            "Accept" => "application/json",
        ],
    'query' => [
            "public_access_key" => "euA8JeCr3oKRptu3",
            "product_ids" => "[112]",
            "count" => "1",
        ],
]);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200):

{
    "items": [
        {
            "product_id": "33869",
            "score": 0.9999999999999993
        },
        {
            "product_id": "481",
            "score": 0.9999999999999991,
            "additional_fields": {
                "price": 12,
                "title": "Example title"
            }
        }
    ]
}

HTTP Request

GET api/action-recommendation/query

Query Parameters

Parameter Status Description
public_access_key required Public Access Key.
product_ids required An array of product IDs.
count required Count of return items.

Returns recommendation stats

Method return statistics of recommendation requests.

Example request:

curl -X GET -G "https://cloud.goprediction.com/api/action-recommendation/query/stats?date_from=2019-01-01&date_to=2019-01-03" \
    -H "Authorization: Bearer {token}" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"
const url = new URL("https://cloud.goprediction.com/api/action-recommendation/query/stats");

    let params = {
            "date_from": "2019-01-01",
            "date_to": "2019-01-03",
        };
    Object.keys(params).forEach(key => url.searchParams.append(key, params[key]));

let headers = {
    "Authorization": "Bearer {token}",
    "Content-Type": "application/json",
    "Accept": "application/json",
}

fetch(url, {
    method: "GET",
    headers: headers,
})
    .then(response => response.json())
    .then(json => console.log(json));

$client = new \GuzzleHttp\Client();
$response = $client->get("https://cloud.goprediction.com/api/action-recommendation/query/stats", [
    'headers' => [
            "Authorization" => "Bearer {token}",
            "Content-Type" => "application/json",
            "Accept" => "application/json",
        ],
    'query' => [
            "date_from" => "2019-01-01",
            "date_to" => "2019-01-03",
        ],
]);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200):

{
    "stats": [
        {
            "date": "2019-01-01",
            "requests": 346
        },
        {
            "date": "2019-01-02",
            "requests": 453
        },
        {
            "date": "2019-01-03",
            "requests": 129
        }
    ]
}

HTTP Request

GET api/action-recommendation/query/stats

Query Parameters

Parameter Status Description
date_from required Date of begin stats.
date_to required Date of end stats.

AR Train

Init train model

Method init to train model data.

Example request:

curl -X POST "https://cloud.goprediction.com/api/action-recommendation/train/1" \
    -H "Authorization: Bearer {token}" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"
const url = new URL("https://cloud.goprediction.com/api/action-recommendation/train/1");

let headers = {
    "Authorization": "Bearer {token}",
    "Content-Type": "application/json",
    "Accept": "application/json",
}

fetch(url, {
    method: "POST",
    headers: headers,
})
    .then(response => response.json())
    .then(json => console.log(json));

$client = new \GuzzleHttp\Client();
$response = $client->post("https://cloud.goprediction.com/api/action-recommendation/train/1", [
    'headers' => [
            "Authorization" => "Bearer {token}",
            "Content-Type" => "application/json",
            "Accept" => "application/json",
        ],
]);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200):

{
    "message": [
        "Data model was added to queue for to train."
    ]
}

HTTP Request

POST api/action-recommendation/train/{instanceId}

AR View

Stores the customer product views

Use this method for storage a product views via customer. Send this request when user come to a product page. This information will bill used for build metrics of purchases and CTR (clicks).

Its not required. But, if you use it, you also should use purchase method.

Example request:

curl -X POST "https://cloud.goprediction.com/api/action-recommendation/view" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -d '{"public_access_key":"6HpcgX00ipvvtrX1","customer":"ODmlFKGkm8XgSZhyn4OIDusbrWWz1i6v","product_id":3912,"is_referrer":0}'
const url = new URL("https://cloud.goprediction.com/api/action-recommendation/view");

let headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
}

let body = {
    "public_access_key": "6HpcgX00ipvvtrX1",
    "customer": "ODmlFKGkm8XgSZhyn4OIDusbrWWz1i6v",
    "product_id": 3912,
    "is_referrer": 0
}

fetch(url, {
    method: "POST",
    headers: headers,
    body: body
})
    .then(response => response.json())
    .then(json => console.log(json));

$client = new \GuzzleHttp\Client();
$response = $client->post("https://cloud.goprediction.com/api/action-recommendation/view", [
    'headers' => [
            "Content-Type" => "application/json",
            "Accept" => "application/json",
        ],
    'json' => [
            "public_access_key" => "6HpcgX00ipvvtrX1",
            "customer" => "ODmlFKGkm8XgSZhyn4OIDusbrWWz1i6v",
            "product_id" => "3912",
            "is_referrer" => "0",
        ],
]);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200):

{
    "status": "success"
}

HTTP Request

POST api/action-recommendation/view

Body Parameters

Parameter Type Status Description
public_access_key string required Public Access Key.
customer string required Unique identifier of customer.
product_id integer required Unique identifier of product.
is_referrer integer required Set 1 when user come to product page from recommendations and 0 if not.