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

eventstandardseeding
track 1200030000
retrieve 1500
batch 100500
meta-like 12000
meta-unlike 12000
discoverstandardseeding
next 9000
recommended 9000
weekly 9000
daily 9000
meta 9000
popular 15000
hot 15000
user_trend-popular 9000
user_trend-hot 9000
userstandardseeding
create 1200030000
save 12000
retrieve 18000
merge 3000
list 1000
itemstandardseeding
create 1200020000
save 1200020000
update 300012000
batch 4001200
retrieve 18000
hide 12000
unhide 12000
delete 3000
list 1000
behaviorstandardseeding
create 1500
retrieve 12000

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": 1592302340
}

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.0 optional

    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 false optional stats

    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 optional stats

    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.

$ 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"
	}'
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"
  }
)
// 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"
	}
});
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"
    }
)
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
    }
}];
{
  "success": true,
  "result": {
    "events": [
      {
        "object": "event",
        "user": "user_rlox8k927z7p",
        "item": "item_83jx4c57r2ru",
        "behavior": "purchase",
        "amount": 1.0,
        "hit": true,
        "context": ["recommended", "detail-view"],
        "created": 1592302340
      }
    ],
    "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.

$ curl https://api.tamber.com/v1/event/retrieve \
	-u Mu6DUPXdDYe98cv5JIfX: \
	-d created_before=1592302340 \
	-d created_since=1454465400 \
	-d number=300 
require 'tamber'
Tamber.project_key = 'Mu6DUPXdDYe98cv5JIfX'

Tamber::Event.retrieve(
  :created_before => 1592302340,
  :created_since =>  1454465400,
  :number => 300
)
Tamber tamber = new Tamber("Mu6DUPXdDYe98cv5JIfX", "");

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

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.retrieve(
    before=1592302340,
    since=1454465400,
    number=300
)
var tamber = require('tamber')('Mu6DUPXdDYe98cv5JIfX');

const event = await tamber.event.retrieve({
	created_before: 1592302340,
	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(1592302340),
		Since:  tamber.Int64(1454465400),
		Number: tamber.Int(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": 1592302340
      },
      ...
      {
        "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.0 optional

      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.

    • created timestamp optional

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

$ 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",
	}
]'
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'
    }
  ]
)
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',
        ),
    ]
)
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",
			},
		},
	})
}
{
  "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.0 optional

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

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

Tamber::Event.metaLike(
  :user => 'user_rlox8k927z7p',
  :property =>  'genre',
  :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'
)
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",
	})
}
{
  "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.

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

Tamber::Event.metaUnlike(
  :user => 'user_rlox8k927z7p',
  :property =>  'genre',
  :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.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'
)
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",
	})
}
{
  "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

      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.

    • 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": 1592302340
    },
    ...
    {
      "object": "event",
      "user": "user_rlox8k927z7p",
      "item": "item_wmt4fn6o4zlk",
      "behavior": "purchase",
      "amount": 1.0,
      "hit": false,
      "context": null,
      "created": 1592302340
    }
  ],
  "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": 1592302340
}

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

      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).

  • 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.

$ 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",
	}
]' 
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'
    }
  ]
)
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',
        ),
    ]
)
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",
			},
		},
	})
}
{
  "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": 1592302340
      },
      {
        "object": "event",
        "user": "user_rlox8k927z7p",
        "item": "item_wmt4fn6o4zlk",
        "behavior": "purchase",
        "amount": 1.0,
        "hit": false,
        "context": null,
        "created": 1592302340
      }
    ],
    "recommended": null,
    "metadata": {
      "city": "San Francisco, CA",
      "name": "Rob Pike"
    },
    "created": 1592302340
  },
  "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

      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).

  • get_events boolean optional

    Include the user's events in the response.


  • 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.

  • 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.

$ 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"
}'
require 'tamber'
Tamber.project_key = 'Mu6DUPXdDYe98cv5JIfX'

Tamber::User.save(
  :id => 'user_rlox8k927z7p',
  :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'
    }
)
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",
		},
	})
}
{
  "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": 1592302340
      },
      {
        "object": "event",
        "user": "user_rlox8k927z7p",
        "item": "item_wmt4fn6o4zlk",
        "behavior": "purchase",
        "amount": 1.0,
        "hit": true,
        "context": null,
        "created": 1592302340
      }
    ],
    "recommended": null,
    "metadata": {
      "city": "Mountain View, CA",
      "age": "55-65",
      "name": "Rob Pike"
    },
    "created": 1592302340
  },
  "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

    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.

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

Tamber::User.retrieve(
  :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')
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",
	})
}
{
  "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": 1592302340
      },
      {
        "object": "event",
        "user": "user_rlox8k927z7p",
        "item": "item_wmt4fn6o4zlk",
        "behavior": "purchase",
        "amount": 1.0,
        "hit": true,
        "context": null,
        "created": 1592302340
      },
      {
        "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": 1592302340
  },
  "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.

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

Tamber::User.merge(
  :from => 'user_rlox8k927z7p',
  :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')
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",
	})
}
{
  "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": 1592302340
      },
      {
        "object": "event",
        "user": "user_rlox8k927z7p",
        "item": "item_wmt4fn6o4zlk",
        "behavior": "purchase",
        "amount": 1.0,
        "hit": true,
        "context": null,
        "created": 1592302340
      },
      {
        "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": 1592302340
  },
  "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.

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

Tamber::User.list(
  :number => 1000,
  :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'})
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",
		},
	})
}
{
  "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": 1592302340
    },
    {
      "id": "user_rlox8k927z7p",
      "object": "user",
      "events": [
        {
          "object": "event",
          "user": "user_rlox8k927z7p",
          "item": "item_83jx4c57r2ru",
          "behavior": "purchase",
          "amount": 1.0,
          "hit": false,
          "context": null,
          "created": 1592302340
        },
        {
          "object": "event",
          "user": "user_rlox8k927z7p",
          "item": "item_wmt4fn6o4zlk",
          "behavior": "purchase",
          "amount": 1.0,
          "hit": true,
          "context": null,
          "created": 1592302340
        },
        {
          "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": 1592302340
    }
  ],
  "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

properties
count 1023
key length 255 characters
value length 2047 characters
tags
count 1023
tag length 2047 characters

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": 1592302340
}

Create an item

Creates a new item object.

Arguments
  • id string

    The item's unique identifier.

  • properties list 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.

$ 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=1592302340
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 => 1592302340
)
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", 1592302340);

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=1592302340
)
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: 1592302340
});
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(1592302340),
	})
}
{
  "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": 1592302340
  },
  "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

    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.

  • 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.

$ 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=1592302340 \
	-d hidden=false
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 => 1592302340
)
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", 1592302340);

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=1592302340
)
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: 1592302340
});
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(1592302340),
	})
}
{
  "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": 1592302340
  },
  "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 float, default 0

    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 string 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.

$ 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']
	}
}' \
require 'tamber'
Tamber.project_key = 'Mu6DUPXdDYe98cv5JIfX'

Tamber::Item.update(
  :id => 'item_wmt4fn6o4zlk',
  :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']
        }
)
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"},
			},
		},
	})
}
{
  "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": 1592302340
  },
  "time": 0.007280504
}

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.

  • 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
  • items list

    Batch of items to save.

    child attributes
    • 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.

  • 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.

$ 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...
]'
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"]
    }
  ]
)
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", 1592302340);
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"]
        }
    ]
)
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(1592302340),
			},
			{
				Id: "item_bmnfmjbaiwyx",
				Properties: map[string]interface{}{
					"clothing_type": "pants",
					"available_32x34": true,
					"available_32x32": false
				},
				Tags: []string{"formal"},
				Created: tamber.Int64(1454465400),
			},
		},
	})
}
{
  "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": 1592302340
    },
    {
      "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.

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

Tamber::Item.retrieve(
  :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')
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",
	})
}
{
  "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": 1592302340
  },
  "time": 0.007280504
}

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.

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

Tamber::Item.hide(
  :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')
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",
	})
}
{
  "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": 1592302340
  },
  "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.

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

Tamber::Item.unhide(
  :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')
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",
	})
}
{
  "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": 1592302340
  },
  "time": 0.007280504
}

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.

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

Tamber::Item.delete(
  :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')
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",
	})
}
{
  "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.

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

Tamber::Item.list(
  :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)
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),
	})
}
{
  "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": 1592302340
    },
    {
      "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

    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.

  • 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.

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

Tamber::Discover.next(
  :user => 'user_rlox8k927z7p',
  :item => 'item_83jx4c57r2ru',
  :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
)
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)
	})
}
{
  "success": true,
  "result": [
    {
      "item": "item_83jx4c57r2ru",
      "score": 0.94321,
      "item_created": 1592302340,
      "object": "discovery"
    },
    {
      "item": "item_znt5crzzfibh",
      "score": 0.88976,
      "item_created": 708652800,
      "object": "discovery"
    },
    ...up to 200 items per response...
  ],
  "time": 0.007280504
}

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

    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.

  • 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.

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

Tamber::Discover.weekly(
  :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'
)
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"),
		}
	)
}
{
  "success": true,
  "result": [
    {
      "item": "item_83jx4c57r2ru",
      "score": 0.94321,
      "item_created": 1592302340,
      "object": "discovery"
    },
    {
      "item": "item_znt5crzzfibh",
      "score": 0.88976,
      "item_created": 708652800,
      "object": "discovery"
    },
    ...up to 200 items per response...
  ],
  "time": 0.007280504
}

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

    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.

  • 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.

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

Tamber::Discover.daily(
  :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'
)
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"),
		}
	)
}
{
  "success": true,
  "result": [
    {
      "item": "item_83jx4c57r2ru",
      "score": 0.94321,
      "item_created": 1592302340,
      "object": "discovery"
    },
    {
      "item": "item_znt5crzzfibh",
      "score": 0.88976,
      "item_created": 708652800,
      "object": "discovery"
    },
    ...up to 200 items per response...
  ],
  "time": 0.007280504
}

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

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

  • 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

    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.

  • 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.

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

Tamber::Discover.meta(
  :property => 'genre',
  :user => 'user_rlox8k927z7p',
  :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
)
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)
	})
}
{
  "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.

$ curl https://api.tamber.com/v1/discover/hot \
	-u :SbWYPBNdARfIDa0IIO9L 
require 'tamber'
Tamber.engine_key = 'SbWYPBNdARfIDa0IIO9L'

Tamber::Discover.hot()
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()
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{})
}
{
  "success": true,
  "result": [
    {
      "item": "item_wmt4fn6o4zlk",
      "score": 0.67234,
      "item_created": 1592302340,
      "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
}

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 hot items

Get the most trending items for the given user.

Arguments
  • 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 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.

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

Tamber::Discover::UserTrend.hot(
  :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')
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"),
	})
}
{
  "success": true,
  "result": [
    {
      "item": "item_wmt4fn6o4zlk",
      "score": 0.67234,
      "item_created": 1592302340,
      "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
}

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

        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 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

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

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

Tamber::Behavior.create(
  :name => 'purchase',
  :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
)
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,
	})
}
{
  "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.

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

Tamber::Behavior.retrieve(
  :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')
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",
	})
}
{
  "success": true,
  "result": {
    "name": "purchase",
    "object": "behavior",
    "desirability": 0.6,
    "type": "exponential",
    "params": {
      "lambda": 2.0
    }
  },
  "time": 0.007280504
}

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
    ]}
  ]
}