API Reference

  • Version: 1.7.0
  • Hostname: segmentino.app/{your_segmentino_workspace}/api

Authorization

Segmentino uses OAuth for API authorization. Basic authentication MUST be enabled by sending ticket to support.
You can access your api credentials via “Settings” -> “API Credentials”. A client/consumer ID and secret should then be generated which will be used in the following processes. All authorization requests should be made to your specific Segmentino instance URL, i.e. https://segmentino.app/your_segmentino_workspace/api

OAuth2 Steps

  • GET
    Obtain Authorization Code
    use Segmentino\Auth\ApiAuth;
    
    // $initAuth->newAuth() will accept an array of OAuth settings
    $settings = array(
        'baseUrl'      => 'https://segmentino.app/{your_segmentino_workspace}',
        'version'      => 'OAuth2',
        'clientKey'    => '5ad6fa7asfs8fa7sdfa6sfas5fas6asdf8',
        'clientSecret' => 'adf8asf7sf54asf3as4f5sf6asfasf97dd',
        'callback'     => 'https://your-callback.com'
    );
    
    // Initiate the auth object
    $initAuth = new ApiAuth();
    $auth     = $initAuth->newAuth($settings);
    
    GET /oauth/v2/authorize?
        client_id=CLIENT_ID
        &grant_type=authorization_code
        &redirect_uri=https%3A%2F%2Fyour-redirect-uri.com%2Fcallback
        &response_type=code
        &state=UNIQUE_STATE_STRING

    Note: The state is optional but recommended to prevent CSRF attacks. It should be a uniquely generated string and stored locally in session, cookie, etc. to be compared with the returned value.

    Note: The redirect_uri should be URL encoded


  • POST
    Replace with an Access Token
    // Initiate process for obtaining an access token; this will redirect the user to the authorize endpoint and/or set the tokens when the user is redirected back after granting authorization
    if ($auth->validateAccessToken()) {
        if ($auth->accessTokenUpdated()) {
            $accessTokenData = $auth->getAccessTokenData();
    
            //store access token data however you want
        }
    }
    POST /oauth/v2/token
    
    client_id=CLIENT_ID
        &client_secret=CLIENT_SECRET
        &grant_type=authorization_code
        &redirect_uri=https%3A%2F%2Fyour-redirect-uri.com%2Fcallback
        &code=UNIQUE_CODE_STRING
  • ANY
    Make Request
    As mentioned in documents
    Authorization: Bearer ACCESS_TOKEN
    OR
    GET https://segmentino.app/{your_segmentino_workspace}/api/users?access_token=ACCESS_TOKEN
    OR
    POST https://segmentino.app/{your_segmentino_workspace}/api/users/{userId}
    
    {Additional Data}&access_token=ACCESS_TOKEN

    Authenticating the API request with OAuth2 is easy. Choose one of the following methods that is appropriate for the application’s needs.


Items

The following methods allow you to maintain the set of items in the catalog. The items are specified using their ids, which are unique string identifiers matching ^[a-zA-Z0-9_-:]+$, i.e. they may consist of digits, latin letters, underscores, colons and minus signs.

Add item

PUT
Add item
$item = new Items();
$item->addItem($itemID)
PUT /items/{itemId}

Adds new item of given itemId to the items catalog.

All the item properties for the newly created items are set null.

Parameters

Parameter Located in Type Required Since version Description
itemId path string Yes   ID of the item to be created.

Responses

Response Description
201 successful operation
400 The itemId does not match ^[a-zA-Z0-9_-:]+$.
401 Invalid or missing authentication details.
404 Invalid URL.
405 Invalid HTTP method.
409 The itemId is already present in the item catalog. In many cases, you may consider this code success – it only tells you that nothing has been written to the database.

Delete item

DELETE
Delete item
$item = new Items();
$item->deleteItem($itemID)
DELETE /items/{itemId}

Deletes an item of given itemId from the catalog.

If there are any purchases, ratings, bookmarks, cart additions or detail views of the item present in the database, they will be deleted in cascade as well. Also, if the item is present in some series, it will be removed from all the series where present.

Parameters

Parameter Located in Type Required Since version Description
itemId path string Yes   ID of the item to be deleted.

Responses

Response Description
200 successful operation
400 The itemId does not match ^[a-zA-Z0-9_-:]+$.
401 Invalid or missing authentication details.
404 The itemId is not present in the item catalog. In many cases, you may consider this code success – it only tells you that nothing has been deleted from the database since the item was already not present. If there is no additional info in the JSON response, you probably have an error in you URL.
405 Invalid HTTP method.

List items

GET
List items
$item = new Items();
$item->listItems()
GET /items/list/

Gets a list of IDs of items currently present in the catalog.

Parameters

Parameter Located in Type Required Since version Description
count query integer No   The number of items to be listed.
offset query integer No   Specifies the number of items to skip (ordered by itemId).
returnProperties query boolean No
With returnProperties=true, property values of the listed items are returned along with their IDs in a JSON dictionary.

Example response:

[
  {
    "itemId": "tv-178",
    "description": "4K TV with 3D feature",
    "categories":   ["Electronics", "Televisions"],
    "price": 342,
    "url": "myshop.com/tv-178"
  },
  {
    "itemId": "mixer-42",
    "description": "Stainless Steel Mixer",
    "categories":   ["Home & Kitchen"],
    "price": 39,
    "url": "myshop.com/mixer-42"
  }
]
includedProperties query array No
Allows to specify, which properties should be returned when returnProperties=true is set. The properties are given as a comma-separated list.

Example response for includedProperties=description,price:

[
  {
    "itemId": "tv-178",
    "description": "4K TV with 3D feature",
    "price": 342
  },
  {
    "itemId": "mixer-42",
    "description": "Stainless Steel Mixer",
    "price": 39
  }
]

Responses

Response Description
200 successful operation

Example:

[
  "item-1",
  "item-2",
  "item-3"
]
401 Invalid or missing authentication details.
404 Not found
405 Invalid HTTP method.

Item Properties

Item properties definition

Item properties are used for modelling your domain. The following methods allow definition of item properties. The properties may be thought as columns in a relational database table.

Add item property

PUT
Add item property
$item = new Items();
$item->addItemProperty($itemID)
PUT /items/properties/{propertyName}

Adding an item property is somehow equivalent to adding a column to the table of items. The items may be characterized by various properties of different types.

Parameters
Parameter Located in Type Required Since version Description
propertyName path string Yes   Name of the item property to be created. Currently, the following names are reserved:id, itemid, case insensitively. Also, the length of the property name must not exceed 63 characters.
type query string Yes  
Value type of the item property to be created. One of: int, double, string, boolean, timestamp, set, image or imageList.
  • int- Signed integer number.
  • double - Floating point number. It uses 64-bit base-2 format (IEEE 754 standard).
  • string - UTF-8 string.
  • boolean - true / false
  • timestamp - Value representing date and time.
  • set - Set of strings.
  • image - URL of an image (jpeg, png or gif).
  • imageList - List of URLs that refer to images.
Responses
Response Description
201 successful operation
400 Property name does not match ^[a-zA-Z0-9_-:]+$, or it is a reserved keyword (‘’id’‘, ‘’itemid’‘), or its length exceeds 63 characters. Type information is missing, or the given type is invalid.
401 Invalid or missing authentication details.
404 Invalid URL.
405 Invalid HTTP method.
409 The property of given name is already present in the database. In many cases, you may consider this code success – it only tells you that nothing has been written to the database.

Delete item property

DELETE
Delete item property
$item = new Items();
$item->deleteItemProperty($name)
DELETE /items/properties/{propertyName}

Deleting an item property is roughly equivalent to removing a column from the table of items.

Parameters
Parameter Located in Type Required Since version Description
propertyName path string Yes   Name of the property to be deleted.
Responses
Response Description
200 successful operation
400 Property name does not match ^[a-zA-Z0-9_-:]+$.
401 Invalid or missing authentication details.
404 Property of given name is not present in the database. In many cases, you may consider this code success – it only tells you that nothing has been deleted from the database since the item property was already not present. If there is no additional info in the JSON response, you probably have an error in you URL.
405 Invalid HTTP method.

Get item property info

GET
Get item property info
$item = new Items();
$item->getItemPropertyInfo($name)
GET /items/properties/{propertyName}

Gets information about specified item property.

Parameters
Parameter Located in Type Required Since version Description
propertyName path string Yes   Name of the property about which the information is to be retrieved.
Responses
Response Description
200 successful operation

Example:

{
  "name": "num-processors",
  "type": "int"
}
400 Property name does not match ^[a-zA-Z0-9_-:]+$.
401 Invalid or missing authentication details.
404 Property of given name is not present in the database. If there is no additional info in the JSON response, you probably have an error in you URL.
405 Invalid HTTP method.

List item properties

GET
List item properties
$item = new Items();
$item->listItemProperties()
GET /items/properties/list/

Gets the list of all the item properties in your database.

Responses
Response Description
200 successful operation

Example:

[
  {
    "name": "tags",
    "type": "set"
  },
  {
    "name": "release-date",
    "type": "timestamp"
  },
  {
    "name": "description",
    "type": "string"
  }
]
401 Invalid or missing authentication details.
404 Invalid URL.
405 Invalid HTTP method.

Values of item properties

The following methods allow assigning property values for items in the catalog. Set values are examined by content-based algorithms and used for recommendations, especially in case of cold start items, which are not covered with interactions yet.

Set item values

POST
Set item values
$item = new Items();
$item->setItemValues($itemID, $body)
POST /items/{itemId}

Set/update (some) property values of a given item. The properties (columns) must be previously created by Add item property.

Parameters
Parameter Located in Type Required Since version Description
itemId path string Yes   ID of the item which will be modified.
  body object Yes  
The values for the individual properties.

Example of body:

{
  "product_description": "4K TV with 3D feature",
  "categories":   ["Electronics", "Televisions"],
  "price_usd": 342,
  "in_stock_from": "2016-11-16T08:00Z",
  "image": "http://myexamplesite.com/products/4ktelevision3d/image.jpg",
  "other_images": ["http://myexamplesite.com/products/4ktelevision3d/image2.jpg",
                   "http://myexamplesite.com/products/4ktelevision3d/image3.jpg"]
}

Set item values can also cascade create the item, if it’s not already present in the database.

For this functionality:

  • When using the client libraries: Set the optional cascadeCreate parameter to true, just like when creating an interaction.

  • When using directly REST API: Set special “property” !cascadeCreate.

    Example:

    {
      "product_description": "4K TV with 3D feature",
      "!cascadeCreate": true
    }
    

    Note the exclamation mark (!) at the beginning of the parameter’s name to distinguish it from item property names.

Responses
Response Description
200 successful operation
400 Property name does not match ‘’^[a-zA-Z0-9_-:]+$‘’, value does not agree to property type.
401 Invalid or missing authentication details.
404 Property of given name is not present in the database. If there is no additional info in the JSON response, you probably have an error in you URL.
405 Invalid HTTP method.

Get item values

GET
Get item values
$item = new Items();
$item->getItemValues($itemID, $body)
GET /items/{itemId}

Get all the current property values of a given item.

Parameters
Parameter Located in Type Required Since version Description
itemId path string Yes   ID of the item properties of which are to be obtained.
Responses
Response Description
200 successful operation

Example:

{
  "release-date": null,
  "tags": [
    "electronics",
    "laptops"
  ],
  "num-processors": 12,
  "description": "Very powerful laptop",
  "weight": 1.6
}
400 The itemId does not match ^[a-zA-Z0-9_-:]+$
401 Invalid or missing authentication details.
404 Item of given itemId is not present in the catalog. If there is no additional info in the JSON response, you probably have an error in you URL.
405 Invalid HTTP method.

Users

The following methods allow you to manage users in your database.

Add user

PUT
Add user
$user = new Users();
$user->addUser($userID)
PUT /users/{userId}

Adds a new user to the database.

Parameters

Parameter Located in Type Required Since version Description
userId path string Yes   ID of the user to be added.

Responses

Response Description
201 successful operation
400 The userId does not match ^[a-zA-Z0-9_-:]+$.
401 Invalid or missing authentication details.
404 Invalid URL.
405 Invalid HTTP method.
409 User of given userId is already present in the database. In many cases, you may consider this code success – it only tells you that nothing has been written to the database.

Delete user

DELETE
Delete user
$user = new Users();
$user->deleteUser($userID)
DELETE /users/{userId}

Deletes a user of given userId from the database.

If there are any purchases, ratings, bookmarks, cart additions or detail views made by the user present in the database, they will be deleted in cascade as well.

Parameters

Parameter Located in Type Required Since version Description
userId path string Yes   ID of the user to be added.

Responses

Response Description
200 successful operation
400 The userId does not match ‘’^[a-zA-Z0-9_-:]+$‘’.
401 Invalid or missing authentication details.
404 User of given userId is not present in the database. In many cases, you may consider this code success – it only tells you that nothing has been deleted from the database since the user was already not present. If there is no additional info in the JSON response, you probably have an error in you URL.
405 Invalid HTTP method.

List users

GET
List users
$user = new Users();
$user->listUsers()
GET /users/list/

Gets a list of IDs of users currently present in the catalog.

Parameters

Parameter Located in Type Required Since version Description
count query integer No   The number of users to be listed.
offset query integer No   Specifies the number of users to skip (ordered by userId).
returnProperties query boolean No
With returnProperties=true, property values of the listed users are returned along with their IDs in a JSON dictionary.

Example response:

[
  {
    "userId": "user-81",
    "country": "US",
    "sex": "M"
  },
  {
    "userId": "user-314",
    "country": "CAN",
    "sex": "F"
  }
]
includedProperties query array No
Allows to specify, which properties should be returned when returnProperties=true is set. The properties are given as a comma-separated list.

Example response for includedProperties=country:

[
  {
    "userId": "user-81",
    "country": "US"
  },
  {
    "userId": "user-314",
    "country": "CAN"
  }
]

Responses

Response Description
200 successful operation

Example:

[
  "user-1",
  "user-2",
  "user-3"
]
401 Invalid or missing authentication details.
404 Invalid URL.
405 Invalid HTTP method.

User Properties

User properties definition

User properties are used for modelling users. The following methods allow definition of user properties. The properties may be thought as columns in a relational database table.

Add user property

PUT
Add user property
$user = new Users();
$user->addUserProperty($name, $type)
PUT /users/properties/{propertyName}

Adding an user property is somehow equivalent to adding a column to the table of users. The users may be characterized by various properties of different types.

Parameters
Parameter Located in Type Required Since version Description
propertyName path string Yes Name of the user property to be created. Currently, the following names are reserved:id, userid, case insensitively. Also, the length of the property name must not exceed 63 characters.
type query string Yes
Value type of the user property to be created. One of: int, double, string, boolean, timestamp, set.
  • int - Signed integer number.
  • double - Floating point number. It uses 64-bit base-2 format (IEEE 754 standard).
  • string - UTF-8 string.
  • boolean - true / false
  • timestamp - Value representing date and time.
  • set - Set of strings.
Responses
Response Description
201 successful operation
400 Property name does not match ^[a-zA-Z0-9_-:]+$, or it is a reserved keyword (‘’id’‘, ‘’userid’‘), or its length exceeds 63 characters. Type information is missing, or the given type is invalid.
401 Invalid or missing authentication details.
404 Invalid URL.
405 Invalid HTTP method.
409 The property of given name is already present in the database. In many cases, you may consider this code success – it only tells you that nothing has been written to the database.

Delete user property

DELETE
Delete user property
$user = new Users();
$user->deleteUserProperty($name)
DELETE /users/properties/{propertyName}

Deleting an user property is roughly equivalent to removing a column from the table of users.

Parameters
Parameter Located in Type Required Since version Description
propertyName path string Yes Name of the property to be deleted.
Responses
Response Description
200 successful operation
400 Property name does not match ^[a-zA-Z0-9_-:]+$.
401 Invalid or missing authentication details.
404 Property of given name is not present in the database. In many cases, you may consider this code success – it only tells you that nothing has been deleted from the database since the user property was already not present. If there is no additional info in the JSON response, you probably have an error in you URL.
405 Invalid HTTP method.

Get user property info

GET
Get user property info
$user = new Users();
$user->getUserPropertyInfo($name)
GET /users/properties/{propertyName}

Gets information about specified user property.

Parameters
Parameter Located in Type Required Since version Description
propertyName path string Yes Name of the property about which the information is to be retrieved.
Responses
Response Description
200 successful operation

Example:

{
  "name": "country",
  "type": "string"
}
400 Property name does not match ^[a-zA-Z0-9_-:]+$.
401 Invalid or missing authentication details.
404 Property of given name is not present in the database. If there is no additional info in the JSON response, you probably have an error in you URL.
405 Invalid HTTP method.

List user properties

GET
List user properties
$user = new Users();
$user->listUserProperties()
GET /users/properties/list/

Gets the list of all the user properties in your database.

Responses
Response Description
200 successful operation

Example:

[
  {
    "name": "country",
    "type": "string"
  },
  {
    "name": "sex",
    "type": "string"
  }
]
401 Invalid or missing authentication details.
404 Invalid URL.
405 Invalid HTTP method.

Values of user properties

The following methods allow assigning property values to user. Set values are examined by content-based algorithms and used in building recommendations especially for users that have only few interactions (e.g. new users). Useful properties may be for example gender or region..

Set user values

POST
Set user values
$user = new Users();
$user->setUserValues($userID, $body)
POST /users/{userId}

Set/update (some) property values of a given user. The properties (columns) must be previously created by Add user property.

Parameters
Parameter Located in Type Required Since version Description
userId path string Yes ID of the user which will be modified.
  body object Yes
The values for the individual properties.

Example of body:

{
  "country": "US",
  "sex": "F"
}

Set user values can also cascade create the user, if it’s not already present in the database.

For this functionality:

  • When using the client libraries: Set the optional cascadeCreate parameter to true, just like when creating an interaction.

  • When using directly REST API: Set special “property” !cascadeCreate.

    Example:

    {
      "country": "US",
      "!cascadeCreate": true
    }
    

    Note the exclamation mark (!) at the beginning of the parameter’s name to distinguish it from item property names.

Responses
Response Description
200 successful operation
400 Property name does not match ‘’^[a-zA-Z0-9_-:]+$‘’, value does not agree to property type.
401 Invalid or missing authentication details.
404 Property of given name is not present in the database. If there is no additional info in the JSON response, you probably have an error in you URL.
405 Invalid HTTP method.

Get user values

GET
Get user values
$user = new Users();
$user->getUserValues($userID)
GET /users/{userId}

Get all the current property values of a given user.

Parameters
Parameter Located in Type Required Since version Description
userId path string Yes ID of the user properties of which are to be obtained.
Responses
Response Description
200 successful operation

Example:

{
  "country": "US",
  "sex": "F"
}
400 The userId does not match ^[a-zA-Z0-9_-:]+$
401 Invalid or missing authentication details.
404 User of given userId is not present in the catalog. If there is no additional info in the JSON response, you probably have an error in you URL.
405 Invalid HTTP method.

User-Item Interactions

The following method allow adding, deleting and listing of interactions between the users and the items.

Detail Views

Add detail view

POST
Add detail view
$interactions = new Interactions();
$interactions->addDetailViews($params)
POST /detailviews/

Adds a detail view of a given item made by a given user.

Parameters
Parameter Located in Type Required Since version Description
userId body string Yes   User who viewed the item
itemId body string Yes   Viewed item
timestamp body string / number No   UTC timestamp of the view as ISO8601-1 pattern or UTC epoch time. The default value is the current time.
duration body integer No   Duration of the view
cascadeCreate body boolean No   Sets whether the given user/item should be created if not present in the database.
recommId body string No If this detail view is based on a recommendation request, recommId is the id of the clicked recommendation.
Responses
Response Description
201 successful operation
400 Given userId or itemId does not match ^[a-zA-Z0-9_-:]+$. timestamp or duration is not a real number ≥ 0.
401 Invalid or missing authentication details.
404 The cascadeCreate is not set true and the userId or the itemId were found in the database. If there is no additional info in the JSON response, you probably have an error in you URL.
405 Invalid HTTP method.
409 Detail view of the exact same userId, itemId and timestamp is already present in the database. Note that a user may view item’s details multiple times, yet triplets (userId, itemId, timestamp) must be unique. In many cases, you may consider this code success – it only tells you that nothing has been written to the database.

Delete detail view

DELETE
Delete detail view
$interactions = new Interactions();
$interactions->deleteDetailViews($params)
DELETE /detailviews/

Deletes an existing detail view uniquely specified by (userId, itemId, and timestamp) or all the detail views with given userId and itemId if timestamp is omitted.

Parameters
Parameter Located in Type Required Since version Description
userId query string Yes   ID of the user who made the detail view.
itemId query string Yes   ID of the item of which the details were viewed.
timestamp query number No   Unix timestamp of the detail view. If the timestamp is omitted, then all the detail views with given userId and itemId are deleted.
Responses
Response Description
200 successful operation
400 Given userId or itemId does not match ^[a-zA-Z0-9_-:]+$, or timestamp is not a real number ≥ 0.
401 Invalid or missing authentication details.
404 The userId, itemId, or detail view with given (userId, itemId, timestamp) not found in the database. If there is no additional info in the JSON response, you probably have an error in you URL.
405 Invalid HTTP method.

List item detail views

GET
List item detail views
$interactions = new Interactions();
$interactions->listItemDetailViews($itemID, $params)
GET /items/{itemId}/detailviews/

List all the detail views of a given item ever made by different users.

Parameters
Parameter Located in Type Required Since version Description
itemId path string Yes   ID of the item of which the detail views are to be listed.
Responses
Response Description
200 successful operation

Example:

[
  {
    "itemId": "item-x",
    "userId": "user-a",
    "duration": 14.23,
    "timestamp": 1348151906.0
  },
  {
    "itemId": "item-x",
    "userId": "user-b",
    "duration": null,
    "timestamp": 1348239363.0
  }
]
400 The itemId does not match ^[a-zA-Z0-9_-:]+$.
401 Invalid or missing authentication details.
404 Given itemId not found in the database. If there is no additional info in the JSON response, you probably have an error in you URL.
405 Invalid HTTP method.

List user detail views

GET
List user detail views
$interactions = new Interactions();
$interactions->listUserDetailViews($userID, $params)
GET /users/{userId}/detailviews/

Lists all the detail views of different items ever made by a given user.

Parameters
Parameter Located in Type Required Since version Description
userId path string Yes   ID of the user whose detail views are to be listed.
Responses
Response Description
200 successful operation

Example:

[
  {
    "itemId": "item-y",
    "userId": "user-a",
    "duration": 134.03,
    "timestamp": 1348139180.0
  },
  {
    "itemId": "item-x",
    "userId": "user-a",
    "duration": 14.23,
    "timestamp": 1348151906.0
  }
]
400 The userId does not match ^[a-zA-Z0-9_-:]+$.
401 Invalid or missing authentication details.
404 Given userId not found in the database. If there is no additional info in the JSON response, you probably have an error in you URL.
405 Invalid HTTP method.

Purchases

Add purchase

POST
Add purchase
$interactions = new Interactions();
$interactions->addPurchase($params)
POST /purchases/

Adds a purchase of a given item made by a given user.

Parameters
Parameter Located in Type Required Since version Description
userId body string Yes   User who purchased the item
itemId body string Yes   Purchased item
timestamp body string / number No   UTC timestamp of the purchase as ISO8601-1 pattern or UTC epoch time. The default value is the current time.
cascadeCreate body boolean No   Sets whether the given user/item should be created if not present in the database.
amount body number No Amount (number) of purchased items. The default is 1. For example if user-x purchases two item-y during a single order (session...), the amount should equal to 2.
price body number No Price paid by the user for the item. If amount is greater than 1, sum of prices of all the items should be given.
profit body number No Your profit from the purchased item. The profit is natural in e-commerce domain (for example if user-x purchases item-y for $100 and the gross margin is 30 %, then the profit is $30), but is applicable also in other domains (for example at a news company it may be income from displayed advertisement on article page). If amount is greater than 1, sum of profit of all the items should be given.
recommId body string No If this purchase is based on a recommendation request, recommId is the id of the clicked recommendation.
Responses
Response Description
201 successful operation
400 The userId or itemId does not match ^[a-zA-Z0-9_-:]+$. timestamp or duration is not a real number ≥ 0.
401 Invalid or missing authentication details.
404 The cascadeCreate is not set true and the userId or the itemId were found in the database. If there is no additional info in the JSON response, you probably have an error in you URL.
405 Invalid HTTP method.
409 Purchase of the exact same userId, itemId and timestamp is already present in the database. In many cases, you may consider this code success – it only tells you that nothing has been written to the database.

Delete purchase

DELETE
Delete purchase
$interactions = new Interactions();
$interactions->deletePurchase($params)
DELETE /purchases/

Deletes an existing purchase uniquely specified by userId, itemId, and timestamp or all the purchases with given userId and itemId if timestamp is omitted.

Parameters
Parameter Located in Type Required Since version Description
userId query string Yes   ID of the user who made the purchase.
itemId query string Yes   ID of the item of which was purchased.
timestamp query number No   Unix timestamp of the purchase. If the timestamp is omitted, then all the purchases with given userId and itemId are deleted.
Responses
Response Description
200 successful operation
400 Given userId or itemId does not match ^[a-zA-Z0-9_-:]+$, or timestamp is not a real number ≥ 0.
401 Invalid or missing authentication details.
404 The userId, itemId, or purchase with given (userId, itemId, timestamp) not found in the database. If there is no additional info in the JSON response, you probably have an error in you URL.
405 Invalid HTTP method.

List item purchases

GET
List item purchases
$interactions = new Interactions();
$interactions->listItemPurchases($itemID, $params)
GET /items/{itemId}/purchases/

List all the ever-made purchases of a given item.

Parameters
Parameter Located in Type Required Since version Description
itemId path string Yes   ID of the item of which the pucrhases are to be listed.
Responses
Response Description
200 successful operation

Example:

[
  {
    "itemId": "item-x",
    "userId": "user-a",
    "timestamp": 1348151906.0
  },
  {
    "itemId": "item-x",
    "userId": "user-b",
    "timestamp": 1348327154.0
  }
]
400 The itemId does not match ^[a-zA-Z0-9_-:]+$.
401 Invalid or missing authentication details.
404 Given itemId not found in the database. If there is no additional info in the JSON response, you probably have an error in you URL.
405 Invalid HTTP method.

List user purchases

GET
List user purchases
$interactions = new Interactions();
$interactions->listUserPurchases($userID, $params)
GET /users/{userId}/purchases/

List all the purchases ever made by a given user.

Parameters
Parameter Located in Type Required Since version Description
userId path string Yes   ID of the user whose purchases are to be listed.
Responses
Response Description
200 successful operation

Example:

[
  {
    "itemId": "item-x",
    "timestamp": 1348151906.0,
    "userId": "user-a"
  },
  {
    "itemId": "item-z",
    "timestamp": 1348239363.0,
    "userId": "user-a"
  }
]
400 The userId does not match ^[a-zA-Z0-9_-:]+$.
401 Invalid or missing authentication details.
404 Given userId not found in the database. If there is no additional info in the JSON response, you probably have an error in you URL.
405 Invalid HTTP method.

Ratings

Add rating

POST
Add rating
$interactions = new Interactions();
$interactions->addRating($params)
POST /ratings/

Adds a rating of given item made by a given user.

Parameters
Parameter Located in Type Required Since version Description
userId body string Yes   User who submitted the rating
itemId body string Yes   Rated item
timestamp body string / number No   UTC timestamp of the rating as ISO8601-1 pattern or UTC epoch time. The default value is the current time.
rating body number Yes   Rating rescaled to interval [-1.0,1.0], where -1.0 means the worst rating possible, 0.0 means neutral, and 1.0 means absolutely positive rating. For example, in the case of 5-star evaluations, rating = (numStars-3)/2 formula may be used for the conversion.
cascadeCreate body boolean No   Sets whether the given user/item should be created if not present in the database.
recommId body string No If this rating is based on a recommendation request, recommId is the id of the clicked recommendation.
Responses
Response Description
201 successful operation
400 The userId or itemId does not match ^[a-zA-Z0-9_-:]+$, or rating is not a real number from [-1.0,1.0], or timestamp is not a real number ≥ 0.
401 Invalid or missing authentication details.
404 The cascadeCreate is not set true and the userId or the itemId were found in the database. If there is no additional info in the JSON response, you probably have an error in you URL.
405 Invalid HTTP method.
409 Rating of the exact same userId, itemId and timestamp is already present in the database. Note that a user may view item’s details multiple times, yet triplets (userId,itemId,timestamp) must be unique. In many cases, you may consider this code success – it only tells you that nothing has been written to the database.

Delete rating

DELETE
Delete rating
$interactions = new Interactions();
$interactions->deleteRating($params)
DELETE /ratings/

Deletes an existing rating specified by (userId, itemId, timestamp) from the database or all the ratings with given userId and itemId if timestamp is omitted.

Parameters
Parameter Located in Type Required Since version Description
userId query string Yes   ID of the user who rated the item.
itemId query string Yes   ID of the item which was rated.
timestamp query number No   Unix timestamp of the rating. If the timestamp is omitted, then all the ratings with given userId and itemId are deleted.
Responses
Response Description
200 successful operation
400 Given userId or itemId does not match ^[a-zA-Z0-9_-:]+$, or timestamp is not a real number ≥ 0.
401 Invalid or missing authentication details.
404 The userId, itemId or rating with given (userId, itemId, timestamp) not found in the database. If there is no additional info in the JSON response, you probably have an error in you URL.
405 Invalid HTTP method.

List item ratings

GET
List item ratings
$interactions = new Interactions();
$interactions->listItemRatings($itemID, $params)
GET /items/{itemId}/ratings/

List all the ratings of an item ever submitted by different users.

Parameters
Parameter Located in Type Required Since version Description
itemId path string Yes   ID of the item of which the ratings are to be listed.
Responses
Response Description
200 successful operation

Example:

[
  {
    "itemId": "item-x",
    "userId": "user-a",
    "rating": -0.25,
    "timestamp": 1348151906.0
  },
  {
    "itemId": "item-x",
    "userId": "user-b",
    "rating": 0.0,
    "timestamp": 1348239363.0
  }
]
400 The itemId does not match ^[a-zA-Z0-9_-:]+$.
401 Invalid or missing authentication details.
404 Given itemId not found in the database. If there is no additional info in the JSON response, you probably have an error in you URL.
405 Invalid HTTP method.

List user ratings

GET
List user ratings
$interactions = new Interactions();
$interactions->listUserRatings($userID, $params)
GET /users/{userId}/ratings/

List all the ratings ever submitted by a given user.

Parameters
Parameter Located in Type Required Since version Description
userId path string Yes   ID of the user whose ratings are to be listed.
Responses
Response Description
200 successful operation

Example:

[
  {
    "itemId": "item-y",
    "userId": "user-a",
    "rating": 0.5,
    "timestamp": 1348139180.0
  },
  {
    "itemId": "item-x",
    "userId": "user-a",
    "rating": -0.25,
    "timestamp": 1348151906.0
  }
]
400 The userId does not match ^[a-zA-Z0-9_-:]+$.
401 Invalid or missing authentication details.
404 Given userId not found in the database. If there is no additional info in the JSON response, you probably have an error in you URL.
405 Invalid HTTP method.

Cart Additions

Add cart addition

POST
Add cart addition
$interactions = new Interactions();
$interactions->addCartAddition($params)
POST /cartadditions/

Adds a cart addition of a given item made by a given user.

Parameters
Parameter Located in Type Required Since version Description
userId body string Yes   User who added the item to the cart
itemId body string Yes   Item added to the cart
timestamp body string / number No   UTC timestamp of the cart addition as ISO8601-1 pattern or UTC epoch time. The default value is the current time.
cascadeCreate body boolean No   Sets whether the given user/item should be created if not present in the database.
amount body number No Amount (number) added to cart. The default is 1. For example if user-x adds two item-y during a single order (session...), the amount should equal to 2.
price body number No Price of the added item. If amount is greater than 1, sum of prices of all the items should be given.
recommId body string No If this cart addition is based on a recommendation request, recommId is the id of the clicked recommendation.
Responses
Response Description
201 successful operation
400 The userId or itemId does not match ^[a-zA-Z0-9_-:]+$, timestamp is not a real number ≥ 0.
401 Invalid or missing authentication details.
404 The cascadeCreate is not set true and the userId or the itemId were found in the database. If there is no additional info in the JSON response, you probably have an error in you URL.
405 Invalid HTTP method.
409 Cart addition of the exact same userId, itemId and timestamp is already present in the database. In many cases, you may consider this code success – it only tells you that nothing has been written to the database.

Delete cart addition

DELETE
Delete cart addition
$interactions = new Interactions();
$interactions->deleteCartAddition($params)
DELETE /cartadditions/

Deletes an existing cart addition uniquely specified by userId, itemId, and timestamp or all the cart additions with given userId and itemId if timestamp is omitted.

Parameters
Parameter Located in Type Required Since version Description
userId query string Yes   ID of the user who made the cart addition.
itemId query string Yes   ID of the item of which was added to cart.
timestamp query number No   Unix timestamp of the cart addition. If the timestamp is omitted, then all the cart additions with given userId and itemId are deleted.
Responses
Response Description
200 successful operation
400 Given userId or itemId does not match ^[a-zA-Z0-9_-:]+$, or timestamp is not a real number ≥ 0.
401 Invalid or missing authentication details.
404 The userId, itemId, or cart addition with given (userId, itemId, timestamp) not found in the database. If there is no additional info in the JSON response, you probably have an error in you URL.
405 Invalid HTTP method.

List item cart additions

GET
List item cart additions
$interactions = new Interactions();
$interactions->listItemCartAdditions($itemID, $params)
GET /items/{itemId}/cartadditions/

List all the ever-made cart addition of a given item.

Parameters
Parameter Located in Type Required Since version Description
itemId path string Yes   ID of the item of which the cart addition are to be listed.
Responses
Response Description
200 successful operation

Example:

[
  {
    "itemId": "item-x",
    "userId": "user-a",
    "timestamp": 1348151906.0
  },
  {
    "itemId": "item-x",
    "userId": "user-a",
    "timestamp": 1348327154.0
  }
]
400 The itemId does not match ^[a-zA-Z0-9_-:]+$.
401 Invalid or missing authentication details.
404 Given itemId not found in the database. If there is no additional info in the JSON response, you probably have an error in you URL.
405 Invalid HTTP method.

List user cart additions

GET
List user cart additions
$interactions = new Interactions();
$interactions->listItemCartAdditions($itemID, $params)
GET /users/{userId}/cartadditions/

List all the cart additions ever made by a given user.

Parameters
Parameter Located in Type Required Since version Description
userId path string Yes   ID of the user whose cart additions are to be listed.
Responses
Response Description
200 successful operation

Example:

[
  {
    "itemId": "item-x",
    "timestamp": 1348151906.0,
    "userId": "user-a"
  },
  {
    "itemId": "item-z",
    "timestamp": 1348239363.0,
    "userId": "user-a"
  }
]
400 The userId does not match ^[a-zA-Z0-9_-:]+$.
401 Invalid or missing authentication details.
404 Given userId not found in the database. If there is no additional info in the JSON response, you probably have an error in you URL.
405 Invalid HTTP method.

Bookmarks

Add bookmark

POST
Add bookmark
$interactions = new Interactions();
$interactions->addBookmark($params)
POST /bookmarks/

Adds a bookmark of a given item made by a given user.

Parameters
Parameter Located in Type Required Since version Description
userId body string Yes   User who bookmarked the item
itemId body string Yes   Bookmarked item
timestamp body string / number No   UTC timestamp of the bookmark as ISO8601-1 pattern or UTC epoch time. The default value is the current time.
cascadeCreate body boolean No   Sets whether the given user/item should be created if not present in the database.
recommId body string No If this bookmark is based on a recommendation request, recommId is the id of the clicked recommendation.
Responses
Response Description
201 successful operation
400 The userId or itemId does not match ^[a-zA-Z0-9_-:]+$, timestamp is not a real number ≥ 0.
401 Invalid or missing authentication details.
404 The cascadeCreate is not set true and the userId or the itemId were found in the database. If there is no additional info in the JSON response, you probably have an error in you URL.
405 Invalid HTTP method.
409 Bookmark of the exact same userId, itemId and timestamp is already present in the database. In many cases, you may consider this code success – it only tells you that nothing has been written to the database.

Delete bookmark

DELETE
Delete bookmark
$interactions = new Interactions();
$interactions->deleteBookmark($params)
DELETE /bookmarks/

Deletes a bookmark uniquely specified by userId, itemId, and timestamp or all the bookmarks with given userId and itemId if timestamp is omitted.

Parameters
Parameter Located in Type Required Since version Description
userId query string Yes   ID of the user who made the bookmark.
itemId query string Yes   ID of the item of which was bookmarked.
timestamp query number No   Unix timestamp of the bookmark. If the timestamp is omitted, then all the bookmarks with given userId and itemId are deleted.
Responses
Response Description
200 successful operation
400 Given userId or itemId does not match ^[a-zA-Z0-9_-:]+$, or timestamp is not a real number ≥ 0.
401 Invalid or missing authentication details.
404 The userId, itemId, or bookmark with given (userId, itemId, timestamp) not found in the database. If there is no additional info in the JSON response, you probably have an error in you URL.
405 Invalid HTTP method.

List item bookmarks

GET
List item bookmarks
$interactions = new Interactions();
$interactions->listItemBookmarks($params)
GET /items/{itemId}/bookmarks/

List all the ever-made bookmarks of a given item.

Parameters
Parameter Located in Type Required Since version Description
itemId path string Yes   ID of the item of which the bookmarks are to be listed.
Responses
Response Description
200 successful operation

Example:

[
  {
    "itemId": "item-x",
    "userId": "user-a",
    "timestamp": 1348151906.0
  },
  {
    "itemId": "item-x",
    "userId": "user-a",
    "timestamp": 1348327154.0
  }
]
400 The itemId does not match ^[a-zA-Z0-9_-:]+$.
401 Invalid or missing authentication details.
404 Given itemId not found in the database. If there is no additional info in the JSON response, you probably have an error in you URL.
405 Invalid HTTP method.

List user bookmarks

GET
List user bookmarks
$interactions = new Interactions();
$interactions->listItemBookmarks($params)
GET /users/{userId}/bookmarks/

List all the bookmarks ever made by a given user.

Parameters
Parameter Located in Type Required Since version Description
userId path string Yes   ID of the user whose bookmarks are to be listed.
Responses
Response Description
200 successful operation

Example:

[
  {
    "itemId": "item-x",
    "timestamp": 1348151906.0,
    "userId": "user-a"
  },
  {
    "itemId": "item-z",
    "timestamp": 1348239363.0,
    "userId": "user-a"
  }
]
400 The userId does not match ^[a-zA-Z0-9_-:]+$.
401 Invalid or missing authentication details.
404 Given userId not found in the database. If there is no additional info in the JSON response, you probably have an error in you URL.
405 Invalid HTTP method.

View Portions

Set view portion

POST
Set view portion
$interactions = new Interactions();
$interactions->addViewPortion($params)
POST /viewportions/

Sets viewed portion of an item (for example a video or article) by a user (at a session). If you send new request with the same (userId, itemId, sessionId), the portion gets updated.

Parameters
Parameter Located in Type Required Since version Description
userId body string Yes User who viewed a portion of the item
itemId body string Yes Viewed item
portion body number Yes Viewed portion of the item (number between 0.0 (viewed nothing) and 1.0 (viewed full item) ). It should be the really viewed part of the item, no matter seeking, so for example if the user seeked immediately to half of the item and then viewed 10% of the item, the portion should still be 0.1.
sessionId body string No ID of session in which the user viewed the item. Default is null (None, nil, NULL etc. depending on language).
timestamp body string / number No UTC timestamp of the rating as ISO8601-1 pattern or UTC epoch time. The default value is the current time.
cascadeCreate body boolean No Sets whether the given user/item should be created if not present in the database.
recommId body string No If this view portion is based on a recommendation request, recommId is the id of the clicked recommendation.
Responses
Response Description
201 successful operation
400 The userId, itemId or sessionId does not match ^[a-zA-Z0-9_-:]+$, or the portion is not a real number from [0.0,1.0].
401 Invalid or missing authentication details.
404 The cascadeCreate is not set true and the userId or the itemId were found in the database. If there is no additional info in the JSON response, you probably have an error in you URL.
405 Invalid HTTP method.

Delete view portion

DELETE
Delete view portion
$interactions = new Interactions();
$interactions->deleteViewPortion($params)
DELETE /viewportions/

Deletes an existing view portion specified by (userId, itemId, sessionId) from the database.

Parameters
Parameter Located in Type Required Since version Description
userId query string Yes ID of the user who rated the item.
itemId query string Yes ID of the item which was rated.
sessionId query string No Identifier of a session.
Responses
Response Description
200 successful operation
400 Given userId, itemId or sessionId does not match ^[a-zA-Z0-9_-:]+$.
401 Invalid or missing authentication details.
404 The userId, itemId or view portion with given (userId, itemId, sessionId) not found in the database. If there is no additional info in the JSON response, you probably have an error in you URL.
405 Invalid HTTP method.

List item view portions

GET
List item view portions
$interactions = new Interactions();
$interactions->listItemViewPortions($itemID, $params)
GET /items/{itemId}/viewportions/

List all the view portions of an item ever submitted by different users.

Parameters
Parameter Located in Type Required Since version Description
itemId path string Yes ID of the item of which the view portions are to be listed.
Responses
Response Description
200 successful operation

Example:

[
  {
    "itemId": "item-x",
    "userId": "user-a",
    "sessionId": "ABAD1D",
    "portion": 0.5,
    "timestamp": 1348151906.0
  },
  {
    "itemId": "item-x",
    "userId": "user-b",
    "sessionId": null,
    "portion": 1,
    "timestamp": 1348239363.0
  }
]
400 The itemId does not match ^[a-zA-Z0-9_-:]+$.
401 Invalid or missing authentication details.
404 Given itemId not found in the database. If there is no additional info in the JSON response, you probably have an error in you URL.
405 Invalid HTTP method.

List user view portions

GET
List user view portions
$interactions = new Interactions();
$interactions->listUserViewPortions($userID, $params)
GET /users/{userId}/viewportions/

List all the view portions ever submitted by a given user.

Parameters
Parameter Located in Type Required Since version Description
userId path string Yes ID of the user whose view portions are to be listed.
Responses
Response Description
200 successful operation

Example:

[
  {
    "itemId": "item-x",
    "userId": "user-a",
    "sessionId": "ABAD1D",
    "portion": 0.25,
    "timestamp": 1348151906.0
  },
  {
    "itemId": "item-y",
    "userId": "user-a",
    "sessionId": "EWQKOL",
    "portion": 0.1,
    "timestamp": 1348239363.0
  }
]
400 The userId does not match ^[a-zA-Z0-9_-:]+$.
401 Invalid or missing authentication details.
404 Given userId not found in the database. If there is no additional info in the JSON response, you probably have an error in you URL.
405 Invalid HTTP method.

Recommendations

Recommendation methods are capable of recommending items (Recommend items to user, Recommend items to item) or users (Recommend users to item, Recommend users to user).

Recommend items to user

GET
Recommend items to user
$interactions = new Interactions();
$interactions->recommendItemsToUser($userID, $params)
GET /recomms/users/{userId}/items/

Based on user’s past interactions (purchases, ratings, etc.) with the items, recommends top-N items that are most likely to be of high value for a given user.

It is also possible to use POST HTTP method - query parameters then become body parameters.

The returned items are sorted by relevancy (first item being the most relevant).

Parameters

Parameter Located in Type Required Since version Description
userId path string Yes ID of the user for which personalized recommendations are to be generated.
count query integer Yes Number of items to be recommended (N for the top-N recommendation).
cascadeCreate query boolean No If the user does not exist in the database, returns a list of non-personalized recommendations and creates the user in the database. This allows for example rotations in the following recommendations for that user, as the user will be already known to the system.
scenario query string No Scenario defines a particular application of recommendations. It can be for example “homepage”, “cart” or “emailing”. You can see each scenario in the UI separately, so you can check how well each application performs. The AI which optimizes models in order to get the best results may optimize different scenarios separately, or even use different models in each of the scenarios.
returnProperties query boolean No
With returnProperties=true, property values of the recommended items are returned along with their IDs in a JSON dictionary. The acquired property values can be used for easy displaying of the recommended items to the user.

Example response:

{
  "recommId": "ce52ada4-e4d9-4885-943c-407db2dee837",
  "recomms":
    [
      {
        "id": "tv-178",
        "values": {
          "description": "4K TV with 3D feature",
          "categories":   ["Electronics", "Televisions"],
          "price": 342,
          "url": "myshop.com/tv-178"
        }
      },
      {
        "id": "mixer-42",
        "values": {
          "description": "Stainless Steel Mixer",
          "categories":   ["Home & Kitchen"],
          "price": 39,
          "url": "myshop.com/mixer-42"
        }
      }
    ]
}
includedProperties query array No
Allows to specify, which properties should be returned when returnProperties=true is set. The properties are given as a comma-separated list.

Example response for includedProperties=description,price:

{
  "recommId": "a86ee8d5-cd8e-46d1-886c-8b3771d0520b",
  "recomms":
    [
      {
        "id": "tv-178",
        "values": {
          "description": "4K TV with 3D feature",
          "price": 342
        }
      },
      {
        "id": "mixer-42",
        "values": {
          "description": "Stainless Steel Mixer",
          "price": 39
        }
      }
    ]
}
diversity query number No Expert option Real number from [0.0, 1.0] which determines how much mutually dissimilar should the recommended items be. The default value is 0.0, i.e., no diversification. Value 1.0 means maximal diversification.
minRelevance query string No Expert option Specifies the threshold of how much relevant must the recommended items be to the user. Possible values one of: “low”, “medium”, “high”. The default value is “low”, meaning that the system attempts to recommend number of items equal to count at any cost. If there are not enough data (such as interactions or item properties), this may even lead to bestseller-based recommendations to be appended to reach the full count. This behavior may be suppressed by using “medium” or “high” values. In such case, the system only recommends items of at least the requested relevancy, and may return less than count items when there is not enough data to fulfill it.
rotationRate query number No Expert option If your users browse the system in real-time, it may easily happen that you wish to offer them recommendations multiple times. Here comes the question: how much should the recommendations change? Should they remain the same, or should they rotate? Segmentino API allows you to control this per-request in backward fashion. You may penalize an item for being recommended in the near past. For the specific user, rotationRate=1 means maximal rotation, rotationRate=0 means absolutely no rotation. You may also use, for example rotationRate=0.2 for only slight rotation of recommended items. Default: 0.1.
rotationTime query number No Expert option Taking rotationRate into account, specifies how long time it takes to an item to recover from the penalization. For example, rotationTime=7200.0 means that items recommended less than 2 hours ago are penalized. Default: 7200.0.

Responses

Response Description
200 successful operation

Example:

{
  "recommId": "3f6ad2f2-a3f1-4ba1-a690-f4f01f76d4eb",
  "recomms": [
    {
      "id": "item-146"
    },
    {
      "id": "item-462"
    },
    {
      "id": "item-463"
    }
  ]
}
400 userId does not match ^[a-zA-Z0-9_-:]+$, count is not a positive integer.
401 Invalid or missing authentication details.
404 userId not found in the database and cascadeCreate is false. If there is no additional info in the JSON response, you probably have an error in you URL.
405 Invalid HTTP method.

Recommend users to user

GET
Recommend users to user
$interactions = new Interactions();
$interactions->recommendUsersToUser($userID, $params)
GET /recomms/users/{userId}/users/

Get similar users as some given user, based on the user’s past interactions (purchases, ratings, etc.) and values of properties.

It is also possible to use POST HTTP method - query parameters then become body parameters.

The returned users are sorted by similarity (first user being the most similar).

Parameters

Parameter Located in Type Required Since version Description
userId path string Yes User to which we find similar users
count query integer Yes Number of users to be recommended (N for the top-N recommendation).
cascadeCreate query boolean No If the user does not exist in the database, returns a list of non-personalized recommendations and creates the user in the database. This allows for example rotations in the following recommendations for that user, as the user will be already known to the system.
scenario query string No Scenario defines a particular application of recommendations. It can be for example “homepage”, “cart” or “emailing”. You can see each scenario in the UI separately, so you can check how well each application performs. The AI which optimizes models in order to get the best results may optimize different scenarios separately, or even use different models in each of the scenarios.
returnProperties query boolean No
With returnProperties=true, property values of the recommended users are returned along with their IDs in a JSON dictionary. The acquired property values can be used for easy displaying the recommended users.

Example response:

{
  "recommId": "9cb9c55d-50ba-4478-84fd-ab456136156e",
  "recomms":
    [
      {
        "id": "user-17",
        "values": {
          "country": "US",
          "sex": "F"
        }
      },
      {
        "id": "user-2",
        "values": {
          "country": "CAN",
          "sex": "M"
        }
      }
    ]
  }
includedProperties query array No
Allows to specify, which properties should be returned when returnProperties=true is set. The properties are given as a comma-separated list.

Example response for includedProperties=country:

{
  "recommId": "b326d82d-5d57-4b45-b362-c9d6f0895855",
  "recomms":
    [
      {
        "id": "user-17",
        "values": {
          "country": "US"
        }
      },
      {
        "id": "user-2",
        "values": {
          "country": "CAN"
        }
      }
    ]
}
diversity query number No Expert option Real number from [0.0, 1.0] which determines how much mutually dissimilar should the recommended users be. The default value is 0.0, i.e., no diversification. Value 1.0 means maximal diversification.
minRelevance query string No Expert option Specifies the threshold of how much relevant must the recommended users be. Possible values one of: “low”, “medium”, “high”. The default value is “low”, meaning that the system attempts to recommend number of users equal to count at any cost. If there are not enough data (such as interactions or user properties), this may even lead to bestseller-based recommendations to be appended to reach the full count. This behavior may be suppressed by using “medium” or “high” values. In such case, the system only recommends users of at least the requested relevancy, and may return less than count users when there is not enough data to fulfill it.
rotationRate query number No Expert option If your users browse the system in real-time, it may easily happen that you wish to offer them recommendations multiple times. Here comes the question: how much should the recommendations change? Should they remain the same, or should they rotate? Segmentino API allows you to control this per-request in backward fashion. You may penalize an user for being recommended in the near past. For the specific user, rotationRate=1 means maximal rotation, rotationRate=0 means absolutely no rotation. You may also use, for example rotationRate=0.2 for only slight rotation of recommended users.
rotationTime query number No Expert option Taking rotationRate into account, specifies how long time it takes to an user to recover from the penalization. For example, rotationTime=7200.0 means that users recommended less than 2 hours ago are penalized.

Responses

Response Description
200 successful operation

Example:

{
  "recommId": "f88d970d-561c-460f-b4d4-faf0478244ca",
  "recomms": [
    {
      "id": "user-64"
    },
    {
      "id": "user-42"
    },
    {
      "id": "user-23"
    }
  ]
}
400 userId does not match ^[a-zA-Z0-9_-:]+$, count is not a positive integer.
401 Invalid or missing authentication details.
404 userId not found in the database and cascadeCreate is false. If there is no additional info in the JSON response, you probably have an error in you URL.
405 Invalid HTTP method.

Recommend items to item

GET
Recommend items to item
$interactions = new Interactions();
$interactions->recommendItemsToItem($itemID, $params)
GET /recomms/items/{itemId}/items/

Recommends set of items that are somehow related to one given item, X. Typical scenario is when user A is viewing X. Then you may display items to the user that he might be also interested in. Recommend items to item request gives you Top-N such items, optionally taking the target user A into account.

It is also possible to use POST HTTP method - query parameters then become body parameters.

The returned items are sorted by relevancy (first item being the most relevant).

Parameters

Parameter Located in Type Required Since version Description
itemId path string Yes ID of the item for which the recommendations are to be generated.
targetUserId query string Yes
ID of the user who will see the recommendations.

Specifying the targetUserId is beneficial because:

  • It makes the recommendations personalized
  • Allows the calculation of Actions and Conversions in the graphical user interface, as Segmentino can pair the user who got recommendations and who afterwards viewed/purchased an item.

If you insist on not specifying the user, pass null (None, nil, NULL etc. depending on language) to targetUserId. Do not create some special dummy user for getting recommendations, as it could mislead the recommendation models, and result in wrong recommendations.

For anonymous/unregistered users it is possible to use for example their session ID.

count query integer Yes Number of items to be recommended (N for the top-N recommendation).
userImpact query number No If targetUserId parameter is present, the recommendations are biased towards the user given. Using userImpact, you may control this bias. For an extreme case of userImpact=0.0, the interactions made by the user are not taken into account at all (with the exception of history-based blacklisting), for userImpact=1.0, you’ll get user-based recommendation. The default value is 0.
cascadeCreate query boolean No If item of given itemId or user of given targetUserId doesn’t exist in the database, it creates the missing entity/entities and returns some (non-personalized) recommendations. This allows for example rotations in the following recommendations for the user of given targetUserId, as the user will be already known to the system.
scenario query string No Scenario defines a particular application of recommendations. It can be for example “homepage”, “cart” or “emailing”. You can see each scenario in the UI separately, so you can check how well each application performs. The AI which optimizes models in order to get the best results may optimize different scenarios separately, or even use different models in each of the scenarios.
returnProperties query boolean No
With returnProperties=true, property values of the recommended items are returned along with their IDs in a JSON dictionary. The acquired property values can be used for easy displaying of the recommended items to the user.

Example response:

{
  "recommId": "0c6189e7-dc1a-429a-b613-192696309361",
  "recomms":
    [
      {
        "id": "tv-178",
        "values": {
          "description": "4K TV with 3D feature",
          "categories":   ["Electronics", "Televisions"],
          "price": 342,
          "url": "myshop.com/tv-178"
        }
      },
      {
        "id": "mixer-42",
        "values": {
          "description": "Stainless Steel Mixer",
          "categories":   ["Home & Kitchen"],
          "price": 39,
          "url": "myshop.com/mixer-42"
        }
      }
    ]
}
includedProperties query array No
Allows to specify, which properties should be returned when returnProperties=true is set. The properties are given as a comma-separated list.

Example response for includedProperties=description,price:

{
  "recommId": "6842c725-a79f-4537-a02c-f34d668a3f80",
  "recomms":
    [
      {
        "id": "tv-178",
        "values": {
          "description": "4K TV with 3D feature",
          "price": 342
        }
      },
      {
        "id": "mixer-42",
        "values": {
          "description": "Stainless Steel Mixer",
          "price": 39
        }
      }
    ]
}
diversity query number No Expert option Real number from [0.0, 1.0] which determines how much mutually dissimilar should the recommended items be. The default value is 0.0, i.e., no diversification. Value 1.0 means maximal diversification.
minRelevance query string No Expert option If the targetUserId is provided: Specifies the threshold of how much relevant must the recommended items be to the user. Possible values one of: “low”, “medium”, “high”. The default value is “low”, meaning that the system attempts to recommend number of items equal to count at any cost. If there are not enough data (such as interactions or item properties), this may even lead to bestseller-based recommendations to be appended to reach the full count. This behavior may be suppressed by using “medium” or “high” values. In such case, the system only recommends items of at least the requested relevancy, and may return less than count items when there is not enough data to fulfill it.
rotationRate query number No Expert option If the targetUserId is provided: If your users browse the system in real-time, it may easily happen that you wish to offer them recommendations multiple times. Here comes the question: how much should the recommendations change? Should they remain the same, or should they rotate? Segmentino API allows you to control this per-request in backward fashion. You may penalize an item for being recommended in the near past. For the specific user, rotationRate=1 means maximal rotation, rotationRate=0 means absolutely no rotation. You may also use, for example rotationRate=0.2 for only slight rotation of recommended items.
rotationTime query number No Expert option If the targetUserId is provided: Taking rotationRate into account, specifies how long time it takes to an item to recover from the penalization. For example, rotationTime=7200.0 means that items recommended less than 2 hours ago are penalized.

Responses

Response Description
200 successful operation

Example:

{
  "recommId": "768448ea-10b3-4028-bb76-4b2f95121d19",
  "recomms": [
    {
      "id": "item-146"
    },
    {
      "id": "item-462"
    },
    {
      "id": "item-463"
    }
  ]
}
400 itemId does not match ^[a-zA-Z0-9_-:]+$, count is not a positive integer.
401 Invalid or missing authentication details.
404 itemId not found in the database and cascadeCreate is false. If there is no additional info in the JSON response, you probably have an error in you URL.
405 Invalid HTTP method.

Recommend users to item

GET
Recommend users to item
$interactions = new Interactions();
$interactions->recommendUsersToItem($userID, $params)
GET /recomms/items/{itemId}/users/

Recommend users that are likely to be interested in a given item.

It is also possible to use POST HTTP method - query parameters then become body parameters.

The returned users are sorted by predicted interest in the item (first user being the most interested).

Parameters

Parameter Located in Type Required Since version Description
itemId path string Yes ID of the item for which the recommendations are to be generated.
count query integer Yes Number of items to be recommended (N for the top-N recommendation).
cascadeCreate query boolean No If item of given itemId doesn’t exist in the database, it creates the missing item.
scenario query string No Scenario defines a particular application of recommendations. It can be for example “homepage”, “cart” or “emailing”. You can see each scenario in the UI separately, so you can check how well each application performs. The AI which optimizes models in order to get the best results may optimize different scenarios separately, or even use different models in each of the scenarios.
returnProperties query boolean No
With returnProperties=true, property values of the recommended users are returned along with their IDs in a JSON dictionary. The acquired property values can be used for easy displaying the recommended users.

Example response:

{
  "recommId": "039b71dc-b9cc-4645-a84f-62b841eecfce",
  "recomms":
    [
      {
        "id": "user-17",
        "values": {
          "country": "US",
          "sex": "F"
        }
      },
      {
        "id": "user-2",
        "values": {
          "country": "CAN",
          "sex": "M"
        }
      }
    ]
}
includedProperties query array No
Allows to specify, which properties should be returned when returnProperties=true is set. The properties are given as a comma-separated list.

Example response for includedProperties=country:

{
  "recommId": "b2b355dd-972a-4728-9c6b-2dc229db0678",
  "recomms":
    [
      {
        "id": "user-17",
        "values": {
          "country": "US"
        }
      },
      {
        "id": "user-2",
        "values": {
          "country": "CAN"
        }
      }
    ]
}
diversity query number No Expert option Real number from [0.0, 1.0] which determines how much mutually dissimilar should the recommended items be. The default value is 0.0, i.e., no diversification. Value 1.0 means maximal diversification.

Responses

Response Description
200 successful operation

Example:

{
  "recommId": "ee94fa8b-efe7-4b35-abc6-2bc3456d66ed",
  "recomms": [
    {
      "id": "user-64"
    },
    {
      "id": "user-42"
    },
    {
      "id": "user-23"
    }
  ]
}
400 itemId does not match ^[a-zA-Z0-9_-:]+$, count is not a positive integer.
401 Invalid or missing authentication details.
404 itemId not found in the database and cascadeCreate is false. If there is no additional info in the JSON response, you probably have an error in you URL.
405 Invalid HTTP method.

User based recommendation [deprecated]

  • Python example
  • Ruby example
  • Java example
  • Python example
  • Ruby example
  • Java example
  • Python example
  • Ruby example
  • Java example
  • earlgrey example
  • PHP example
  • csharp example
  • REST example
  • Python example
  • Ruby example
  • Java example
  • earlgrey example
  • PHP example
  • csharp example
  • REST example
  • Python example
  • Ruby example
  • Java example
  • earlgrey example
  • PHP example
  • csharp example
  • REST example
  • Python example
  • Ruby example
  • Java example
  • earlgrey example
  • PHP example
  • csharp example
  • REST example
  • Python example
  • Ruby example
  • Java example
  • earlgrey example
  • PHP example
  • csharp example
  • REST example
  • Python example
  • Ruby example
  • Java example
  • earlgrey example
  • PHP example
  • csharp example
  • REST example
  • Python example
  • Ruby example
  • Java example
  • earlgrey example
  • PHP example
  • csharp example
  • REST example
  • Python example
  • Ruby example
  • Java example
  • earlgrey example
  • PHP example
  • csharp example
  • REST example
  • Python example
  • Ruby example
  • Java example
  • earlgrey example
  • PHP example
  • csharp example
  • REST example
  • Python example
  • Ruby example
  • Java example
  • earlgrey example
  • PHP example
  • csharp example
  • REST example
  • Python example
  • Ruby example
  • Java example
  • earlgrey example
  • PHP example
  • csharp example
  • REST example
  • Python example
  • Ruby example
  • Java example
  • earlgrey example
  • PHP example
  • csharp example
  • REST example
  • Python example
  • Ruby example
  • Java example
  • earlgrey example
  • PHP example
  • csharp example
  • REST example
  • Python example
  • Ruby example
  • Java example
  • earlgrey example
  • PHP example
  • csharp example
  • REST example
  • Python
  • Ruby
  • Java
  • Node.js
  • PHP
  • C♯
  • REST
client.send(new rqs.UserBasedRecommendation(userId, count, { //optional parameters: 'filter': <string>, 'booster': <string>, 'cascadeCreate': <boolean>, 'scenario': <string>, 'returnProperties': <boolean>, 'includedProperties': <array>, 'diversity': <number>, 'minRelevance': <string>, 'rotationRate': <number>, 'rotationTime': <number> }), callback);

Item based recommendation [deprecated]

client.send(new rqs.ItemBasedRecommendation(itemId, count, { //optional parameters: 'targetUserId': <string>, 'userImpact': <number>, 'filter': <string>, 'booster': <string>, 'cascadeCreate': <boolean>, 'scenario': <string>, 'returnProperties': <boolean>, 'includedProperties': <array>, 'diversity': <number>, 'minRelevance': <string>, 'rotationRate': <number>, 'rotationTime': <number> }), callback);