Node.js
Ruby
Go
Python
Java
curl

Introduction

The Tamber API is organized around REST, allowing you to easily input events as they happen, and get the recommendations you want. Our API is designed for real time usage with predictable, resource-oriented URLs and HTTP response codes to indicate any API errors. All requests can be sent as either GET or POST requests, and all reponses are returned in JSON.

We have native libraries for most use cases (Go, Python, Java, Ruby, etc.) that are all built for high-performance and are open-source.

API Libraries

Libraries for the Tamber API are available in several languages.

https://api.tamber.com/v1

Authentication

In order to use the API to communicate with your Tamber Engine, you must send the associated Project key, and/or an Engine key for Discover and Behavior methods, in the request's authorization. Your Project and Engine keys are listed in your Dashboard. Your keys can be used both to write and read data, so we advise keeping them secret. Do not share your keys in publicly accessible areas such as GitHub or client-side code.

Authentication is performed via Basic Auth, with the Project key as the username, and the Engine key as the password. Most requests can be made with only a Project key - the exceptions being Discover and Behavior requests, as well as any method in which the get_recs field is set. All requests can be made with only an Engine key, as the Project will be automatically inferred.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Versioning

When backwards-incompatible changes are made to the API, a new dated version is released. You can view the version used by a Tamber Engine and upgrade to the latest version in the respective engine's Dashboard Settings. You will only need to specify a version if you would like to test a newer version of the API without doing a full upgrade.

Read our release notes to see changes and upgrades between versions.

Errors

Every response includes a boolean success value. If success is false, there will be an accompanying error message describing what went wrong.

In the case of unexpected errors, the error message will include only an error code. Please email us at support@tamber.com with this code, your engine key, and the timestamp of your API request.

Libraries

We are currently developing libraries for Go, Ruby, Python, Java, PHP, iOS, and Node.js – we will include them here as they become available.

• Node.js

• iOS

• Go

• Python

• Ruby

• Java

Rate Limits

Rate limits are applied on a per-project basis, and reset every 5 minutes. Some methods have a "seeding" limit, which allows a higher rate limit for projects that have no engines and are still seeding data.

When an application exceeds the rate limit for a given API endpoint, the API will return a HTTP 429 Too Many Requests response code.

Each method response includes HTTP headers indicating rate limit information, specific to the given method – the reset is global to all methods.

Headers

X-Rate-Limit-Limit

Request limit per period for method.

X-Rate-Limit-Remaining

Requests remaining in current window for method.

X-Rate-Limit-Reset

Time in seconds until rate limits are reset.

How to avoid rate limiting

Rate limits are designed for real time usage, where events are tracked as users perform them and recommendations are requested as users require them.

If your platform requires very high volume usage, and you need higher limits, just email us at support@tamber.com.

Rate Limits | per 5-minute window

| event | standard | seeding | | track | 12000 | 30000 | | retrieve | 1500 | | | batch | 100 | 500 | | meta-like | 12000 | | | meta-unlike | 12000 | |

| discover | standard | seeding | | next | 9000 | | | recommended | 9000 | | | weekly | 9000 | | | daily | 9000 | | | meta | 9000 | | | popular | 15000 | | | hot | 15000 | | | user_trend-popular | 9000 | | | user_trend-hot | 9000 | |

| user | standard | seeding | | create | 12000 | 30000 | | save | 12000 | | | retrieve | 18000 | | | merge | 3000 | | | list | 1000 | |

| item | standard | seeding | | create | 12000 | 20000 | | save | 12000 | 20000 | | update | 3000 | 12000 | | batch | 400 | 1200 | | retrieve | 18000 | | | hide | 12000 | | | unhide | 12000 | | | delete | 3000 | | | list | 1000 | |

Events

An event is any action someone takes in your application or on your website. The specific kind of action that the user performs is called the behavior. Note that we recommend starting out with just 1-4 behaviors - a single key metric that you would bet your company on (for Amazon this would be item purchases) and 2-3 other behaviors that allow you to more robustly gauge users' tastes.

Note that while the item field is generally required, there are some reserved behaviors that support item-less events:

• tmb_session_started

• tmb_session_ended

• tmb_push_rendered

The event object

Attributes

user string

User associated with the event.

behavior string

The unique behavior name.

item string

Item associated with the event.

amount float, default 1.0

The amount that the behavior was performed (ex. percentage of the movie that was watched, rating given, etc.). Not the same as desirability of the behavior type.

hit boolean

Boolean indicating that the event represents a successful recommendation (i.e. the item in the event was presented to the user as a recommendation).

context map

The context(s) in which the event occurred.

created timestamp

Time the event occurred.

{
  "object": "event",
  "user": "user_rlox8k927z7p",
  "item": "item_83jx4c57r2ru",
  "behavior": "purchase",
  "amount": 1.0,
  "hit": true,
  "context": {
    "page": "homepage",
    "section": "featured_section"
  },
  "created": 1592301489
}

Track an event

The track method lets you record any actions your users perform. Users and items that do not yet exist will automatically be created.

Arguments

user string or User

User associated with the event. You may supply either the unique identifier for the user, or a User Object. If using a User Object, you must set the id field.

behavior string

The unique behavior name.

item string or Item

Item associated with the event. You may supply either the unique identifier for the item, or an Item Object. If using an Item Object, you must set the id field.

amount float, default 1.0optional

The amount that the behavior was performed (ex. percentage of the movie that was watched, rating given, etc.). Not the same as desirability of the behavior type. Defaults to 1.0 if not supplied.

created timestamp optional

Time the event occurred. Defaults to the current time if not supplied.

hit boolean, default falseoptionalstats

Set to true to indicate that the event represents a successful recommendation (i.e. the item in the event was presented to the user as a recommendation).

context map optionalstats

The context(s) in which the event occurred. Useful for segmenting events data to determine the impact of interface elements and other contextual variables on user behavior. Also useful for A/B testing interface changes.

get_recs object optional

If you would like to instantly return new discover-recommended results for the user, add a get_recs request with standard optional fields (number, filter, get_properties, variability, exclude_items). Note that because all fields are optional, setting get_recs to an empty json object will return recommendations with default values.

child attributes

number int optional

The number of items to return, with the expectation that the set of items returned will be displayed to the user.

exclude_items list optional

List of items to exclude from results. Useful for hiding items that are already being displayed to the user.

variability float, default 0 optional

Apply variability to the results. Higher variability will mean the results change more between requests, and will generally be more adventurous – pulling items from a wider range of possible results.

filter map optional

A map of properties to logical filter arguments. To filter on tags, use the key "tags". Filtering on properties that do not exist will return an error.

get_properties boolean optional

Discoveries will be returned with the items' properties and tags.

var tamber = require('tamber')('Mu6DUPXdDYe98cv5JIfX');

tamber.event.track({
    user: "user_rlox8k927z7p",
    item: "item_83jx4c57r2ru",
    behavior: "purchase",
    hit: true,
    context: {
        page: "homepage",
        section: "featured_section"
    }
});

package main

import (
    tamber "github.com/tamber/tamber-go"
    "github.com/tamber/tamber-go/event"
)

func main() {
    tamber.DefaultProjectKey = "Mu6DUPXdDYe98cv5JIfX"

e, info, err := event.Track(&tamber.EventParams{
        User:     "user_rlox8k927z7p",
        Item:     "item_83jx4c57r2ru",
        Behavior: "purchase",
        Hit:	  tamber.Bool(true),
        Context:  map[string]interface{}{
            "page": "homepage",
            "section": "featured_section"
        },
    })
}

#import <Tamber/Tamber.h>

[Tamber setUser:@"user_rlox8k927z7p"];
TMBEventParams *params = [TMBEventParams eventWithItem:@"item_83jx4c57r2ru" behavior:@"purchase"];
[[Tamber client] trackEvent:params responseCompletion:^(TMBEventResponse *object, NSHTTPURLResponse *response, NSString *errorMessage) {\
    if(errorMessage){\
        // Handle error\
    }\
}];

require 'tamber'
Tamber.project_key = 'Mu6DUPXdDYe98cv5JIfX'

Tamber::Event.track(
  :user => 'user_rlox8k927z7p',
  :item =>  'item_83jx4c57r2ru',
  :behavior => 'purchase',
  :hit => true,
  :context => {
    "page": "homepage",
    "section": "featured_section"
  }
)

$ curl https://api.tamber.com/v1/event/track \
    -u Mu6DUPXdDYe98cv5JIfX: \
    -d user=user_rlox8k927z7p \
    -d item=item_83jx4c57r2ru \
    -d behavior=purchase \
    -d hit=true \
    -d context='{
        "page": "homepage",
        "section": "featured_section"
    }'

Tamber tamber = new Tamber("Mu6DUPXdDYe98cv5JIfX", "");

HashMap<String, Object> eventParams = new HashMap<String, Object>();
eventParams.put("user", "user_rlox8k927z7p");
eventParams.put("item", "item_83jx4c57r2ru");
eventParams.put("behavior", "purchase");
eventParams.put("hit", true);

HashMap<String, Object> context = new HashMap<String, Object>();
context.put("page", "detail-view");
context.put("section", "recommended");

eventParams.put("context", context);

JSONObject resp = new JSONObject();
try {
    JSONObject resp = tamber.event.track(eventParams);
} catch (TamberException e) {
    System.out.println(String.format("%s=%s", e.getClass().getName(), e.getMessage()));
}

import tamber

tamber.project_key = 'Mu6DUPXdDYe98cv5JIfX'

tamber.Event.track(
    user='user_rlox8k927z7p',
    item='item_83jx4c57r2ru',
    behavior='purchase',
    hit=True,
    context={
        "page": "detail-view",
        "section": "recommended"
    }
)

// add this to your html header
<script type="text/javascript">
    var s=document.createElement("script");s.type="text/javascript",s.src="https://js.tamber.com/1.1.0/tmb.min.js",s.async=!0,document.getElementsByTagName("head")[0].appendChild(s),s.onload=s.onreadystatechange=function(){
        window.tamber = window.tamber("Mu6DUPXdDYe98cv5JIfX");
        window.tamber.setTrackGuests(true);
    };
</script>

// call tamber
window.tamber.event.track({
    user: "user_rlox8k927z7p",
    item: "item_83jx4c57r2ru",
    behavior: "purchase",
    context: {
        "page": "homepage",
        "section": "featured_section"
    }
});

{
  "success": true,
  "result": {
    "events": [\
      {\
        "object": "event",\
        "user": "user_rlox8k927z7p",\
        "item": "item_83jx4c57r2ru",\
        "behavior": "purchase",\
        "amount": 1.0,\
        "hit": true,\
        "context": ["recommended", "detail-view"],\
        "created": 1592301489\
      }\
    ],
    "recommended": null
  },
  "time": 0.007280504
}

Retrieve events

Find events associated with a given user or item, and within a given time period. Currently, you cannot get events given both a user and an item – setting both of these fields will return an error.

Arguments

user string optional

Only return events associated with the given user.

item string optional

Only return events associated with the given item.

behavior string optional

Only return events with the given behavior.

created_since timestamp optional
created_before timestamp optional
number int optional

The number of events to return. Default is 200, Maximum is 500.

var tamber = require('tamber')('Mu6DUPXdDYe98cv5JIfX');

const event = await tamber.event.retrieve({
    created_before: 1592301489,
    created_since: 1454465400,
    number: 300
});

package main

import (
    tamber "github.com/tamber/tamber-go"
    "github.com/tamber/tamber-go/event"
)

func main() {
    tamber.DefaultProjectKey = "Mu6DUPXdDYe98cv5JIfX"

e, info, err := event.Retrieve(&tamber.EventParams{
        Before: tamber.Int64(1592301489),
        Since:  tamber.Int64(1454465400),
        Number: tamber.Int(300),
    })
}

require 'tamber'
Tamber.project_key = 'Mu6DUPXdDYe98cv5JIfX'

Tamber::Event.retrieve(
  :created_before => 1592301489,
  :created_since =>  1454465400,
  :number => 300
)

$ curl https://api.tamber.com/v1/event/retrieve \
    -u Mu6DUPXdDYe98cv5JIfX: \
    -d created_before=1592301489 \
    -d created_since=1454465400 \
    -d number=300

Tamber tamber = new Tamber("Mu6DUPXdDYe98cv5JIfX", "");

HashMap<String, Object> eventParams = new HashMap<String, Object>();
eventParams.put("created_before", 1592301489);
eventParams.put("created_since", 1454465400);
eventParams.put("number", 300);

```python
import tamber

tamber.project_key = 'Mu6DUPXdDYe98cv5JIfX'

tamber.Event.retrieve(
    before=1592301489,
    since=1454465400,
    number=300
)

{
  "success": true,
  "result": {
    "events": [\
      {\
        "object": "event",\
        "user": "user_rlox8k927z7p",\
        "item": "item_83jx4c57r2ru",\
        "behavior": "purchase",\
        "amount": 1.0,\
        "hit": true,\
        "context": ["recommended", "detail-view"],\
        "created": 1592301489\
      },\
      ...\
      {\
        "object": "event",\
        "user": "user_ujkksokcwr1k",\
        "item": "item_bmnfmjbaiwyx",\
        "behavior": "purchase",\
        "amount": 1.0,\
        "hit": false,\
        "context": null,\
        "created": 1454465400\
      }\
    ],
    "recommended": null
  },
  "time": 0.007280504
}

Batch event tracking

Track up to 1000 events in a single call.

Intended to be used in special cases, like when filling in historical data. For standard use, please stream individual events with the Track method.

Arguments

events list

Batch of events to track.

child attributes

user string

User associated with the event.

behavior string

The name of the unique behavior that the user performed on the item.

item string

Item associated with the event.

amount float, default 1.0optional
created timestamp optional

Time the event occurred. Defaults to the current time if not supplied.

var tamber = require('tamber')('Mu6DUPXdDYe98cv5JIfX');

const events = await tamber.event.batch({
    events: [{\
        user: "user_rlox8k927z7p",\
        item: "item_wmt4fn6o4zlk",\
        behavior: "purchase"\
    }, {\
        user: "user_rlox8k927z7p",\
        item: "item_83jx4c57r2ru",\
        behavior: "purchase"\
    }, {\
        user: "user_ujkksokcwr1k",\
        item: "item_83jx4c57r2ru",\
        behavior: "purchase"\
    }]
});

package main

import (
    tamber "github.com/tamber/tamber-go"
    "github.com/tamber/tamber-go/event"
)

func main() {
    tamber.DefaultProjectKey = "Mu6DUPXdDYe98cv5JIfX"

batch, info, err := event.Batch(&tamber.EventBatchParams{
        Events: []tamber.EventParams{
            tamber.EventParams{
                User:     "user_rlox8k927z7p",
                Item:     "item_wmt4fn6o4zlk",
                Behavior: "purchase",
            },
            tamber.EventParams{
                User:     "user_rlox8k927z7p",
                Item:     "item_83jx4c57r2ru",
                Behavior: "purchase",
            },
            tamber.EventParams{
                User:     "user_ujkksokcwr1k",
                Item:     "item_83jx4c57r2ru",
                Behavior: "purchase",
            },
        },
    })
}

require 'tamber'
Tamber.project_key = 'Mu6DUPXdDYe98cv5JIfX'

Tamber::Event.batch(
  :events => [\
    {\
      :user => 'user_rlox8k927z7p',\
      :item => 'item_wmt4fn6o4zlk',\
      :behavior => 'purchase'\
    },\
    {\
      :user => 'user_rlox8k927z7p',\
      :item => 'item_83jx4c57r2ru',\
      :behavior => 'purchase'\
    }\
    {\
      :user => 'user_ujkksokcwr1k',\
      :item => 'item_83jx4c57r2ru',\
      :behavior => 'purchase'\
    }\
  ]
)

$ curl https://api.tamber.com/v1/event/batch \
    -u Mu6DUPXdDYe98cv5JIfX: \
    -d events='
[\
    {\
        "user": "user_rlox8k927z7p",\
        "item": "item_wmt4fn6o4zlk",\
        "behavior": "purchase",\
    }, {\
        "user": "user_rlox8k927z7p",\
        "item": "item_83jx4c57r2ru",\
        "behavior": "purchase",\
    }, {\
        "user": "user_ujkksokcwr1k",\
        "item": "item_83jx4c57r2ru",\
        "behavior": "purchase",\
    }\
]'

Tamber tamber = new Tamber("Mu6DUPXdDYe98cv5JIfX", "");

HashMap<String, Object> eventParams = new HashMap<String, Object>();

List<HashMap<String, Object>> events = new ArrayList<HashMap<String, Object>>();
HashMap<String, Object> e1 = new HashMap<String, Object>();
e1.put("user", "user_rlox8k927z7p");
e1.put("behavior", "purchase");
e1.put("item", "item_wmt4fn6o4zlk");
events.add(e1);
HashMap<String, Object> e2 = new HashMap<String, Object>();
e2.put("user", "user_rlox8k927z7p");
e2.put("behavior", "purchase");
e2.put("item", "item_83jx4c57r2ru");
events.add(e2);
HashMap<String, Object> e3 = new HashMap<String, Object>();
e3.put("user", "user_ujkksokcwr1k");
e3.put("behavior", "purchase");
e3.put("item", "item_83jx4c57r2ru");
events.add(e3);

eventParams.put("events", events);

JSONObject resp = new JSONObject();
try {
    JSONObject resp = tamber.event.batch(eventParams);
} catch (TamberException e) {
    System.out.println(String.format("%s=%s", e.getClass().getName(), e.getMessage()));
}

import tamber

tamber.project_key = 'Mu6DUPXdDYe98cv5JIfX'

tamber.Event.batch(
    events=[\
        tamber.Event(\
            user='user_rlox8k927z7p',\
            item='item_wmt4fn6o4zlk',\
            behavior='purchase',\
        ),\
        tamber.Event(\
            user='user_rlox8k927z7p',\
            item='item_83jx4c57r2ru',\
            behavior='purchase',\
        ),\
        tamber.Event(\
            user='user_ujkksokcwr1k',\
            item='item_83jx4c57r2ru',\
            behavior='purchase',\
        ),\
    ]
)

{
  "success": true,
  "result": {
    "object": "event_batch",
    "num_batch_events": 3,
    "num_batch_users": 2,
    "num_batch_items": 2,
    "num_users_added": 1,
    "num_items_added": 1
  },
  "time": 0.007280504
}

Meta events

Meta events allow you to track the item properties and tags that each user likes. For example, in an onboarding process, you might have users select their favorite genres or categories. With meta events, these preferences are automatically incorporated into normal recommendations made to the user. You can also get recommended property and tag values for a given user and/or item with discover-meta.

Track a like

The like method lets you record any properties and tags that a user likes. For example, a user might like the value "sci-fi" for the property "genre".

Arguments

user string

User associated with the like.

property string

The unique property name.

value string, number, boolean

The value of the given property that the user likes.

amount float, default 1.0optional

The amount that the like was performed, used as a weight in recommendation generating. Defaults to 1.0 if not supplied.

var tamber = require('tamber')('Mu6DUPXdDYe98cv5JIfX');

tamber.event.meta.like({
    user: "user_rlox8k927z7p",
    property: "genre",
    value: "sci-fi"
});

package main

import (
    tamber "github.com/tamber/tamber-go"
    "github.com/tamber/tamber-go/event"
)

func main() {
    tamber.DefaultProjectKey = "Mu6DUPXdDYe98cv5JIfX"

e, info, err := event.Meta.Like(&tamber.EventMetaParams{
        User:     "user_rlox8k927z7p",
        Property: "genre",
        Value:    "sci-fi",
    })
}

require 'tamber'
Tamber.project_key = 'Mu6DUPXdDYe98cv5JIfX'

Tamber::Event.metaLike(
  :user => 'user_rlox8k927z7p',
  :property =>  'genre',
  :value => 'sci-fi'
)

$ curl https://api.tamber.com/v1/event/meta/like \
    -u Mu6DUPXdDYe98cv5JIfX: \
    -d user=user_rlox8k927z7p \
    -d property=genre \
    -d value=sci-fi

Tamber tamber = new Tamber("Mu6DUPXdDYe98cv5JIfX", "");

HashMap<String, Object> metaEventParams = new HashMap<String, Object>();
metaEventParams.put("user", "user_rlox8k927z7p");
metaEventParams.put("property", "genre");
metaEventParams.put("value", "sci-fi");

JSONObject resp = new JSONObject();
try {
    JSONObject resp = tamber.event.metaLike(metaEventParams);
} catch (TamberException e) {
    System.out.println(String.format("%s=%s", e.getClass().getName(), e.getMessage()));
}

import tamber

tamber.project_key = 'Mu6DUPXdDYe98cv5JIfX'

tamber.Event.metaLike(
    user='user_rlox8k927z7p',
    property='genre',
    value=sci-fi'
)

{
  "success": true,
  "result": {
    "property": "genre",
    "value": "sci-fi",
    "amount": 1.0
  },
  "time": 0.007280504
}

Untrack a like

Use unlike to undo a previously tracked like. This is particularly useful for cases where a user unlikes a property value, as they might do during an onboarding process.

Arguments

user string

User associated with the unlike.

property string

The unique property name.

value string, number, boolean

The value of the given property that the user unliked.

var tamber = require('tamber')('Mu6DUPXdDYe98cv5JIfX');

tamber.event.meta.unlike({
    user: "user_rlox8k927z7p",
    property: "genre",
    value: "sci-fi"
});

package main

import (
    tamber "github.com/tamber/tamber-go"
    "github.com/tamber/tamber-go/event"
)

func main() {
    tamber.DefaultProjectKey = "Mu6DUPXdDYe98cv5JIfX"

e, info, err := event.Meta.Unlike(&tamber.EventMetaParams{
        User:     "user_rlox8k927z7p",
        Property: "genre",
        Value:    "sci-fi",
    })
}

require 'tamber'
Tamber.project_key = 'Mu6DUPXdDYe98cv5JIfX'

Tamber::Event.metaUnlike(
  :user => 'user_rlox8k927z7p',
  :property =>  'genre',
  :value => 'sci-fi'
)

$ curl https://api.tamber.com/v1/event/meta/unlike \
    -u Mu6DUPXdDYe98cv5JIfX: \
    -d user=user_rlox8k927z7p \
    -d property=genre \
    -d value=sci-fi

Tamber tamber = new Tamber("Mu6DUPXdDYe98cv5JIfX", "");

JSONObject resp = new JSONObject();
try {
    JSONObject resp = tamber.event.metaUnlike(metaEventParams);
} catch (TamberException e) {
    System.out.println(String.format("%s=%s", e.getClass().getName(), e.getMessage()));
}

import tamber

tamber.project_key = 'Mu6DUPXdDYe98cv5JIfX'

tamber.Event.metaUnlike(
    user='user_rlox8k927z7p',
    property='genre',
    value=sci-fi'
)

{
  "success": true,
  "result": null,
  "time": 0.007280504
}

Users

User objects typically represent the human users in your model, though users can be anything that performs behaviors on items. The API allows you to create, update, and retrieve users. While new users are automatically added when an event is tracked, the create method is useful if your system onboards new users with a set of events and/or metadata.

The user object

Attributes

id string
object string, value is "user"
events list

A list of all of the events that are associated with the user (i.e. all passed user-item interactions).

child attributes

user string

User associated with the event..

behavior string

The name of the unique behavior that the user performed on the item.

item string

Item associated with the event.

amount float, default 1.0
created timestamp

Time the event occurred.

recommended list

A list of all items recommended to the user.

child attributes

id string

Unique identifier of the recommended item.

score float

The relative strength of the recommendation.

popularity float

The relative popularity of the recommended item.

hotness float

The relative hotness of the recommended item.

item_created timestamp
metadata map optional

Data associated with the user.

special fields

tmb_test_user boolean

Users with metadata field tmb_test_user set to true will be treated as test users, and will be able to use tamber as normal without affecting the global model of the project's engine(s).

created timestamp

{
  "id": "user_rlox8k927z7p",
  "object": "user",
  "events": [\
    {\
      "object": "event",\
      "user": "user_rlox8k927z7p",\
      "item": "item_83jx4c57r2ru",\
      "behavior": "purchase",\
      "amount": 1.0,\
      "hit": true,\
      "context": null,\
      "created": 1592301489\
    },\
    ...\
    {\
      "object": "event",\
      "user": "user_rlox8k927z7p",\
      "item": "item_wmt4fn6o4zlk",\
      "behavior": "purchase",\
      "amount": 1.0,\
      "hit": false,\
      "context": null,\
      "created": 1592301489\
    }\
  ],
  "recommended": [\
    {\
      "object": "event",\
      "item": "item_bmnfmjbaiwyx",\
      "score": 0.91297,\
      "item_created": 1454465400\
    },\
    ...\
    {\
      "object": "event",\
      "item": "item_znt5crzzfibh",\
      "score": 0.88976,\
      "item_created": 708652800\
    }\
  ],
  "metadata": {
    "city": "San Francisco, CA",
    "age": "55-65"
  },
  "created": 1592301489
}

Create a user

Creates a new user object. Note that tracking events associated with a new user will automatically create the user – you do not need to create a user before tracking events. Attempting to create a user that already exists will return an error.

We recommend only using the create method if your users sign up before performing any actions.

Arguments

id string

The unique identifier for the user.

events list optional

A list of all of the events that the new user has performed.

metadata map optional

Data associated with the user.

special fields

tmb_test_user boolean
get_recs object optional

child attributes

number int optional

The number of items to return, with the expectation that the set of items returned will be displayed to the user.

exclude_items list optional

List of items to exclude from results. Useful for hiding items that are already being displayed to the user.

variability float, default 0 optional
filter map optional

A map of properties to logical filter arguments. To filter on tags, use the key "tags". Filtering on properties that do not exist will return an error.

get_properties boolean optional

Discoveries will be returned with the items' properties and tags.

var tamber = require('tamber')('Mu6DUPXdDYe98cv5JIfX');

const user = await tamber.user.create({
    id: "user_rlox8k927z7p",
    metadata: {
        "city": "San Francisco, CA",
        "name": "Rob Pike"
    },
    events: [{\
        item: "item_83jx4c57r2ru",\
        behavior: "purchase"\
    }, {\
        item: "item_wmt4fn6o4zlk",\
        behavior: "purchase"\
    }]
});

package main

import (
    tamber "github.com/tamber/tamber-go"
    "github.com/tamber/tamber-go/user"
)

func main() {
    tamber.DefaultProjectKey = "Mu6DUPXdDYe98cv5JIfX"

u, info, err := user.Create(&tamber.UserParams{
        Id: "user_rlox8k927z7p",
        Metadata: map[string]interface{}{
            "city": "San Francisco, CA",
            "name": "Rob Pike",
        },
        Events: []tamber.EventParams{
            tamber.EventParams{
                Item:     "item_83jx4c57r2ru",
                Behavior: "purchase",
            },
            tamber.EventParams{
                Item:     "item_wmt4fn6o4zlk",
                Behavior: "purchase",
            },
        },
    })
}

require 'tamber'
Tamber.project_key = 'Mu6DUPXdDYe98cv5JIfX'

Tamber::User.create(
  :id => 'user_rlox8k927z7p',
  :metadata => {
    'city' => 'San Francisco, CA',
    'name' => 'Rob Pike'
  },
  :events => [\
    {\
      :item => 'item_wmt4fn6o4zlk',\
      :behavior => 'purchase'\
    },\
    {\
      :item => 'item_83jx4c57r2ru',\
      :behavior => 'purchase'\
    }\
  ]
)

$ curl https://api.tamber.com/v1/user/create \
    -u Mu6DUPXdDYe98cv5JIfX: \
    -d id=user_rlox8k927z7p \
    -d metadata='
{
    "city": "San Francisco, CA",
    "name": "Rob Pike"
}' \
    -d events='
[\
    {\
        "item": "item_83jx4c57r2ru",\
        "behavior": "purchase",\
    }, {\
        "item": "item_wmt4fn6o4zlk",\
        "behavior": "purchase",\
    }\
]'

Tamber tamber = new Tamber("Mu6DUPXdDYe98cv5JIfX", "");

HashMap<String, Object> userParams = new HashMap<String, Object>();
userParams.put("id", "user_rlox8k927z7p");

HashMap<String, Object> metadata = new HashMap<String, Object>();
metadata.put("city", "San Francisco, CA");
metadata.put("name", "Rob Pike");
userParams.put("metadata", metadata);

List<HashMap<String, Object>> events = new ArrayList<HashMap<String, Object>>();
HashMap<String, Object> e1 = new HashMap<String, Object>();
e1.put("behavior", "purchase");
e1.put("item", "item_83jx4c57r2ru");
events.add(e1);
HashMap<String, Object> e2 = new HashMap<String, Object>();
e2.put("behavior", "purchase");
e2.put("item", "item_wmt4fn6o4zlk");
events.add(e2);
userParams.put("events", events);

JSONObject resp = new JSONObject();
try {
    JSONObject resp = tamber.user.create(userParams);
} catch (TamberException e) {
    System.out.println(String.format("%s=%s", e.getClass().getName(), e.getMessage()));
}

import tamber

tamber.project_key = 'Mu6DUPXdDYe98cv5JIfX'

tamber.User.create(
    id='user_rlox8k927z7p',
    metadata={
        'city': 'San Francisco, CA',
        'name': 'Rob Pike'
    }
    events=[\
        tamber.Event(\
            item='item_wmt4fn6o4zlk',\
            behavior='purchase',\
        ),\
        tamber.Event(\
            item='item_83jx4c57r2ru',\
            behavior='purchase',\
        ),\
    ]
)

{
  "success": true,
  "result": {
    "id": "user_rlox8k927z7p",
    "object": "user",
    "events": [\
      {\
        "object": "event",\
        "user": "user_rlox8k927z7p",\
        "item": "item_83jx4c57r2ru",\
        "behavior": "purchase",\
        "amount": 1.0,\
        "hit": true,\
        "context": null,\
        "created": 1592301489\
      },\
      {\
        "object": "event",\
        "user": "user_rlox8k927z7p",\
        "item": "item_wmt4fn6o4zlk",\
        "behavior": "purchase",\
        "amount": 1.0,\
        "hit": false,\
        "context": null,\
        "created": 1592301489\
      }\
    ],
    "recommended": null,
    "metadata": {
      "city": "San Francisco, CA",
      "name": "Rob Pike"
    },
    "created": 1592301489
  },
  "time": 0.007280504
}

Save

Saves the specified user.

by setting the values of the parameters passed. Any parameters not provided will be left unchanged. While metadata does not affect users' recommendations, you can return fresh recommendations by setting the get_recs parameter.

Arguments

id string

The unique identifier for the user.

metadata map optional

Data associated with the user.

special fields

tmb_test_user boolean
get_events boolean optional

Include the user's events in the response.

get_recs object optional

child attributes

number int optional

The number of items to return, with the expectation that the set of items returned will be displayed to the user.

exclude_items list optional

List of items to exclude from results. Useful for hiding items that are already being displayed to the user.

variability float, default 0 optional
filter map optional

A map of properties to logical filter arguments. To filter on tags, use the key "tags". Filtering on properties that do not exist will return an error.

get_properties boolean optional

Discoveries will be returned with the items' properties and tags.

mode string, default 'replace' optional

Update operation mode. Accepts 'merge' and 'replace' modes for updating user metadata. 'merge' will add the supplied key-values to the existing user metadata (only overwriting on conflicts). 'replace' will overwrite the whole metadata object with the supplied value.

var tamber = require('tamber')('Mu6DUPXdDYe98cv5JIfX');

const user = await tamber.user.save({
    id: "user_rlox8k927z7p",
    metadata: {
        "city": "Mountain View, CA",
        "age": "55-65",
        "name": "Rob Pike"
    }
});

package main

import (
    tamber "github.com/tamber/tamber-go"
    "github.com/tamber/tamber-go/user"
)

func main() {
    tamber.DefaultProjectKey = "Mu6DUPXdDYe98cv5JIfX"

u, info, err := user.Save(&tamber.UserParams{
        Id: "user_rlox8k927z7p",
        Metadata: map[string]interface{}{
            "city": "Mountain View, CA",
            "age":  "55-65",
            "name": "Rob Pike",
        },
    })
}

require 'tamber'
Tamber.project_key = 'Mu6DUPXdDYe98cv5JIfX'

Tamber::User.save(
  :id => 'user_rlox8k927z7p',
  :metadata => {
    'city' => 'Mountain View, CA',
    'age' => '55-65',
    'name' => 'Rob Pike'
  }
)

$ curl https://api.tamber.com/v1/user/save \
    -u Mu6DUPXdDYe98cv5JIfX: \
    -d id=user_rlox8k927z7p \
    -d metadata='
{
    "city": "Mountain View, CA",
    "age": "55-65",
    "name": "Rob Pike"
}'

Tamber tamber = new Tamber("Mu6DUPXdDYe98cv5JIfX", "");

HashMap<String, Object> userParams = new HashMap<String, Object>();
userParams.put("id", "user_rlox8k927z7p");

HashMap<String, Object> metadata = new HashMap<String, Object>();
metadata.put("city", "Mountain View, CA");
metadata.put("age", "55-65");
metadata.put("name", "Rob Pike");
userParams.put("metadata", metadata);

JSONObject resp = new JSONObject();
try {
    JSONObject resp = tamber.user.save(userParams);
} catch (TamberException e) {
    System.out.println(String.format("%s=%s", e.getClass().getName(), e.getMessage()));
}

import tamber

tamber.project_key = 'Mu6DUPXdDYe98cv5JIfX'

tamber.User.save(
    id='user_rlox8k927z7p',
    metadata={
        'city': 'Mountain View, CA',
        'age':  '55-65',
        'name': 'Rob Pike'
    }
)

{
  "success": true,
  "result": {
    "id": "user_rlox8k927z7p",
    "object": "user",
    "events": [\
      {\
        "object": "event",\
        "user": "user_rlox8k927z7p",\
        "item": "item_83jx4c57r2ru",\
        "behavior": "purchase",\
        "amount": 1.0,\
        "hit": false,\
        "context": null,\
        "created": 1592301489\
      },\
      {\
        "object": "event",\
        "user": "user_rlox8k927z7p",\
        "item": "item_wmt4fn6o4zlk",\
        "behavior": "purchase",\
        "amount": 1.0,\
        "hit": true,\
        "context": null,\
        "created": 1592301489\
      }\
    ],
    "recommended": null,
    "metadata": {
      "city": "Mountain View, CA",
      "age": "55-65",
      "name": "Rob Pike"
    },
    "created": 1592301489
  },
  "time": 0.007280504
}

Retrieve a user

Retrieves the user with the supplied id.

Arguments

id string

The unique identifier for the user.

get_recs object optional

child attributes

number int optional

The number of items to return, with the expectation that the set of items returned will be displayed to the user.

exclude_items list optional

List of items to exclude from results. Useful for hiding items that are already being displayed to the user.

variability float, default 0 optional
filter map optional

A map of properties to logical filter arguments. To filter on tags, use the key "tags". Filtering on properties that do not exist will return an error.

get_properties boolean optional

Discoveries will be returned with the items' properties and tags.

var tamber = require('tamber')('Mu6DUPXdDYe98cv5JIfX');

const user = await tamber.user.retrieve({
    id: "user_rlox8k927z7p"
});

package main

import (
    tamber "github.com/tamber/tamber-go"
    "github.com/tamber/tamber-go/user"
)

func main() {
    tamber.DefaultProjectKey = "Mu6DUPXdDYe98cv5JIfX"

u, info, err := user.Retrieve(&tamber.UserParams{
        Id: "user_rlox8k927z7p",
    })
}

require 'tamber'
Tamber.project_key = 'Mu6DUPXdDYe98cv5JIfX'

Tamber::User.retrieve(
  :id => 'user_rlox8k927z7p'
)

$ curl https://api.tamber.com/v1/user/retrieve \
    -u Mu6DUPXdDYe98cv5JIfX: \
    -d id=user_rlox8k927z7p

Tamber tamber = new Tamber("Mu6DUPXdDYe98cv5JIfX", "");
HashMap<String, Object> userParams = new HashMap<String, Object>();
userParams.put("id", "user_rlox8k927z7p");

JSONObject resp = new JSONObject();
try {
    JSONObject resp = tamber.user.retrieve(userParams);
} catch (TamberException e) {
    System.out.println(String.format("%s=%s", e.getClass().getName(), e.getMessage()));
}

import tamber

tamber.project_key = 'Mu6DUPXdDYe98cv5JIfX'

tamber.User.retrieve(id='user_rlox8k927z7p')

{
  "success": true,
  "result": {
    "id": "user_rlox8k927z7p",
    "object": "user",
    "events": [\
      {\
        "object": "event",\
        "user": "user_rlox8k927z7p",\
        "item": "item_83jx4c57r2ru",\
        "behavior": "purchase",\
        "amount": 1.0,\
        "hit": false,\
        "context": null,\
        "created": 1592301489\
      },\
      {\
        "object": "event",\
        "user": "user_rlox8k927z7p",\
        "item": "item_wmt4fn6o4zlk",\
        "behavior": "purchase",\
        "amount": 1.0,\
        "hit": true,\
        "context": null,\
        "created": 1592301489\
      },\
      {\
        "object": "event",\
        "user": "user_rlox8k927z7p",\
        "item": "item_bmnfmjbaiwyx",\
        "behavior": "like",\
        "amount": 1.0,\
        "hit": false,\
        "context": null,\
        "created": 1454465400\
      }\
    ],
    "recommended": null,
    "metadata": {
      "city": "Mountain View, CA",
      "age": "55-65",
      "name": "Rob Pike"
    },
    "created": 1592301489
  },
  "time": 0.007280504
}

Merge users

Merge one user into another user. This method makes it easy to handle anonymous users who perform events before signing in. Merging removes the originating `from` user, and transfers all of the associated events and metadata to the receiving user.

Arguments

from string

The unique identifier of the user from which you are merging. This user id will no longer be valid when the merge completes.

to string

The unique identifier of the user to which you are merging. By default, if the `to` user does not yet exist it will be created.

no_create boolean optional

By default, if the `to` user does not yet exist it will be created. Setting no_create to `true` disables this behavior, and attempting to merge to a user that does not exist will return an error.

var tamber = require('tamber')('Mu6DUPXdDYe98cv5JIfX');

const toUser = await tamber.user.merge({
    from: "user_rlox8k927z7p",
    to: "user_ujkksokcwr1k"
});

package main

import (
    tamber "github.com/tamber/tamber-go"
    "github.com/tamber/tamber-go/user"
)

func main() {
    tamber.DefaultProjectKey = "Mu6DUPXdDYe98cv5JIfX"

u, info, err := user.Merge(&tamber.UserMergeParams{
        From: "user_rlox8k927z7p",
        To: "user_rlox8k927z7p",
    })
}

require 'tamber'
Tamber.project_key = 'Mu6DUPXdDYe98cv5JIfX'

Tamber::User.merge(
  :from => 'user_rlox8k927z7p',
  :to => 'user_ujkksokcwr1k'
)

$ curl https://api.tamber.com/v1/user/merge \
    -u Mu6DUPXdDYe98cv5JIfX: \
    -d from=user_rlox8k927z7p \
    -d to=user_ujkksokcwr1k

Tamber tamber = new Tamber("Mu6DUPXdDYe98cv5JIfX", "");
HashMap<String, Object> userParams = new HashMap<String, Object>();
userParams.put("from", "user_rlox8k927z7p");
userParams.put("to", "user_ujkksokcwr1k");

JSONObject resp = new JSONObject();
try {
    JSONObject resp = tamber.user.merge(userParams);
} catch (TamberException e) {
    System.out.println(String.format("%s=%s", e.getClass().getName(), e.getMessage()));
}

import tamber

tamber.project_key = 'Mu6DUPXdDYe98cv5JIfX'

tamber.User.merge(from='user_rlox8k927z7p', to='user_ujkksokcwr1k')

{
  "success": true,
  "result": {
    "id": "user_ujkksokcwr1k",
    "object": "user",
    "events": [\
      {\
        "object": "event",\
        "user": "user_rlox8k927z7p",\
        "item": "item_83jx4c57r2ru",\
        "behavior": "purchase",\
        "amount": 1.0,\
        "hit": false,\
        "context": null,\
        "created": 1592301489\
      },\
      {\
        "object": "event",\
        "user": "user_rlox8k927z7p",\
        "item": "item_wmt4fn6o4zlk",\
        "behavior": "purchase",\
        "amount": 1.0,\
        "hit": true,\
        "context": null,\
        "created": 1592301489\
      },\
      {\
        "object": "event",\
        "user": "user_rlox8k927z7p",\
        "item": "item_bmnfmjbaiwyx",\
        "behavior": "like",\
        "amount": 1.0,\
        "hit": false,\
        "context": null,\
        "created": 1454465400\
      }\
    ],
    "recommended": null,
    "metadata": {
      "city": "Mountain View, CA",
      "age": "55-65",
      "name": "Rob Pike"
    },
    "created": 1592301489
  },
  "time": 0.007280504
}

List user

Retrieves all users sorted by creation time.

Arguments

number int, default 200 optional

The number of users to return on each page, with a max of 1000.

page int optional

The page of users to return.

filter object optional

The metadata you would like to search on. The key-values are AND'd together, meaning the search will return users whose metadata contains the entirety of the given dictionary.

var tamber = require('tamber')('Mu6DUPXdDYe98cv5JIfX');

const users = await tamber.user.list({
    number: 1000,
    filter: {
        "city": "Mountain View, CA"
    }
});

package main

import (
    tamber "github.com/tamber/tamber-go"
    "github.com/tamber/tamber-go/user"
)

func main() {
    tamber.DefaultProjectKey = "Mu6DUPXdDYe98cv5JIfX"

users, info, err := user.List(&tamber.UserListParams{
        Number: tamber.Int(1000),
        Filter: map[string]interface{}{
            "city": "Mountain View, CA",
        },
    })
}

require 'tamber'
Tamber.project_key = 'Mu6DUPXdDYe98cv5JIfX'

Tamber::User.list(
  :number => 1000,
  :filter => {
    'city' => 'Mountain View, CA'
  }
)

$ curl https://api.tamber.com/v1/user/list \
    -u Mu6DUPXdDYe98cv5JIfX: \
    -d number=1000 \
    -d filter='
{
    "city": "Mountain View, CA"
}'

Tamber tamber = new Tamber("Mu6DUPXdDYe98cv5JIfX", "");
HashMap<String, Object> userParams = new HashMap<String, Object>();
userParams.put("number", 1000);
HashMap<String, Object> filter = new HashMap<String, Object>();
filter.put("city", "Mountain View, CA");
userParams.put("filter", filter);

JSONObject resp = new JSONObject();
try {
    JSONObject resp = tamber.user.list(userParams);
} catch (TamberException e) {
    System.out.println(String.format("%s=%s", e.getClass().getName(), e.getMessage()));
}

import tamber

tamber.project_key = 'Mu6DUPXdDYe98cv5JIfX'

tamber.User.list(number=1000, filter={'city': 'Mountain View, CA'})

{
  "success": true,
  "result": [\
    {\
      "id": "user_ujkksokcwr1k",\
      "object": "user",\
      "events": [\
        {\
          "object": "event",\
          "user": "user_ujkksokcwr1k",\
          "item": "item_znt5crzzfibh",\
          "behavior": "like",\
          "amount": 1.0,\
          "hit": false,\
          "context": null,\
          "created": 1454465400\
        }\
      ],\
      "recommended": null,\
      "metadata": {\
        "city": "Mountain View, CA",\
        "device_id": "7C177432-C769-4739-9DDB-3C3240C5E070"\
      },\
      "created": 1592301489\
    },\
    {\
      "id": "user_rlox8k927z7p",\
      "object": "user",\
      "events": [\
        {\
          "object": "event",\
          "user": "user_rlox8k927z7p",\
          "item": "item_83jx4c57r2ru",\
          "behavior": "purchase",\
          "amount": 1.0,\
          "hit": false,\
          "context": null,\
          "created": 1592301489\
        },\
        {\
          "object": "event",\
          "user": "user_rlox8k927z7p",\
          "item": "item_wmt4fn6o4zlk",\
          "behavior": "purchase",\
          "amount": 1.0,\
          "hit": true,\
          "context": null,\
          "created": 1592301489\
        },\
        {\
          "object": "event",\
          "user": "user_rlox8k927z7p",\
          "item": "item_bmnfmjbaiwyx",\
          "behavior": "like",\
          "amount": 1.0,\
          "hit": false,\
          "context": null,\
          "created": 1454465400\
        }\
      ],\
      "recommended": null,\
      "metadata": {\
        "city": "Mountain View, CA",\
        "age": "55-65",\
        "name": "Rob Pike"\
      },\
      "created": 1592301489\
    }\
  ],
  "time": 0.007280504
}

Item

An item is a unit of recommendation – the things you want to match with your users. For high performance applications that require recommendation filtering (ex. only recommend chinese restaurants that are currently open) at very low latency, item objects allow you to set the Properties and Tags on which Filtering operates.

Data Limits

The item object

Attributes

id string

The item's unique identifier.

properties map

Object containing the properties that the item has been assigned.

tags array of strings

A list of all of the tags that the item has been assigned.

hidden boolean optional

Boolean indicating that the item is hidden from all users.

created timestamp

{
  "id": "item_83jx4c57r2ru",
  "object": "item",
  "properties": {
    "duration_minutes": 161,
    "director": "Stanley Kubrick",
    "title": "2001: A Space Odyssey"
  },
  "tags": [\
    "sci-fi",\
    "epic"\
  ],
  "hidden": false,
  "created": 1592301489
}

Create an item

Creates a new item object.

Arguments

id string

The item's unique identifier.

properties map optional

Object containing the properties that the item has been assigned. Each property may be set to only one value, and it must be of the appropriate type for the given property.

tags array of strings optional

Array of tags assigned to the item.

hidden boolean optional

If the item should be hidden from all users and used only for model learning.

created timestamp optional

Time the item was created.

var tamber = require('tamber')('Mu6DUPXdDYe98cv5JIfX');

const item = await tamber.item.create({
    id: "item_wmt4fn6o4zlk",
    properties: {
        "clothing_type": "shirt",
        "available_small": true,
        "available_medium": true,
        "available_large": true
    },
    tags: ["casual", "preppy"],
    created: 1592301489
});

package main

import (
    tamber "github.com/tamber/tamber-go"
    "github.com/tamber/tamber-go/item"
)

func main() {
    tamber.DefaultProjectKey = "Mu6DUPXdDYe98cv5JIfX"

i, info, err := item.Create(&tamber.ItemParams{
        Id: "item_wmt4fn6o4zlk",
        Properties: map[string]interface{}{
            "clothing_type": "shirt",
            "available_small":	 true,
            "available_medium":	 true,
            "available_large":	 true,
        },
        Tags: []string{"casual", "preppy"},
        Created: tamber.Int64(1592301489),
    })
}

require 'tamber'
Tamber.project_key = 'Mu6DUPXdDYe98cv5JIfX'

Tamber::Item.create(
  :id => 'item_wmt4fn6o4zlk',
  :properties => {
    'clothing_type' => 'shirt',
    'available_small' => true,
    'available_medium' => true,
    'available_large' => true,
  },
  :tags => ['casual', 'preppy'],
  :created => 1592301489
)

$ curl https://api.tamber.com/v1/item/create \
    -u Mu6DUPXdDYe98cv5JIfX: \
    -d id=item_wmt4fn6o4zlk \
    -d properties='
{
    "clothing_type": "shirt",
    "available_small": true,
    "available_medium": true,
    "available_large": true
}' \
    -d tags='["casual", "preppy"]' \
    -d created=1592301489

Tamber tamber = new Tamber("Mu6DUPXdDYe98cv5JIfX", "");

HashMap<String, Object> itemParams = new HashMap<String, Object>();
itemParams.put("id", "item_wmt4fn6o4zlk");

HashMap<String, Object> properties = new HashMap<String, Object>();
properties.put("clothing_type", "shirt");
properties.put("available_small", true);
properties.put("available_medium", true);
properties.put("available_large", true);
itemParams.put("properties", properties);

List<String> tags = new ArrayList<String>();
tags.add("casual");
tags.add("preppy");
itemParams.put("tags", tags);

itemParams.put("created", 1592301489);

JSONObject resp = new JSONObject();
try {
    resp = tamber.item.create(itemParams);
} catch (TamberException e) {
    System.out.println(String.format("%s=%s", e.getClass().getName(), e.getMessage()));
}

import tamber

tamber.project_key = 'Mu6DUPXdDYe98cv5JIfX'

tamber.Item.create(
    id='item_wmt4fn6o4zlk',
    properties={
        'clothing_type': 'shirt',
        'available_small':	 True,
        'available_medium':	 True,
        'available_large':	 True,
    },
    tags=['casual', 'preppy'],
    created=1592301489
)

{
  "success": true,
  "result": {
    "id": "item_wmt4fn6o4zlk",
    "object": "item",
    "properties": {
      "clothing_type": "shirt",
      "available_small": true,
      "available_medium": true,
      "available_large": true
    },
    "tags": [\
      "casual",\
      "preppy"\
    ],
    "hidden": false,
    "created": 1592301489
  },
  "time": 0.007280504
}

Save an item

Saves a new item object. Conflicts where an item with the given id already exists, can be handled in either of two ways.

replace: By default, the new item overwrites the existing one.
merge: The new item is merged with the existing one, with conflicting property values being set to the new item's values.

Arguments

id string

The item's unique identifier.

properties map optional
tags array of strings optional

Array of tags assigned to the item.

hidden boolean optional

If the item should be hidden from all users and used only for model learning.

created timestamp optional

Time the item was created.

mode string, default 'replace' optional

Update operation mode. Accepts 'merge' and 'replace' modes for updating user metadata. 'replace' is the default value, and will overwrite the whole item object with the supplied value. 'merge' will update the values given for any object fields except for the properties field. The properties field's key-values will be added to the existing item properties in the same way, only overwriting on conflicts.

var tamber = require('tamber')('Mu6DUPXdDYe98cv5JIfX');

const item = await tamber.item.save({
    id: "item_wmt4fn6o4zlk",
    properties: {
        "clothing_type": "shirt",
        "available_small": true,
        "available_medium": true,
        "available_large": true
    },
    tags: ["casual", "preppy"],
    created: 1592301489
});

package main

import (
    tamber "github.com/tamber/tamber-go"
    "github.com/tamber/tamber-go/item"
)

func main() {
    tamber.DefaultProjectKey = "Mu6DUPXdDYe98cv5JIfX"

i, info, err := item.Save(&tamber.ItemSaveParams{
        Id: "item_wmt4fn6o4zlk",
        Properties: map[string]interface{}{
            "clothing_type": "shirt",
            "available_small":	 true,
            "available_medium":	 true,
            "available_large":	 true,
        },
        Tags: []string{"casual", "preppy"},
        Created: tamber.Int64(1592301489),
    })
}

require 'tamber'
Tamber.project_key = 'Mu6DUPXdDYe98cv5JIfX'

Tamber::Item.save(
  :id => 'item_wmt4fn6o4zlk',
  :properties => {
    'clothing_type' => 'shirt',
    'available_small' => true,
    'available_medium' => true,
    'available_large' => true,
  },
  :tags => ['casual', 'preppy'],
  :created => 1592301489
)

$ curl https://api.tamber.com/v1/item/save \
    -u Mu6DUPXdDYe98cv5JIfX: \
    -d id=item_wmt4fn6o4zlk \
    -d properties='
{
    "clothing_type": "shirt",
    "available_small": true,
    "available_medium": true,
    "available_large": true
}' \
    -d tags='["casual", "preppy"]' \
    -d created=1592301489 \
    -d hidden=false

Tamber tamber = new Tamber("Mu6DUPXdDYe98cv5JIfX", "");

HashMap<String, Object> itemParams = new HashMap<String, Object>();
itemParams.put("id", "item_wmt4fn6o4zlk");

List<String> tags = new ArrayList<String>();
tags.add("casual");
tags.add("preppy");
itemParams.put("tags", tags);

itemParams.put("created", 1592301489);

JSONObject resp = new JSONObject();
try {
    resp = tamber.item.save(itemParams);
} catch (TamberException e) {
    System.out.println(String.format("%s=%s", e.getClass().getName(), e.getMessage()));
}

import tamber

tamber.project_key = 'Mu6DUPXdDYe98cv5JIfX'

tamber.Item.save(
    id='item_wmt4fn6o4zlk',
    properties={
        'clothing_type': 'shirt',
        'available_small':   True,
        'available_medium':  True,
        'available_large':   True,
    },
    tags=['casual', 'preppy'],
    created=1592301489
)

{
  "success": true,
  "result": {
    "id": "item_wmt4fn6o4zlk",
    "object": "item",
    "properties": {
      "clothing_type": "shirt",
      "available_small": true,
      "available_medium": true,
      "available_large": false,
      "stock": 89
    },
    "tags": [\
      "preppy"\
    ],
    "hidden": false,
    "created": 1592301489
  },
  "time": 0.007280504
}

Update an item

Add and remove Properties and Tags.

Updates work by upsert - novel items are created, existing property values are updated to new values, and novel properties and tags are inserted into the item's properties and tags.

Arguments

id string

The item's unique identifier.

updates map

The updates field is a map that takes an 'add' field and a 'remove' field. Each of these fields takes a 'properties' and a 'tags' field. All fields are optional.

no_create boolean optional

Updates on novel items will by default result in the automatic creation of the item. Setting 'no_create' to true will prevent this behavior, and requests will return an error if an unknown item is updated.

var tamber = require('tamber')('Mu6DUPXdDYe98cv5JIfX');

const item = await tamber.item.update({
    id: "item_wmt4fn6o4zlk",
    updates: {
        add: {
            properties: {
                "available_large": false,
                "stock": 89
            }
        },
        remove: {
            tags: ["casual"]
        }
    }
});

package main

import (
    tamber "github.com/tamber/tamber-go"
    "github.com/tamber/tamber-go/item"
)

func main() {
    tamber.DefaultProjectKey = "Mu6DUPXdDYe98cv5JIfX"

i, info, err := item.Update(&tamber.ItemParams{
        Id: "item_wmt4fn6o4zlk",
        Updates: tamber.ItemUpdates{
            Add: tamber.ItemFeatures{
                Properties: map[string]interface{}{
                    "available_large":	 false,
                    "stock": 89,
                },
            },
            Remove: tamber.ItemFeatures{
                Tags: []string{"casual"},
            },
        },
    })
}

require 'tamber'
Tamber.project_key = 'Mu6DUPXdDYe98cv5JIfX'

Tamber::Item.update(
  :id => 'item_wmt4fn6o4zlk',
  :updates => {
    :add => {
      :properties => {
        'available_large' => false,
        'stock' => 89
      }
    },
    :remove => {
      :tags => [\
        'casual'\
      ]
    }
  }
)

$ curl https://api.tamber.com/v1/item/update \
    -u Mu6DUPXdDYe98cv5JIfX: \
    -d id=item_wmt4fn6o4zlk \
    -d updates='
{
    'add': {
        'properties': {
            'available_large': false,
            'stock': 89
        }
    },
    'remove': {
        'tags': ['casual']
    }
}' \

Tamber tamber = new Tamber("Mu6DUPXdDYe98cv5JIfX", "");

HashMap<String, Object> itemParams = new HashMap<String, Object>();
itemParams.put("id", "item_wmt4fn6o4zlk");

HashMap<String, Object> updates = new HashMap<String, Object>();

HashMap<String, Object> add = new HashMap<String, Object>();
HashMap<String, Object> addProperties = new HashMap<String, Object>();
addProperties.put("available_large", false);
addProperties.put("stock", 89);
add.put("properties", addProperties);
updates.put("add", add);

HashMap<String, Object> remove = new HashMap<String, Object>();
List<String> removeTags = new ArrayList<String>();
removeTags.add("casual");
remove.put("tags", removeTags);
updates.put("remove", remove);

itemParams.put("updates", updates);

JSONObject resp = new JSONObject();
try {
    resp = tamber.item.update(itemParams);
} catch (TamberException e) {
    System.out.println(String.format("%s=%s", e.getClass().getName(), e.getMessage()));
}

import tamber

tamber.project_key = 'Mu6DUPXdDYe98cv5JIfX'
tamber.Item.update(
    id='item_wmt4fn6o4zlk',
    updates={
        'add': {
            'properties': {
                'available_large': False,
                'stock': 89
            }
        },
        'remove': {
            'tags': ['casual']
        }
)

Batch item saving

Save up to 1000 items in a single call.

Conflicts where an item with the given id already exists, can be handled in either of two ways.

Arguments

items list

Batch of items to save.

child attributes

id string

The item's unique identifier.

properties map optional
tags array of strings optional

Array of tags assigned to the item.

hidden boolean optional

If the item should be hidden from all users and used only for model learning.

created timestamp optional

Time the item was created.

mode string, default 'replace' optional

var tamber = require('tamber')('Mu6DUPXdDYe98cv5JIfX');

const item = await tamber.item.batch({
    items: [\
        {\
            "id": "item_wmt4fn6o4zlk",\
            "properties": {\
                "clothing_type": "shirt",\
                "available_small": true,\
                "available_medium": true,\
                "available_large": true\
            },\
            "tags": ["casual", "preppy"]\
        },\
        {\
            "id": "item_bmnfmjbaiwyx",\
            "properties": {\
                "clothing_type": "pants",\
                "available_32x34": true,\
                "available_32x32": false\
            },\
            "tags": ["formal"]\
        }\
    ]
});

package main

import (
    tamber "github.com/tamber/tamber-go"
    "github.com/tamber/tamber-go/item"
)

func main() {
    tamber.DefaultProjectKey = "Mu6DUPXdDYe98cv5JIfX"

items, info, err := item.Save(&tamber.ItemBatchParams{
        Items: []ItemParams{
            {
                Id: "item_wmt4fn6o4zlk",
                Properties: map[string]interface{}{
                    "clothing_type": "shirt",
                    "available_small":	 true,
                    "available_medium":	 true,
                    "available_large":	 true,
                },
                Tags: []string{"casual", "preppy"},
                Created: tamber.Int64(1592301489),
            },
            {
                Id: "item_bmnfmjbaiwyx",
                Properties: map[string]interface{}{
                    "clothing_type": "pants",
                    "available_32x34": true,
                    "available_32x32": false
                },
                Tags: []string{"formal"},
                Created: tamber.Int64(1454465400),
            },
        },
    })
}

require 'tamber'
Tamber.project_key = 'Mu6DUPXdDYe98cv5JIfX'

Tamber::Item.batch(
  :items => [\
    {\
      "id": "item_wmt4fn6o4zlk",\
      "properties": {\
        "clothing_type": "shirt",\
        "available_small": true,\
        "available_medium": true,\
        "available_large": true\
      },\
      "tags": ["casual", "preppy"]\
    },\
    {\
      "id": "item_bmnfmjbaiwyx",\
      "properties": {\
        "clothing_type": "pants",\
        "available_32x34": true,\
        "available_32x32": false\
      },\
      "tags": ["formal"]\
    }\
  ]
)

$ curl https://api.tamber.com/v1/item/save \
    -u Mu6DUPXdDYe98cv5JIfX: \
    -d items='
[\
    {\
        "id": "item_wmt4fn6o4zlk",\
        "properties": {\
            "clothing_type": "shirt",\
            "available_small": true,\
            "available_medium": true,\
            "available_large": true\
        },\
        "tags": ["casual", "preppy"]\
    },\
    {\
        "id": "item_bmnfmjbaiwyx",\
        "properties": {\
            "clothing_type": "pants",\
            "available_32x34": true,\
            "available_32x32": false\
        },\
        "tags": ["formal"]\
    }\
    ...up to 1000 items per batch...\
]'

Tamber tamber = new Tamber("Mu6DUPXdDYe98cv5JIfX", "");

HashMap<String, Object> params = new HashMap<String, Object>();

List<HashMap<String, Object>> items = new ArrayList<HashMap<String, Object>>();

HashMap<String, Object> i1 = new HashMap<String, Object>();
i1.put("id", "item_wmt4fn6o4zlk");
HashMap<String, Object> properties = new HashMap<String, Object>();
properties.put("clothing_type", "shirt");
properties.put("available_small", true);
properties.put("available_medium", true);
properties.put("available_large", true);
i1.put("properties", properties);
List<String> tags = new ArrayList<String>();
tags.add("casual");
tags.add("preppy");
i1.put("tags", tags);
i1.put("created", 1592301489);
items.add(i1);

HashMap<String, Object> i2 = new HashMap<String, Object>();
i2.put("id", "item_bmnfmjbaiwyx");
HashMap<String, Object> properties = new HashMap<String, Object>();
properties.put("clothing_type", "pants");
properties.put("available_32x34", true);
properties.put("available_32x32", false);
i2.put("properties", properties);
List<String> tags = new ArrayList<String>();
tags.add("formal");
i2.put("tags", tags);
i2.put("created", 1454465400);
items.add(i2);

params.put("items", items);

JSONObject resp = new JSONObject();
try {
    JSONObject resp = tamber.item.batch(params);
} catch (TamberException e) {
    System.out.println(String.format("%s=%s", e.getClass().getName(), e.getMessage()));
}

import tamber

tamber.project_key = 'Mu6DUPXdDYe98cv5JIfX'

tamber.Item.batch(
    items=[\
        {\
            "id": "item_wmt4fn6o4zlk",\
            "properties": {\
                "clothing_type": "shirt",\
                "available_small": True,\
                "available_medium": True,\
                "available_large": True\
            },\
            "tags": ["casual", "preppy"]\
        },\
        {\
            "id": "item_bmnfmjbaiwyx",\
            "properties": {\
                "clothing_type": "pants",\
                "available_32x34": True,\
                "available_32x32": False\
            },\
            "tags": ["formal"]\
        }\
    ]
)

{
  "success": true,
  "result": [\
    {\
      "id": "item_wmt4fn6o4zlk",\
      "object": "item",\
      "properties": {\
        "clothing_type": "shirt",\
        "available_small": true,\
        "available_medium": true,\
        "available_large": false,\
        "stock": 89\
      },\
      "tags": [\
        "preppy"\
      ],\
      "hidden": false,\
      "created": 1592301489\
    },\
    {\
      "id": "item_bmnfmjbaiwyx",\
      "object": "item",\
      "properties": {\
        "clothing_type": "pants",\
        "available_32x34": true,\
        "available_32x32": false\
      },\
      "tags": [\
        "formal"\
      ],\
      "hidden": false,\
      "created": 708652800\
    }\
  ],
  "time": 0.007280504
}

Retrieve an item

Retrieves the item with the given id.

Arguments

id string

The item's unique identifier.

var tamber = require('tamber')('Mu6DUPXdDYe98cv5JIfX');

const item = await tamber.item.retrieve({
    id: "item_wmt4fn6o4zlk"
});

package main

import (
    tamber "github.com/tamber/tamber-go"
    "github.com/tamber/tamber-go/item"
)

func main() {
    tamber.DefaultProjectKey = "Mu6DUPXdDYe98cv5JIfX"

i, info, err := item.Retrieve(&tamber.ItemParams{
        Id: "item_wmt4fn6o4zlk",
    })
}

require 'tamber'
Tamber.project_key = 'Mu6DUPXdDYe98cv5JIfX'

Tamber::Item.retrieve(
  :id => 'item_wmt4fn6o4zlk'
)

$ curl https://api.tamber.com/v1/item/retrieve \
    -u Mu6DUPXdDYe98cv5JIfX: \
    -d id=item_wmt4fn6o4zlk

Tamber tamber = new Tamber("Mu6DUPXdDYe98cv5JIfX", "");

HashMap<String, Object> itemParams = new HashMap<String, Object>();
itemParams.put("id", "item_wmt4fn6o4zlk");

JSONObject resp = new JSONObject();
try {
    resp = tamber.item.retrieve(itemParams);
} catch (TamberException e) {
    System.out.println(String.format("%s=%s", e.getClass().getName(), e.getMessage()));
}

import tamber

tamber.project_key = 'Mu6DUPXdDYe98cv5JIfX'
tamber.Item.retrieve(id='item_wmt4fn6o4zlk')

Hide an item

Hides an existing item with the given identifier from users. Importantly, the relevant engines do not unlearn the item and its associated events, as its past interactions are still relevant even if the item is not.

If you would like to re-add an item that was removed, just use the unhide method with the item's unique identifier and it will automatically be reintroduced to users.

Arguments

id string

The item's unique identifier.

var tamber = require('tamber')('Mu6DUPXdDYe98cv5JIfX');

tamber.item.hide({
    id: "item_wmt4fn6o4zlk"
});

package main

import (
    tamber "github.com/tamber/tamber-go"
    "github.com/tamber/tamber-go/item"
)

func main() {
    tamber.DefaultProjectKey = "Mu6DUPXdDYe98cv5JIfX"

i, info, err := item.Hide(&tamber.ItemParams{
        Id: "item_wmt4fn6o4zlk",
    })
}

require 'tamber'
Tamber.project_key = 'Mu6DUPXdDYe98cv5JIfX'

Tamber::Item.hide(
  :id => 'item_wmt4fn6o4zlk'
)

$ curl https://api.tamber.com/v1/item/hide \
    -u Mu6DUPXdDYe98cv5JIfX: \
    -d id=item_wmt4fn6o4zlk

Tamber tamber = new Tamber("Mu6DUPXdDYe98cv5JIfX", "");

HashMap<String, Object> itemParams = new HashMap<String, Object>();
itemParams.put("id", "item_wmt4fn6o4zlk");

JSONObject resp = new JSONObject();
try {
    resp = tamber.item.hide(itemParams);
} catch (TamberException e) {
    System.out.println(String.format("%s=%s", e.getClass().getName(), e.getMessage()));
}

import tamber

tamber.project_key = 'Mu6DUPXdDYe98cv5JIfX'
tamber.Item.hide(id='item_wmt4fn6o4zlk')

{
  "success": true,
  "result": {
    "id": "item_wmt4fn6o4zlk",
    "object": "item",
    "properties": {
      "clothing_type": "shirt",
      "available_small": true,
      "available_medium": true,
      "available_large": false,
      "stock": 89
    },
    "tags": [\
      "preppy"\
    ],
    "hidden": true,
    "created": 1592301489
  },
  "time": 0.007280504
}

Unhide an item

Unhide a previously hidden item – meaning the item will be automatically re-introduce to users. It is safe to call this method on items that are not hidden.

Arguments

id string

The item's unique identifier.

var tamber = require('tamber')('Mu6DUPXdDYe98cv5JIfX');

tamber.item.unhide({
    id: "item_wmt4fn6o4zlk"
});

package main

import (
    tamber "github.com/tamber/tamber-go"
    "github.com/tamber/tamber-go/item"
)

func main() {
    tamber.DefaultProjectKey = "Mu6DUPXdDYe98cv5JIfX"

i, info, err := item.Unhide(&tamber.ItemParams{
        Id: "item_wmt4fn6o4zlk",
    })
}

require 'tamber'
Tamber.project_key = 'Mu6DUPXdDYe98cv5JIfX'

Tamber::Item.unhide(
  :id => 'item_wmt4fn6o4zlk'
)

$ curl https://api.tamber.com/v1/item/unhide \
    -u Mu6DUPXdDYe98cv5JIfX: \
    -d id=item_wmt4fn6o4zlk

Tamber tamber = new Tamber("Mu6DUPXdDYe98cv5JIfX", "");

HashMap<String, Object> itemParams = new HashMap<String, Object>();
itemParams.put("id", "item_wmt4fn6o4zlk");

JSONObject resp = new JSONObject();
try {
    resp = tamber.item.unhide(itemParams);
} catch (TamberException e) {
    System.out.println(String.format("%s=%s", e.getClass().getName(), e.getMessage()));
}

import tamber

tamber.project_key = 'Mu6DUPXdDYe98cv5JIfX'
tamber.Item.unhide(id='item_wmt4fn6o4zlk')

Delete an item

Delete an existing item with the given identifier. This is the full avada kedavra, and is intended to be used to remove items that were mistakenly added or incorrectly formatted. For other cases, like unlisting items that are out of stock, we recommend using item-hide.

Deleted items are removed entirely from your project, and are forgotten by all relevant engines. This means that the engines will not only no longer return the item in discoveries, but they will unlearn the item and any user interactions that occurred on the item.

Arguments

id string

The item's unique identifier.

var tamber = require('tamber')('Mu6DUPXdDYe98cv5JIfX');

tamber.item.delete({
    id: "item_wmt4fn6o4zlk"
});

package main

import (
    tamber "github.com/tamber/tamber-go"
    "github.com/tamber/tamber-go/item"
)

func main() {
    tamber.DefaultProjectKey = "Mu6DUPXdDYe98cv5JIfX"

i, info, err := item.Delete(&tamber.ItemParams{
        Id: "item_wmt4fn6o4zlk",
    })
}

require 'tamber'
Tamber.project_key = 'Mu6DUPXdDYe98cv5JIfX'

Tamber::Item.delete(
  :id => 'item_wmt4fn6o4zlk'
)

$ curl https://api.tamber.com/v1/item/delete \
    -u Mu6DUPXdDYe98cv5JIfX: \
    -d id=item_wmt4fn6o4zlk

Tamber tamber = new Tamber("Mu6DUPXdDYe98cv5JIfX", "");

HashMap<String, Object> itemParams = new HashMap<String, Object>();
itemParams.put("id", "item_wmt4fn6o4zlk");

JSONObject resp = new JSONObject();
try {
    resp = tamber.item.delete(itemParams);
} catch (TamberException e) {
    System.out.println(String.format("%s=%s", e.getClass().getName(), e.getMessage()));
}

import tamber

tamber.project_key = 'Mu6DUPXdDYe98cv5JIfX'
tamber.Item.delete(id='item_wmt4fn6o4zlk')

{
  "success": true,
  "result": {
    "id": "item_wmt4fn6o4zlk",
    "object": "item",
    "properties": null,
    "tags": null,
    "created": 0
  },
  "time": 0.007280504
}

List items

Retrieves all items sorted by creation time.

Arguments

number int, default 200 optional

The number of items to return on each page, with a max of 1000.

page int optional

The page of items to return.

include_hidden boolean optional

Include hidden items in results.

filter map optional

A map of properties to logical filter arguments. To filter on tags, use the key "tags". Filtering on properties that do not exist will return an error.

var tamber = require('tamber')('Mu6DUPXdDYe98cv5JIfX');

const items = await tamber.item.list({
    number: 1000
});

package main

import (
    tamber "github.com/tamber/tamber-go"
    "github.com/tamber/tamber-go/item"
)

func main() {
    tamber.DefaultProjectKey = "Mu6DUPXdDYe98cv5JIfX"

items, info, err := item.List(&tamber.ItemListParams{
        Number: tamber.Int(1000),
    })
}

require 'tamber'
Tamber.project_key = 'Mu6DUPXdDYe98cv5JIfX'

Tamber::Item.list(
  :number => 1000
)

$ curl https://api.tamber.com/v1/item/list \
    -u Mu6DUPXdDYe98cv5JIfX: \
    -d number=1000

Tamber tamber = new Tamber("Mu6DUPXdDYe98cv5JIfX", "");

HashMap<String, Object> itemParams = new HashMap<String, Object>();
itemParams.put("number", 1000);

JSONObject resp = new JSONObject();
try {
    resp = tamber.item.list(itemParams);
} catch (TamberException e) {
    System.out.println(String.format("%s=%s", e.getClass().getName(), e.getMessage()));
}

import tamber

tamber.project_key = 'Mu6DUPXdDYe98cv5JIfX'
tamber.Item.list(number=1000)

{
  "success": true,
  "result": [\
    {\
      "id": "item_wmt4fn6o4zlk",\
      "object": "item",\
      "properties": {\
        "clothing_type": "shirt",\
        "available_small": true,\
        "available_medium": true,\
        "available_large": false,\
        "stock": 89\
      },\
      "tags": [\
        "preppy"\
      ],\
      "hidden": false,\
      "created": 1592301489\
    },\
    {\
      "id": "item_83jx4c57r2ru",\
      "object": "item",\
      "properties": {\
        "duration_minutes": 161,\
        "director": "Stanley Kubrick",\
        "title": "2001: A Space Odyssey"\
      },\
      "tags": [\
        "sci-fi",\
        "epic"\
      ],\
      "hidden": false,\
      "created": 708652800\
    }\
  ],
  "time": 0.007280504
}

Discover

Discover is the core toolset of Tamber. Use discover-next to get the best set of items to display in an 'Up Next' or 'Users also viewed' section on an item page, use discover-recommended to power a personalized recommendations section on a hompeage, or discover-weekly for a personalized periodical. You can also get the most popular and the hottest items in your engine – both powerful discovery tools for new users without any events.

Features

Up Next

Recommended

Discover Weekly & Daily

Meta entities

Trending

User Trends

Up next

Get the optimal set of items to display in an 'Up Next' or 'Users also viewed' section of an item page at the current moment, and for the given user. This is the most effective way to plug discovery directly into your app.

Simply pecify the current item the user is viewing, the user's id (if they have one), and the number of items you wish to display.

Continuation

If you would like to enable infinite scrolling or a "see more" function, use the continuation parameter to automatically retrieve items to append to the current list. No complicated pagination or caching required.

You can also hide items that are already being displayed in other sections on the page by supplying the exclude_items parameter with a list of item ids.

Arguments

item string or Item

The current item (i.e. the item for which you want to recommend 'next' items). You may supply either the unique identifier for the item, or an Item Object. If using an Item Object, you must set the id field.

user string or User optional

Unique identifier for the user, or a User Object. If using a User Object, you must set the id field.

number int optional

The number of items to return, with the expectation that the set of items returned will be displayed to the user.

exclude_items list optional

List of items to exclude from results. Useful for hiding items that are already being displayed to the user.

variability float, default 0 optional
filter map optional

A map of properties to logical filter arguments. To filter on tags, use the key "tags". Filtering on properties that do not exist will return an error.

get_properties boolean optional

Discoveries will be returned with the items' properties and tags.

continuation boolean optional

Auto-continue from the last discover-next request for the given user. Allows you to 'show more' or implement infinite scrolling.

no_create string optional

Disables automatic creation of novel users and/or items. Set to user to disable user creation, item to disable item creation, or user,item to disable both user and item creation.

var tamber = require('tamber')('Mu6DUPXdDYe98cv5JIfX');

const items = await tamber.discover.next({
    user: "user_rlox8k927z7p",
    item: "item_83jx4c57r2ru",
    number: 8
});

package main

import (
    tamber "github.com/tamber/tamber-go"
    "github.com/tamber/tamber-go/discover"
    "github.com/tamber/tamber-go/item"
)

func main() {
    tamber.DefaultEngineKey = "SbWYPBNdARfIDa0IIO9L"

d, info, err := discover.Next(&tamber.DiscoverNextParams{
        User: tamber.IdString("user_rlox8k927z7p"),
        Item: &tamber.Item{
            Id: "item_83jx4c57r2ru",
            Properties: &map[string]interface{}{
                "duration": 64.5,
                "genre":    "comedy",
            },
        },
        Number: tamber.Int(8)
    })
}

require 'tamber'
Tamber.engine_key = 'SbWYPBNdARfIDa0IIO9L'

Tamber::Discover.next(
  :user => 'user_rlox8k927z7p',
  :item => 'item_83jx4c57r2ru',
  :number => 8
)

$ curl https://api.tamber.com/v1/discover/next \
    -u :SbWYPBNdARfIDa0IIO9L \
    -d user=user_rlox8k927z7p \
    -d item=item_83jx4c57r2ru \
    -d number=8

Tamber tamber = new Tamber("Mu6DUPXdDYe98cv5JIfX", "SbWYPBNdARfIDa0IIO9L");

HashMap<String, Object> discoverParams = new HashMap<String, Object>();
discoverParams.put("user", "user_rlox8k927z7p");
discoverParams.put("item", "item_83jx4c57r2ru");
discoverParams.put("number", 8);

JSONObject resp = new JSONObject();
try {
    resp = tamber.discover.next(discoverParams);
} catch (TamberException e) {
    System.out.println(String.format("%s=%s", e.getClass().getName(), e.getMessage()));
}

import tamber

tamber.engine_key = 'SbWYPBNdARfIDa0IIO9L'
tamber.Discover.next(
    user='user_rlox8k927z7p',
    item='item_83jx4c57r2ru',
    number=8
)

{
  "success": true,
  "result": [\
    {\
      "item": "item_83jx4c57r2ru",\
      "score": 0.94321,\
      "item_created": 1592301489,\
      "object": "discovery"\
    },\
    {\
      "item": "item_znt5crzzfibh",\
      "score": 0.88976,\
      "item_created": 708652800,\
      "object": "discovery"\
    },\
    ...up to 200 items per response...\
  ],
  "time": 0.007280504
}

Recommended items

Get items to show to a given user in a recommended section.

Continuation

You can also hide items that are already being displayed in other sections on the page by supplying the exclude_items parameter with a list of item ids.

Arguments

user string or User optional
number int optional

The number of items to return, with the expectation that the set of items returned will be displayed to the user.

exclude_items list optional

List of items to exclude from results. Useful for hiding items that are already being displayed to the user.

variability float, default 0 optional
filter map optional

A map of properties to logical filter arguments. To filter on tags, use the key "tags". Filtering on properties that do not exist will return an error.

get_properties boolean optional

Discoveries will be returned with the items' properties and tags.

continuation boolean optional

Auto-continue from the last discover-next request for the given user. Allows you to 'show more' or implement infinite scrolling.

no_create boolean optional

Disables automatic creation of novel users.

var tamber = require('tamber')('Mu6DUPXdDYe98cv5JIfX');

const items = await tamber.discover.recommended({
    user: "user_rlox8k927z7p"
});

package main

import (
    tamber "github.com/tamber/tamber-go"
    "github.com/tamber/tamber-go/discover"
)

func main() {
    tamber.DefaultEngineKey = "SbWYPBNdARfIDa0IIO9L"

d, info, err := discover.Recommended(
        &tamber.DiscoverRecommendedParams{
            User: tamber.IdString("user_rlox8k927z7p"),
        }
    )
}

@import Tamber;

[Tamber setPublishableProjectKey:@"your_project_key"];
[Tamber setUser:@"user_rlox8k927z7p"];

TMBDiscoverParams *params = [TMBDiscoverParams discoverRecommended:[NSNumber numberWithInt:8]];
[[Tamber client] discoverRecommended:params responseCompletion:^(TMBDiscoverResponse *object, NSHTTPURLResponse *response, NSString *errorMessage) {\
    if(errorMessage){\
        // Handle error\
    } else {\
        object.discoveries // Array of recommendations\
    }\
}];

require 'tamber'
Tamber.engine_key = 'SbWYPBNdARfIDa0IIO9L'

Tamber::Discover.recommended(
  :user => 'user_rlox8k927z7p'
)

$ curl https://api.tamber.com/v1/discover/recommended \
    -u :SbWYPBNdARfIDa0IIO9L \
    -d user=user_rlox8k927z7p

Tamber tamber = new Tamber("Mu6DUPXdDYe98cv5JIfX", "SbWYPBNdARfIDa0IIO9L");

HashMap<String, Object> discoverParams = new HashMap<String, Object>();
discoverParams.put("user", "user_rlox8k927z7p");

JSONObject resp = new JSONObject();
try {
    resp = tamber.discover.recommended(discoverParams);
} catch (TamberException e) {
    System.out.println(String.format("%s=%s", e.getClass().getName(), e.getMessage()));
}

import tamber

tamber.engine_key = 'SbWYPBNdARfIDa0IIO9L'
tamber.Discover.recommended(
    user='user_rlox8k927z7p'
)

Discover weekly beta

Build your own Spotify-style discover weekly feature. Returns a set of items recommended to the user for the week.

Results for the week will refresh each Sunday morning at 12am UTC, or at 12am at the local time of the given user if you have set the user's `tmb_timezone` metadata field (must be a location name corresponding to a file in the IANA Time Zone database, such as "America/New_York").

Arguments

user string or User optional
number int optional

The number of items to return, with the expectation that the set of items returned will be displayed to the user.

exclude_items list optional

List of items to exclude from results. Useful for hiding items that are already being displayed to the user.

filter map optional

A map of properties to logical filter arguments. To filter on tags, use the key "tags". Filtering on properties that do not exist will return an error.

get_properties boolean optional

Discoveries will be returned with the items' properties and tags.

no_create boolean optional

Disables automatic creation of novel users.

var tamber = require('tamber')('Mu6DUPXdDYe98cv5JIfX');

const items = await tamber.discover.weekly({
    user: "user_rlox8k927z7p"
});

package main

import (
    tamber "github.com/tamber/tamber-go"
    "github.com/tamber/tamber-go/discover"
)

func main() {
    tamber.DefaultEngineKey = "SbWYPBNdARfIDa0IIO9L"

d, info, err := discover.Weekly(
        &tamber.DiscoverPeriodicParams{
            User: tamber.IdString("user_rlox8k927z7p"),
        }
    )
}

require 'tamber'
Tamber.engine_key = 'SbWYPBNdARfIDa0IIO9L'

Tamber::Discover.weekly(
  :user => 'user_rlox8k927z7p'
)

$ curl https://api.tamber.com/v1/discover/weekly \
    -u :SbWYPBNdARfIDa0IIO9L \
    -d user=user_rlox8k927z7p

Tamber tamber = new Tamber("Mu6DUPXdDYe98cv5JIfX", "SbWYPBNdARfIDa0IIO9L");

HashMap<String, Object> discoverParams = new HashMap<String, Object>();
discoverParams.put("user", "user_rlox8k927z7p");

JSONObject resp = new JSONObject();
try {
    resp = tamber.discover.weekly(discoverParams);
} catch (TamberException e) {
    System.out.println(String.format("%s=%s", e.getClass().getName(), e.getMessage()));
}

import tamber

tamber.engine_key = 'SbWYPBNdARfIDa0IIO9L'
tamber.Discover.weekly(
    user='user_rlox8k927z7p'
)

Discover daily beta

Get a set of items recommended to the user for a daily periodical.

Results will refresh each morning at 12am UTC, or at 12am local time for the given user if you have set the user's `tmb_timezone` metadata field (must be a location name corresponding to a file in the IANA Time Zone database, such as "America/New_York").

Arguments

user string or User optional
number int optional

The number of items to return, with the expectation that the set of items returned will be displayed to the user.

exclude_items list optional

List of items to exclude from results. Useful for hiding items that are already being displayed to the user.

filter map optional

A map of properties to logical filter arguments. To filter on tags, use the key "tags". Filtering on properties that do not exist will return an error.

get_properties boolean optional

Discoveries will be returned with the items' properties and tags.

no_create boolean optional

Disables automatic creation of novel users.

var tamber = require('tamber')('Mu6DUPXdDYe98cv5JIfX');

const items = await tamber.discover.daily({
    user: "user_rlox8k927z7p"
});

package main

import (
    tamber "github.com/tamber/tamber-go"
    "github.com/tamber/tamber-go/discover"
)

func main() {
    tamber.DefaultEngineKey = "SbWYPBNdARfIDa0IIO9L"

d, info, err := discover.Daily(
        &tamber.DiscoverPeriodicParams{
            User: tamber.IdString("user_rlox8k927z7p"),
        }
    )
}

require 'tamber'
Tamber.engine_key = 'SbWYPBNdARfIDa0IIO9L'

Tamber::Discover.daily(
  :user => 'user_rlox8k927z7p'
)

$ curl https://api.tamber.com/v1/discover/daily \
    -u :SbWYPBNdARfIDa0IIO9L \
    -d user=user_rlox8k927z7p

Tamber tamber = new Tamber("Mu6DUPXdDYe98cv5JIfX", "SbWYPBNdARfIDa0IIO9L");

HashMap<String, Object> discoverParams = new HashMap<String, Object>();
discoverParams.put("user", "user_rlox8k927z7p");

JSONObject resp = new JSONObject();
try {
    resp = tamber.discover.daily(discoverParams);
} catch (TamberException e) {
    System.out.println(String.format("%s=%s", e.getClass().getName(), e.getMessage()));
}

import tamber

tamber.engine_key = 'SbWYPBNdARfIDa0IIO9L'
tamber.Discover.daily(
    user='user_rlox8k927z7p'
)

Meta entities

Recommend the higher-level objects represented in your items' metadata. Discover-meta allows you to retrieve recommended values for item property types, for example setting property to "genre" would return recommended genres for the given user.

You may include an item in the request to retrieve relevant property values for the given user-item pair, or exclude the user altogether to retrieve relevant values for the item alone.

Arguments

property string

The unique property name for which to recommend values.

user string or User optional
item string or Item optional

Unique identifier for the item, or an Item Object. If using an Item Object, you must set the id field.

number int optional

The number of items to return, with the expectation that the set of items returned will be displayed to the user.

variability float, default 0 optional
no_create string optional

var tamber = require('tamber')('Mu6DUPXdDYe98cv5JIfX');

const recommmendedGenres = await tamber.discover.meta({
    property: "genre",
    user: "user_rlox8k927z7p",
    number: 8
});

package main

import (
    tamber "github.com/tamber/tamber-go"
    "github.com/tamber/tamber-go/discover"
)

func main() {
    tamber.DefaultEngineKey = "SbWYPBNdARfIDa0IIO9L"

d, info, err := discover.Meta(&tamber.DiscoverMetaParams{
        Property: "genre",
        User: "user_rlox8k927z7p",
        Number: tamber.Int(8)
    })
}

require 'tamber'
Tamber.engine_key = 'SbWYPBNdARfIDa0IIO9L'

Tamber::Discover.meta(
  :property => 'genre',
  :user => 'user_rlox8k927z7p',
  :number => 8
)

$ curl https://api.tamber.com/v1/discover/meta \
    -u :SbWYPBNdARfIDa0IIO9L \
    -d property=genre \
    -d user=user_rlox8k927z7p \
    -d number=8

Tamber tamber = new Tamber("Mu6DUPXdDYe98cv5JIfX", "SbWYPBNdARfIDa0IIO9L");

HashMap<String, Object> discoverParams = new HashMap<String, Object>();
discoverParams.put("property", "genre");
discoverParams.put("user", "user_rlox8k927z7p");
discoverParams.put("number", 8);

JSONObject resp = new JSONObject();
try {
    resp = tamber.discover.meta(discoverParams);
} catch (TamberException e) {
    System.out.println(String.format("%s=%s", e.getClass().getName(), e.getMessage()));
}

import tamber

tamber.engine_key = 'SbWYPBNdARfIDa0IIO9L'
tamber.Discover.meta(
    property='genre',
    user='user_rlox8k927z7p',
    number=8
)

{
  "success": true,
  "result": [\
    {\
      "item": "fantasy",\
      "score":  0.53201,\
      "object": "discovery"\
    },\
    {\
      "item": "creative non-fiction",\
      "score": 0.34590,\
      "object": "discovery"\
    },\
    ...\
    {\
      "item": "manga",\
      "score": 0.22616,\
      "object": "discovery"\
    }\
  ],
  "time": 0.007280504
}

Hottest items

Get the most trending items in your engine. As with all Discover methods, results are paginated and you can set the number of items on each page, as well as a filter map.

Arguments

user string or User optional

Unique identifier for the current user, or a User Object. If using a User Object, you must set the id field. Providing the user does not affect results, and is only used to track the user's engagement and enable continuation.

number int optional

The number of items to return on each page.

page int optional

The page of recommended items to return. This is ignored if continuation is true.

continuation boolean optional

Auto-continue from the last discover-hot request for the given user. Allows you to 'show more' or implement infinite scrolling.

filter map optional

A map of properties to logical filter arguments. To filter on tags, use the key "tags". Filtering on properties that do not exist will return an error.

exclude_items list optional

List of items to exclude from results. Useful for hiding items that are already being displayed to the user.

get_properties boolean optional

Discoveries will be returned with the items' properties and tags.

var tamber = require('tamber')('Mu6DUPXdDYe98cv5JIfX');

const items = await tamber.discover.hot();

package main

import (
    tamber "github.com/tamber/tamber-go"
    "github.com/tamber/tamber-go/discover"
)

func main() {
    tamber.DefaultEngineKey = "SbWYPBNdARfIDa0IIO9L"

d, info, err := discover.Hot(&tamber.DiscoverBasicParams{})
}

require 'tamber'
Tamber.engine_key = 'SbWYPBNdARfIDa0IIO9L'

Tamber::Discover.hot()

$ curl https://api.tamber.com/v1/discover/hot \
    -u :SbWYPBNdARfIDa0IIO9L

Tamber tamber = new Tamber("Mu6DUPXdDYe98cv5JIfX", "SbWYPBNdARfIDa0IIO9L");

HashMap<String, Object> discoverParams = new HashMap<String, Object>();
discoverParams.put("number", 50);

JSONObject resp = new JSONObject();
try {
    resp = tamber.discover.hot(discoverParams);
} catch (TamberException e) {
    System.out.println(String.format("%s=%s", e.getClass().getName(), e.getMessage()));
}

import tamber

tamber.engine_key = 'SbWYPBNdARfIDa0IIO9L'
tamber.Discover.hot()

{
  "success": true,
  "result": [\
    {\
      "item": "item_wmt4fn6o4zlk",\
      "score": 0.67234,\
      "item_created": 1592301489,\
      "object": "discovery"\
    },\
    {\
      "item": "item_bmnfmjbaiwyx",\
      "score": 0.84447,\
      "item_created": 1454465400,\
      "object": "discovery"\
    },\
    ...\
    {\
      "item": "item_znt5crzzfibh",\
      "score": 0.59254,\
      "item_created": 708652800,\
      "object": "discovery"\
    }\
  ],
  "time": 0.007280504
}

Popular items

Get the most popular items in your engine. As with all Discover methods, results are paginated and you can set the number of items on each page, as well as a filter map.

Arguments

user string or User optional
number int optional

The number of items to return on each page.

page int optional

The page of recommended items to return. This is ignored if continuation is true.

continuation boolean optional

Auto-continue from the last discover-popular request for the given user. Allows you to 'show more' or implement infinite scrolling.

filter map optional

A map of properties to logical filter arguments. To filter on tags, use the key "tags". Filtering on properties that do not exist will return an error.

exclude_items list optional

List of items to exclude from results. Useful for hiding items that are already being displayed to the user.

get_properties boolean optional

Discoveries will be returned with the items' properties and tags.

var tamber = require('tamber')('Mu6DUPXdDYe98cv5JIfX');

const items = await tamber.discover.popular();

package main

import (
    tamber "github.com/tamber/tamber-go"
    "github.com/tamber/tamber-go/discover"
)

func main() {
    tamber.DefaultEngineKey = "SbWYPBNdARfIDa0IIO9L"

d, info, err := discover.Popular(&tamber.DiscoverBasicParams{})
}

require 'tamber'
Tamber.engine_key = 'SbWYPBNdARfIDa0IIO9L'

Tamber::Discover.popular()

$ curl https://api.tamber.com/v1/discover/popular \
    -u :SbWYPBNdARfIDa0IIO9L

Tamber tamber = new Tamber("Mu6DUPXdDYe98cv5JIfX", "SbWYPBNdARfIDa0IIO9L");

HashMap<String, Object> discoverParams = new HashMap<String, Object>();
discoverParams.put("number", 50);

JSONObject resp = new JSONObject();
try {
    resp = tamber.discover.popular(discoverParams);
} catch (TamberException e) {
    System.out.println(String.format("%s=%s", e.getClass().getName(), e.getMessage()));
}

import tamber

tamber.engine_key = 'SbWYPBNdARfIDa0IIO9L'
tamber.Discover.popular()

{
  "success": true,
  "result": [\
    {\
      "item": "item_wmt4fn6o4zlk",\
      "score": 0.34590,\
      "item_created": 1592301489,\
      "object": "discovery"\
    },\
    {\
      "item": "item_bmnfmjbaiwyx",\
      "score": 0.53201,\
      "item_created": 1454465400,\
      "object": "discovery"\
    },\
    ...\
    {\
      "item": "item_znt5crzzfibh",\
      "score": 0.72616,\
      "item_created": 708652800,\
      "object": "discovery"\
    }\
  ],
  "time": 0.007280504
}

User Trends

User Trends allows you to get single-user trends. These functions work like the global trend functions (like popular and hot), but only use behavior data from the given user.

User popular items

Get the most popular items for the given user.

Arguments

user string or User optional
number int optional

The number of items to return on each page.

continuation boolean optional

Auto-continue from the last request for the given user. Allows you to 'show more' or implement infinite scrolling.

filter map optional

A map of properties to logical filter arguments. To filter on tags, use the key "tags". Filtering on properties that do not exist will return an error.

exclude_items list optional

List of items to exclude from results. Useful for hiding items that are already being displayed to the user.

get_properties boolean optional

Discoveries will be returned with the items' properties and tags.

no_create boolean optional

Disables automatic creation of novel users.

var tamber = require('tamber')('Mu6DUPXdDYe98cv5JIfX');

const items = await tamber.discover.userPopular({
    user: "user_rlox8k927z7p"
});

package main

import (
    tamber "github.com/tamber/tamber-go"
    "github.com/tamber/tamber-go/discover"
)

func main() {
    tamber.DefaultEngineKey = "SbWYPBNdARfIDa0IIO9L"

d, info, err := discover.UserTrend.Popular(
        &tamber.DiscoverUserTrendParams{
            User: tamber.IdString("user_rlox8k927z7p"),
        }
    )
}

require 'tamber'
Tamber.engine_key = 'SbWYPBNdARfIDa0IIO9L'

Tamber::Discover::UserTrend.popular(
  :user => 'user_rlox8k927z7p'
)

$ curl https://api.tamber.com/v1/discover/user_trend/popular \
    -u :SbWYPBNdARfIDa0IIO9L \
    -d user=user_rlox8k927z7p

Tamber tamber = new Tamber("Mu6DUPXdDYe98cv5JIfX", "SbWYPBNdARfIDa0IIO9L");

HashMap<String, Object> discoverParams = new HashMap<String, Object>();
discoverParams.put("user", "user_rlox8k927z7p");
discoverParams.put("number", 50);

JSONObject resp = new JSONObject();
try {
    resp = tamber.discover.userPopular(discoverParams);
} catch (TamberException e) {
    System.out.println(String.format("%s=%s", e.getClass().getName(), e.getMessage()));
}

import tamber

tamber.engine_key = 'SbWYPBNdARfIDa0IIO9L'
tamber.Discover.userPopular(user='user_rlox8k927z7p')

User hot items

Get the most trending items for the given user.

Arguments

user string or User optional
number int optional

The number of items to return on each page.

continuation boolean optional

Auto-continue from the last request for the given user. Allows you to 'show more' or implement infinite scrolling.

filter map optional

A map of properties to logical filter arguments. To filter on tags, use the key "tags". Filtering on properties that do not exist will return an error.

exclude_items list optional

List of items to exclude from results. Useful for hiding items that are already being displayed to the user.

get_properties boolean optional

Discoveries will be returned with the items' properties and tags.

no_create boolean optional

Disables automatic creation of novel users.

var tamber = require('tamber')('Mu6DUPXdDYe98cv5JIfX');

const items = await tamber.discover.userHot({
    user: "user_rlox8k927z7p"
});

package main

import (
    tamber "github.com/tamber/tamber-go"
    "github.com/tamber/tamber-go/discover"
)

func main() {
    tamber.DefaultEngineKey = "SbWYPBNdARfIDa0IIO9L"

d, info, err := discover.UserTrend.Hot(&tamber.DiscoverUserTrendParams{
        User: tamber.IdString("user_rlox8k927z7p"),
    })
}

require 'tamber'
Tamber.engine_key = 'SbWYPBNdARfIDa0IIO9L'

Tamber::Discover::UserTrend.hot(
  :user => 'user_rlox8k927z7p'
)

$ curl https://api.tamber.com/v1/discover/user_trend/hot \
    -u :SbWYPBNdARfIDa0IIO9L \
    -d user=user_rlox8k927z7p

Tamber tamber = new Tamber("Mu6DUPXdDYe98cv5JIfX", "SbWYPBNdARfIDa0IIO9L");

HashMap<String, Object> discoverParams = new HashMap<String, Object>();
discoverParams.put("user", "user_rlox8k927z7p");
discoverParams.put("number", 50);

JSONObject resp = new JSONObject();
try {
    resp = tamber.discover.userHot(discoverParams);
} catch (TamberException e) {
    System.out.println(String.format("%s=%s", e.getClass().getName(), e.getMessage()));
}

import tamber

tamber.engine_key = 'SbWYPBNdARfIDa0IIO9L'
tamber.Discover.userHot(user='user_rlox8k927z7p')

Behaviors

Behavior objects allow you to define the kinds of events in your engine, and control how they are interpreted. We recommend starting out with just 1-4 behaviors - a single key metric that you would bet your company on (for Instagram this would be photo likes) and 2-3 other common behaviors that allow you to more robustly gauge users' tastes.

The API allows you to create and retrieve behaviors. You can also perform these actions in your dashboard.

The behavior object

Attributes

name string

Unique behavior name.

desirability float

How desirable it is for the behavior to be performed by a user. Behavior desirability is considered on a relative basis, as it compares to other behaviors.

type string

The behavior type determines how the behavior is handled.

params list

Parameters for how the behavior type should be handled. Different behavior types support different parameters.

child attributes

exponential

params

step float optional

The step (or lambda) of the exponential decay function – must be greater than 1. Determines how additional occurrences of a user's behavior on an item will be weighted. Higher values will make repeat occurrences of user-item interactions more quickly approach 0 in actual value.

step_auto boolean optional

Tamber will automatically learn an optimal step value. If neither step nor step_auto are set, then step_auto will default to true. If set to true, then step is optional.

rating

params

min float optional

The minimum amount value for the given rating behavior.

max float optional

The maximum amount value for the given rating behavior.

minmax_auto boolean optional

Tamber will automatically rescale min and max based on the values it sees. If min and/or max are set, minmax_auto will still decrease or increase these values as lower or higher values are seen in events. If neither min, max nor minmax_auto are set, then minmax_auto will default to true. If minmax_auto is set to true, then min and max are both optional. If minmax_auto is not set or is set to false, then both min and max fields must be set.

chi-squared

params

k float

The degrees of freedom of the chi-squared distribution. Determines how additional occurrences of a user's behavior on an item will be weighted.

created timestamp

{
  "name": "like",
  "object": "behavior",
  "desirability": 0.5,
  "type": "exponential",
  "params": {
    "lambda": 2.0
  }
}

Create a behavior

Creates a behavior object with the given name, desirability, type, and relevant parameters.

Arguments

name string

Unique behavior name.

desirability float

How desirable it is for the behavior to be performed by a user. Behavior desirability is considered on a relative basis, as it compares to other behaviors.

type string optional

The behavior type determines how the behavior is handled. Defaults to 'exponential' if not supplied.

params list

Parameters for how the behavior type should be handled. Different behavior types support different parameters.

child attributes

exponential

params

step float optional
step_auto boolean optional
rating

params

min float optional

The minimum value for the given rating behavior.

max float optional

The maximum value for the given rating behavior.

minmax_auto boolean optional

Tamber will automatically rescale min and max based on the values it sees. If min and/or max are set, minmax_auto will still decrease or increase these values as lower or higher values are seen in events. If neither min, max nor minmax_auto are set, then minmax_auto will default to true. If step_auto is set to true, then min and max are both optional. If minmax_auto is not set or is set to false, then both min and max fields must be set.

chi-squared

params

k float

var tamber = require('tamber')('Mu6DUPXdDYe98cv5JIfX');

const behavior = await tamber.behavior.create({
    name: "purchase",
    desirability: 0.6
});

package main

import (
    tamber "github.com/tamber/tamber-go"
    "github.com/tamber/tamber-go/behavior"
)

func main() {
    tamber.DefaultEngineKey = "SbWYPBNdARfIDa0IIO9L"

b, info, err := behavior.Create(&tamber.BehaviorParams{
        Name: "purchase",
        Desirability: 0.6,
    })
}

require 'tamber'
Tamber.engine_key = 'SbWYPBNdARfIDa0IIO9L'

Tamber::Behavior.create(
  :name => 'purchase',
  :desirability => 0.6
)

$ curl https://api.tamber.com/v1/behavior/create \
    -u :SbWYPBNdARfIDa0IIO9L \
    -d name=purchase \
    -d desirability=0.6

Tamber tamber = new Tamber("Mu6DUPXdDYe98cv5JIfX", "SbWYPBNdARfIDa0IIO9L");

HashMap<String, Object> behaviorParams = new HashMap<String, Object>();
behaviorParams.put("name", "purchase");
behaviorParams.put("desirability", 0.6);

JSONObject resp = new JSONObject();
try {
    resp = tamber.behavior.create(behaviorParams);
} catch (TamberException e) {
    System.out.println(String.format("%s=%s", e.getClass().getName(), e.getMessage()));
}

import tamber

tamber.engine_key = 'SbWYPBNdARfIDa0IIO9L'
tamber.Behavior.create(
    name='purchase',
    desirability=0.6
)

{
  "success": true,
  "result": {
    "name": "purchase",
    "object": "behavior",
    "desirability": 0.6,
    "type": "exponential",
    "params": {
      "lambda": 2.0
    }
  },
  "time": 0.007280504
}

Retrieve a behavior

Retrieves the behavior with the given name.

Arguments

name string

Unique behavior name.

var tamber = require('tamber')('Mu6DUPXdDYe98cv5JIfX');

const behavior = await tamber.behavior.retrieve({
    name: "purchase"
});

package main

import (
    tamber "github.com/tamber/tamber-go"
    "github.com/tamber/tamber-go/behavior"
)

func main() {
    tamber.DefaultEngineKey = "SbWYPBNdARfIDa0IIO9L"

b, info, err := behavior.Retrieve(&tamber.BehaviorParams{
        Name: "purchase",
    })
}

require 'tamber'
Tamber.engine_key = 'SbWYPBNdARfIDa0IIO9L'

Tamber::Behavior.retrieve(
  :name => 'purchase'
)

$ curl https://api.tamber.com/v1/behavior/retrieve \
    -u :SbWYPBNdARfIDa0IIO9L \
    -d name=purchase

Tamber tamber = new Tamber("Mu6DUPXdDYe98cv5JIfX", "SbWYPBNdARfIDa0IIO9L");

HashMap<String, Object> behaviorParams = new HashMap<String, Object>();
behaviorParams.put("name", "purchase");

JSONObject resp = new JSONObject();
try {
    resp = tamber.behavior.retrieve(behaviorParams);
} catch (TamberException e) {
    System.out.println(String.format("%s=%s", e.getClass().getName(), e.getMessage()));
}

import tamber

tamber.engine_key = 'SbWYPBNdARfIDa0IIO9L'
tamber.Behavior.retrieve(name='purchase')

Data Formatting

If you have existing data, you can use it to train your recommendation engine before deploying personalization in your app. The historical data Tamber uses to learn is the record of all past user interactions (events).

Events Dataset

The events dataset is a list of all past events that users have performed on your platform (or in the dataset that you would like to generate recommendations from). It can be uploaded as either a CSV, or gzipped CSV file. Be sure that the file name extension includes '.csv'.

The required columns are user, item, behavior, amount, and created. You may optionally include a context column (with stringified json as its value).

You may include a header, or provide values in the order listed above.

user,item,behavior,amount,created
user_rlox8k927z7p,item_83jx4c57r2ru,purchase,1.0,1591331679

user,item,behavior,amount,created,context
user_rlox8k927z7p,item_83jx4c57r2ru,purchase,1.0,1591331679,"{""client"": [""iPhone"", ""ios"", ""device_phone""]}"

Items Dataset

The items dataset is a list of all existing items in your database. It can be uploaded as a JSON file. Be sure that the file name extension includes '.json'.

[\
    {\
        "id": "item_83jx4c57r2ru",\
        "properties": {\
            "type": "book",\
            "title": "The Moon is a Harsh Mistress",\
            "img": "https://img.domain.com/book/The_Moon_is_a_Harsh Mistress.jpg"\
        },\
        "tags": ["sci-fi", "bestseller"],\
        "created": 1591331679\
    },\
    ...\
]

Behavior Controls

Traditionally, recommender systems have focused on explicit ratings that users assign to each item. But user ratings are only a small part of the picture that we are trying to paint. The goal is for a user to click a link, love a new shirt, watch a movie – not rate them for rating's sake.

Tamber is designed to use the actual behaviors users perform because they are what matter fundamentally. Better yet, users do not have to do anything special to get recommendations – it just happens. To accomplish this, Tamber combines algorithms that learn users' unique preferences for behaviors with desirability scores that you assign. A desirability score should indicate how well the behavior aligns with your high level goals. For example, users might generally prefer to 'like' clothing items, but a 'share' has a higher desirability score because it brings more new users to your site.

In addition to desirability scores, behaviors are also assigned a type – either Rating, Exponential Decay, or Chi-Squared Decay. These types determine how the behavior is treated by Tamber. For the two decay functions, the slope of the Cumulative Distribution Function is used to determine the decay applied to repeat occurances of the given behavior for the same user-item pair. An extra parameter is supplied to determine the shape of the decay curve – the lambda value for the Exponential distribution, and k for Chi-Squared.

You can create new behaviors from your dashboard in your engine's control section, or using the behavior methods below.

Filtering

Read our guide for instructions.

The perfect restaurant recommendation is not only one the user will love, it is also one that is open. To solve conditional problems like this, Tamber gives you the most powerful filter on the web.

Tamber's filtering tool allows you to form complex logical phrases, which can even operate across properties. Want to only recommend tshirts where sales_count > returns_count? Bicycle routes where either the average duration is less than 30 minutes or the max incline is less than 5 degrees? Maybe the user also wants to go at least 15 miles? Tamber can efficiently handle even the most elaborate filters, so your users can always see just the things they are looking for, and nothing more.

How it works

Filters are composed in JSON. Logical and Comparison Operators are keys with arrays as values. Operators 'join' all of the values in this array. Most programming languages use infix notation, where operators appear between values (ex. a && b && c), but here the operator is prefixed (ex. && [a, b, c]). Logical Operators can prefix an arbitrary number of boolean statements, but Comparison Operators must evaluate 2 statements. These statements are typically an item property and a value, but can also be two item properties. Item properties are objects with key 'property' and value the name of the item property.

Logical Operators

and, or, not

Comparison Operators

eq, neq, gt, gte, lt, lte

Array Operators

contains, overlaps

Filter Example

Recommended items where the CLOTHING_TYPE == SUITS and JACKET_COLOR != PANTS_COLOR and WAIST_SIZE in range (35 - 41].

{
  "and": [\
    {"eq": [\
      {"property": "clothing_type"},\
      "suit"\
    ]},\
    {"neq": [\
      {"property": "jacket_color"},\
      {"property": "pant_color"}\
    ]},\
    {"gt": [\
      {"property": "waist_size"},\
      35\
    ]},\
    {"lte": [\
      {"property": "waist_size"},\
      41\
    ]}\
  ]
}

Trends

Trends allows you to find the hottest and the most popular items on your platform in real time. Our analysis is based on up-to-the-millisecond user data, and our proprietary prediction algorithms. As with recommendations, these stats are fully filterable and accessible through the Discover API endpoint.

Introduction

API Libraries

Authentication

Versioning

Errors

Libraries

Rate Limits

Headers

How to avoid rate limiting

Rate Limits | per 5-minute window

Events

The event object

Attributes

user string

behavior string

item string

amount float, default 1.0

hit boolean

context map

created timestamp

Track an event

Arguments

user string or User

behavior string

item string or Item

amount float, default 1.0optional

created timestamp optional

hit boolean, default falseoptionalstats

context map optionalstats

get_recs object optional

child attributes

number int optional

exclude_items list optional

variability float, default 0 optional

filter map optional

get_properties boolean optional

Retrieve events

Arguments

user string optional

item string optional

behavior string optional

created_since timestamp optional

created_before timestamp optional

number int optional

Batch event tracking

Arguments

events list

child attributes

user string

behavior string

item string

amount float, default 1.0optional

created timestamp optional

Meta events

Track a like

Arguments

user string

property string

value string, number, boolean

amount float, default 1.0optional

Untrack a like

Arguments

user string

property string

value string, number, boolean

Users

The user object

Attributes

id string

object string, value is "user"

events list

child attributes

user string

behavior string

item string

amount float, default 1.0

created timestamp

recommended list

child attributes

id string