The Tumbz API for Developers' doc, one-pager to get you quickly started

Tumbz REST API Documentation

Below you'll find code samples and information that will teach you how to use The Tumbz API.

Access to the Tumbz API

Use of our API is restricted through API keys.

To be able to code an application using the Tumbz API, contact us for you private key by email at info 'at' tum.bz

Note that a demo api key is provided in the code samples below. This key should not be used in your application's environment as it has a limited quota of requests per hour.

About our API

The Tumbz API follows the basic REST principles. If you plan on building something and would need access to options that are not available right now, please let us know and we'll get in touch.

Responses are sent in JSON format by default, but can be converted to XML simply by adding ".xml" to the resource name your requesting in the url.

Resources available through the API:

For a list of the current possible calls and options, see below.

Getting started: Quick example

Here's a quick Ruby example

# using basic stuff... require 'net/http' require 'json' ### HOW TO: Get a list of users ### # add your own apikey in the url params url = 'http://api.tum.bz/v1/users?limit=3&apikey=nzaEhGbo4B9yAOn1GKveoSL003sexY9F' resp = Net::HTTP.get_response(URI.parse(url)) usersList = JSON.parse(resp.body) # here you have a converted JSON array easy to work with usersList.each do |user| # you can loop on each item in the array puts user['username'] # Get movies in user's watch later list url = 'http://api.tum.bz/v1/products?in_later_list_of_user='+user['username']+'&apikey=nzaEhGbo4B9yAOn1GKveoSL003sexY9F' resp = Net::HTTP.get_response(URI.parse(url)) laterList = JSON.parse(resp.body) laterList.each do |product| puts product['title'] end end

In JavaScript, using jQuery and JSONP:

// Get 3 users jQuery.ajax({ 'url':'http://api.tum.bz/v1/users?limit=3&apikey=nzaEhGbo4B9yAOn1GKveoSL003sexY9F', 'dataType':'jsonp' }).success(function(data){ console.debug(data) });

Console testing:

Want to get your hands dirty: You can play with our API resources via the the Apigee console. Simply type in http://api.tum.bz/v1{ a resource name }?apikey={ your api key } in the field and you'll be able to test the API's interactions.

Or... gem 'tumbz'!

Ruby lovers and Gem collectors will be happy to discover the Tumbz open source gem, a Ruby wrapper allowing you to interact in a freaking efficient way with our API, built using Her by @remi

See the gem's documentation and code samples here.

Resources and params available

Here's the list of the resources available via the Tumbz API. For some resources, additionnal filtering params can be added after the "?" sign. Each possible params will be detailed below.

Root url of the API:

http://api.tum.bz/v1

Demo key, for testing purposes:
apikey=nzaEhGbo4B9yAOn1GKveoSL003sexY9F

GET/comments

Returns a list of comments based on the params entered. Comments are made by users and always relate to a specific review. Comments can be nested in case of user replies.

Sample url:

http://api.tum.bz/v1/comments?user=fred&limit=3&apikey=nzaEhGbo4B9yAOn1GKveoSL003sexY9F

Available params: review; user; limit; offset;

POST/comments

Requires your user to be logged in via OAuth2

Post a new comment about a review (tumbz up or down)

Sample url:

http://api.tum.bz/v1/comments?review=50aea29478190f00020eb2d7&text=indeed!&apikey=nzaEhGbo4B9yAOn1GKveoSL003sexY9F

Available params: review; reply_to_comment; text;

PUT/comments/{id}

Requires your user to be logged in via OAuth2

Update the text of one of your comments

Sample url:

http://api.tum.bz/v1/comments/5076efa072265c000201fa73?text=indeed, indeed a lot!!!&apikey=nzaEhGbo4B9yAOn1GKveoSL003sexY9F

Available params: text;

DELETE/comments/{id}

Requires your user to be logged in via OAuth2

Delete one of your comments

Sample url:

http://api.tum.bz/v1/comments/5076efa072265c000201fa73&apikey=nzaEhGbo4B9yAOn1GKveoSL003sexY9F

Available params: none

Fields returned in response for comments:

Field Desc
id Unique identifier of comment
username Username of user commenting
user_avatar Avatar of user commenting
text Text content of the comment
user_id ID of user commenting
review_id ID of the review this comment was about
product_id ID of the product this comment was about (via the review)
time_diff Short text for "created X time ago"
created_at Datetime the comment was created
childs Nested comments array

GET/likes

Returns a list of 'Likes' based on the params entered. Important to understand that a 'Like' is not the same as a 'Tumbz Up'. Likes are all about a user liking a review, not necessarily the product this review was about.

Sample url:

http://api.tum.bz/v1/likes?user=plbabin&apikey=nzaEhGbo4B9yAOn1GKveoSL003sexY9F

Available params: review; user; limit; offset;

GET/likes/{id}

Get the details of a specific Like, from it's ID.

Sample url:

http://api.tum.bz/v1/likes/50213af988b95c00020822cc?apikey=nzaEhGbo4B9yAOn1GKveoSL003sexY9F

Available params: none

POST/likes

Requires your user to be logged in via OAuth2

Post a new Like about a review. Maximum 1 like per user per review.

Sample url:

http://api.tum.bz/v1/like?review=50aea29478190f00020eb2d7&apikey=nzaEhGbo4B9yAOn1GKveoSL003sexY9F

Available params: review;

DELETE/likes/{id}

Requires your user to be logged in via OAuth2

Delete one of your Likes

Sample url:

http://api.tum.bz/v1/likes/5076efa072265c000201fa73&apikey=nzaEhGbo4B9yAOn1GKveoSL003sexY9F

Available params: none

Fields returned in response for likes:

Field Desc
id Unique identifier of this 'Like'
review_id ID of the review (tumbz) that was liked
user_id ID of the user who liked the review (tumbz)
username Username of the user who liked the review (tumbz)

GET/partners_lookup/books

You can use this resource to search for book ISBNs that are maybe not tumbzed by anyone yet. Use this in conjunction with Google Books search to provide as many book options as possible for your users to review.

Sample url:

http://api.tum.bz/v1/partners_lookup/books?q=patrick&apikey=nzaEhGbo4B9yAOn1GKveoSL003sexY9F

Available params: q; limit; offset;

Fields returned in response for partners books lookup:

Field Desc
isbn ISBN id. Use this to POST new reviews about a book.
title Book title
contributors Contributors / book authors
publisher_name Name of the Publisher
publisher_url Url to publisher's website
publishing_date Publishing date
categories Categories / genres
img_thumb Url to thumbnail image
img_cover Url to cover image
desc Book's description, synopsis
source Parner providing this book's information

GET/partners_lookup/tvshows

You can use this resource to search for tv shows that are maybe not tumbzed by anyone yet. Use this to implement a tv shows search allowing your users to post new review using the 'external_id' field.

Sample url:

http://api.tum.bz/v1/partners_lookup/tvshows?q=house&apikey=nzaEhGbo4B9yAOn1GKveoSL003sexY9F

Available params: q; limit; offset;

Fields returned in response for partners tv shows lookup:

Field Desc
external_id TVDB id of the TV Show
title TV Show title
seasons_count Number of TV Show seasons
category Category of the TV Show
source From which provider

GET/products

Returns a list of products (movie, book, tv, album) based on the params entered. Only products previously tumbzed will be returned by this call, it is not a direct link to external apis for addionnal product searches. Note: You can't mix the following params, only 1 of them can apply: in_later_list_of_user, top_products_for_user, top_albums_for_user, top_books_for_user, top_tvs_for_user and top_movies_for_user.

Sample url:

http://api.tum.bz/v1/products?cat=movie&in_later_list_of_user=fred&apikey=nzaEhGbo4B9yAOn1GKveoSL003sexY9F

Available params: cat; in_later_list_of_user; top_products_for_user; top_albums_for_user; top_books_for_user; top_movies_for_user; top_tvs_for_user; days; hide_tumbzed_products; external_id; limit; offset;

GET/products/search

Returns products with matching title, artist name, genre or categorie. This search goes through our local products database. It includes all products previously tumbzed + books from De Marque + the TVDB TV Shows. You can also use this search to lookup a specific product using an external id (IMDB movie id, book isbn, itunes ID, Rdio key, TheTVDB ID).

Sample url:

http://api.tum.bz/v1/products/search?q=alternat&apikey=nzaEhGbo4B9yAOn1GKveoSL003sexY9F

Available params: q; cat; limit; offset;

GET/products/{id}

Get the details of a specific tumbz product, from it's ID.

Sample url:

http://api.tum.bz/v1/products/5089dd712f9cd5000201cc88?apikey=nzaEhGbo4B9yAOn1GKveoSL003sexY9F

Available params: none

Fields returned in response for products:

Field Desc
id Unique identifier of the tumbz product
cat Category of the product (movie, album, book)
url Url of the product's page on Tum.bz
title Title of the product
artist Artist / author of the product
external_id External ID of the product reviewed. ISBN for books, IMDB for movies, TVDB for tv shows and Itunes Collection ID or Rdio key for music album.
similar_external_ids All known and handled similar external ids for this product
img_thumb Thumbnail image url of the product
img_cover Cover image url of the product
desc Short text describing the product (summary, details...)
genres Movie or music genres, book categories
publisher Publisher, for books
trailer Url of trailer, for movies
like_percentage Percentage of positive reviews for this product
review_count Number of reviews made about this product
review_positive_count Number of positive reviews made about this product
review_negative_count Number of negative reviews made about this product
purchase_urls Urls where this product can be purchased online
stream_urls Urls where this product can be streamed/listened online

GET/reviews

Returns a list of reviews (aka tumbz up or tumbz down) based on the params entered. Reviews are made by users about a product. They are the result of a user giving a tumbz up or down for a movie, book, tv or album.

Sample url:

http://api.tum.bz/v1/reviews?cat=movie&from_users_respected_by=fred&limit=5&apikey=nzaEhGbo4B9yAOn1GKveoSL003sexY9F

Available params: cat; from_users_respected_by; user; product; product_external_id; limit; offset;

GET/reviews/{id}

Get the details for a tumbz by it's ID

Sample url:

http://api.tum.bz/v1/reviews/50982558339ff4000203478b?apikey=nzaEhGbo4B9yAOn1GKveoSL003sexY9F

Available params: none

POST/reviews

Requires your user to be logged in via OAuth2

Create a new product review (aka tumbz up or tumbz down). The 'text' param is not mandatory. External IDs and 'cat' are mandatory to create new review. Those external IDs are available in the Tumbz API for products already tumbzed by another user. However, in order to be able to post reviews on new products, you need to implement the use of external APIs in your app: Google Books, iTunes, Rdio and TMDB. Each one of those external API is easy to use and well documented.

Sample url:

http://api.tum.bz/v1/reviews?product_external_id=tt0458339&positive=1&text=testing&apikey=nzaEhGbo4B9yAOn1GKveoSL003sexY9F

Available params: cat; product_external_id; positive; text;

PUT/reviews/{id}

Requires your user to be logged in via OAuth2

Update one of your tumbz, to change it's 'positive' or 'text' values.

Sample url:

http://api.tum.bz/v1/reviews/50982558339ff4000203478b?text=wowapikey=nzaEhGbo4B9yAOn1GKveoSL003sexY9F

Available params: positive; text;

DELETE/reviews/{id}

Requires your user to be logged in via OAuth2

Delete one of your tumbz.

Sample url:

http://api.tum.bz/v1/reviews/50982558339ff4000203478b?apikey=nzaEhGbo4B9yAOn1GKveoSL003sexY9F

Available params: none

Fields returned in response for reviews:

Field Desc
id Unique identifier of the review (tumbz)
positive Boolean, true if it's a tumbz up
text Text content of the review (optional)
user_id ID of user who made the review
username Username of user who made the review
user_avatar Avatar of user who made the review
url Url of the review's page on Tum.bz
product_url Url of the product's page for the product reviewed
product_id ID of the product reviewed
product_title Title of the product reviewed
product_cat Category of the product reviewed (movie, album, book)
product_img_thumb Thumbnail image url of the product reviewed
product_img_cover Cover image url of the product reviewed
product_artist Artist / Author of the product reviewed
product_external_id External ID of the product reviewed. ISBN for books, IMDB for movies, Itunes Collection ID or Rdio key for music albums.
product_similar_external_ids All known and handled similar external ids for this product
product_like_percentage Percentage of tumbz up versus total number of tumbz for the product reviewed
product_review_count Number of reviews made about the current product reviewed
product_review_positive_count Number of positive reviews made about the current product reviewed
product_review_negative_count Number of negative reviews made about the current product reviewed
time_diff Short text for "created X time ago"
created_at Datetime the review was created
comments_count Number of comments made about this review (excluding nested comments, aka replies)
comments_and_replies_count Number of comments made about this review (including nested comments, aka replies)
likes_count Number of Likes for this review

GET/users

Returns a list of tumbz users according to the params entered. Note: You can't mix the following params, only 1 of them can apply: respecting, respected, tumbzed_product_up and tumbzed_product_down.

Sample url:

http://api.tum.bz/v1/users?respecting=plbabin&limit=25&apikey=nzaEhGbo4B9yAOn1GKveoSL003sexY9F

Available params: respecting; respected; tumbzed_product_up; tumbzed_product_down; limit; offset;

GET/users/search

Returns found users with usernames, emails, first names or last names matching the search query.

Sample url:

http://api.tum.bz/v1/users/search?q=rem&apikey=nzaEhGbo4B9yAOn1GKveoSL003sexY9F

Available params: q; limit; offset;

GET/users/{id or username}

Get the details of a specific tumbz user, from it's ID or username.

Sample url:

http://api.tum.bz/v1/users/fred?apikey=nzaEhGbo4B9yAOn1GKveoSL003sexY9F

Available params: none

Fields returned in response for users:

Field Desc
id Unique identifier of user
username Unique username, can be used to get user's information, but can be changed by user over time.
profile_url URL of Tumbz profile
firstname First name
lastname Last name
avatar URL of user's avatar.
bio Bio / presentation of user. Up to 400 chars.
like Things that user likes. Up to 140 chars.
like_not Things that user doesn't like. Up to 140 chars.
personal_website URL to user's website
city City name provided by user

POST/users

Requires your user to be logged in via OAuth2

Create a new tumbz user that will be able to login via your app and post reviews and use the app. The following fields are mandatory: 'username', 'email', 'firstname', 'lastname', 'password'

Sample url:

http://api.tum.bz/v1/users?username=demo&email=demo@tum.bz&firstname=Demo&lastname=User&password=demo1234&apikey=nzaEhGbo4B9yAOn1GKveoSL003sexY9F

Available params: username; email; firstname; lastname; password; website; city; bio;

PUT/users/{id or username}

Requires your user to be logged in via OAuth2

Update a user's profile informations. For now, only edits on currently logged in user is allowed.

Sample url:

http://api.tum.bz/v1/users/demo?firstname=Johnny-Demoapikey=nzaEhGbo4B9yAOn1GKveoSL003sexY9F

Available params: username; email; firstname; lastname; password; website; city; bio;

GET/user_suggestions

Suggestions of users that have similar opinions and that the targetted user should consider as a potential interests match.

Sample url:

http://api.tum.bz/v1/user_suggestions?user=plbabin&apikey=nzaEhGbo4B9yAOn1GKveoSL003sexY9F

Available params: user;

GET/user_suggestions/{id}

Get the details of a specific user suggestion from it's ID.

Sample url:

http://api.tum.bz/v1/user_suggestions/5057fe9233625f000204587f?apikey=nzaEhGbo4B9yAOn1GKveoSL003sexY9F

Available params: none

Fields returned in response for users suggestions:

Field Desc
id Unique identifier of this user suggestion
targetted_user_id The user this suggestion is made for
suggested_user_id The user we are suggesting to consider as a potential interests match
similar_reviews List of reviews that the suggested user made where we found matching tastes

Configuring your requests with params

In order to get the responses you need from the API, you'll have to use filter url params after the "?" sign. Here are the details about the usage the context and possible values for those params.

Refer to the list of resources above to see where those params can be used.

Param Usage Possible values Default
bio Bio / presentation text of user displayed in his profile. String up to 400 chars nil
cat Category of the products. book, movie, tv, or album nil
city City name of user as inputted in his profile. String (free text) from 2 up to 140 chars nil
days To be used with one of the 'top{productType}ForUser params below. Will adjust the 'top products for user' algorythm to a number of days in the past. 1, 7, 30 or 180 30
email User's email address. String with valid email format nil
external_id ID used to link to external data source's API and fetch data about the product. For books, use the ISBN returned by Google Books. For music, use the Rdio key or collectionId returned by iTunes API. For movies, use the IMDB id returned by TMDB. nil
firstname Firstname of a user. String nil
from_users_respected_by Reviews made by users who are respected by the given user. User ID or username nil
hide_tumbzed_products To be used with one of the 'top{productType}ForUser params below. If set to '1', will remove from this user's Top Chart the products he already tumbzed. Very useful for product suggestions. 1 or 0 0
in_later_list_of_user Products that are in a user's 'Watch/Listen/Read Later List User ID or username nil
lastname Lastname of a user. String nil
limit Available for all lists resources. Used to paginate the number of results returned. integer between 0 and 100 10
offset Available for all lists resources. Used to paginate the number of results returned. integer greater or equal to 0. Use 0 (beginning of the list)
password Case sensitive string used to log in users in the app. String minimum 6 chars nil
positive A tumbz up is positive (1), down is negative (0). 0 or 1 nil
product For a specific product. Product ID nil
product_external_id ID used to link to external data source's API and fetch data about the product. For books, use the ISBN returned by Google Books. For music, use the Rdio key or collectionId returned by iTunes API. For movies, use the IMDB id returned by TMDB. nil
q Query param, text searched. String, minimum 3 chars nil
reply_to_comment The comment you are replying to. Only 1 level of reply is allowed. You can reply only to parent comments. Comment ID nil
respecting Get users that are respecting the given user in param. User ID nil
respected Get users that are respected by the given user in param. User ID nil
review For a specific review (tumbz). Review ID nil
top_albums_for_user Top 10 albums for the given user User ID or username nil
text Short text entered by the user String, max 400 chars nil
top_books_for_user Top 10 books for the given user User ID or username nil
top_movies_for_user Top 10 movies for the given user User ID or username nil
top_tvs_for_user Top 10 tv shows for the given user User ID or username nil
top_products_for_user Top 10 products, in all categories for the given user User ID or username nil
tumbzed_product_up Get users that gave a tumbz up to the given product. Product ID nil
tumbzed_product_down Get users that gave a tumbz down to the given product. Product ID nil
user For a specific user. User ID or username nil
username Case sensitive string used to identify users in the app. String from 4 to 40 chars nil
website Url of user's personal website. String in URL format nil

OAuth2 login for you users

All GET described in the above API can be executed without any user login. Only an API Key is required (email us to get one: info@tum.bz). But in order to WRITE data using the API's POST, PUT and DELETE methods, you'll need to sign-in your user. In order to do so, you must get an OAuth2 token for your user's credential, store it, and send it in the header for each further requests, so your user is "logged in" through the API.

Short login sequence demo

# using basic stuff... require 'net/http' require 'json' # get credentials from your end user # then request your OAuth2 token... require 'net/http' require 'json' ### HOW TO: Get and use your OAuth2 token ### # add your own apikey in the url params url = 'http://api.tum.bz/v1/auth?apikey=nzaEhGbo4B9yAOn1GKveoSL003sexY9F' # IMPORTANT: You must send a POST call, not GET resp = Net::HTTP.post_form(URI.parse(url), {"email" => "USER-PROVIDED-EMAIL", "password" => "AND-HIS-PASSWORD"}) authResponse = JSON.parse(resp.body) token = authResponse['access_token'] # store this token securely in your app # then send it with each further calls (another way to use net/http) uri = URI.parse("http://api.tum.bz/v1/reviews") http = Net::HTTP.new(uri.host, uri.port) request = Net::HTTP::Post.new(uri.request_uri) headers = {'Authorization' => "OAuth2 #{token}"} formData = {"cat" => "movie", "product_external_id" => "tt1844770", "positive" => "1", "text" => "Masterpiece!", "apikey" => "nzaEhGbo4B9yAOn1GKveoSL003sexY9F"} request.set_form_data(formData) request["Authorization"] = "OAuth #{token}" resp = http.request(request) # There, you'll see the confirmation, or error :) postResponse = JSON.parse(resp.body)

What's the difference between your API Key and OAuth2?

The API key is mandatory for each calls to the API. It allows us to give access to specific developers and track the use of each calls, so we have a better understanding of the API's usage in order to optimize it. OAuth2 is used to log in your end user, as they are doing when going to the web version of Tum.bz. You only need to implement this one if your application is doing WRITE operations.

We hope you enjoy it!

We believe the Tumbz API is great, but we want it to be freaking-awesome. So drop-us a line if you have any comments or see something missing. We'll be reading every comments and take them into account while we're trying to build the best experience in entertainment products discovery.

- Fred & PL

Join our Feedback community here or email us at feedback 'at' tum.bz

The Tumbz API A REST API brought to you by the team behind the Tum.bz App

Use our data to build your next awesome app or mashup.

Currently at v1.

Comments are welcome! Email us at feedback 'at' tum.bz or hit the Feedback button on the right.

Follow Us

The Tum.bz Team

  • plbabin

    Pierre-Luc Babin

    Web dev machine and front end killer

  • fred

    Frédérick Dubois

    Charts algorythmer and web developer

Tumbz

Tumbz helps you discover albums, movies and books by listening to the opinion of people whose taste you respect.

Find out more »

API Resources: