TasteDive API Documentation

Overview

TasteDive (formerly named TasteKid) is an entertainment recommendation engine for films, TV shows, music, video games, and books. It also has elements of a social media site.

When a user types in the title of a film or TV show, the site’s algorithm provides a list of similar content. It provides recommendations for TV shows to watch based on films liked by the user, and vice versa. It also provides recommendations for music, video games, and books, and includes film and TV trailers and music videos. The API responds to standard URL query strings, and it returns data in an easily interpretable and scrapable JSON format.

An account is free and is not required to receive recommendations, but recommendations are more accurate for those with an account. The more a user explores the site, the more the site learns about the user’s preferences and the better the results become. The site also has a social media aspect where one can see activity and gain recommendations from other users, how many others in the community like or dislike any recommendation, and how popular their tastes are within the TasteDive community.

Requirements

Anyone with an internet browser can readily access the TasteDive API. If you decide to use it, you have to request an access key. Using this key, you can perform 300 requests per hour. It requires no special programs or installations. The API, however, presents results in JSON. Thus, a JSON reader of some kind can help organize the page into a user-friendly, human-readable format. (JSONview, for instance, has an exceptional extension for Chrome or Firefox users.)

Learn more

The following sections give a high-level overview of the TasteDive parameters (i.e., the categories of recommendations of the specific type) and walk through the process of querying the parameters values for specific results.

Endpoints

The TasteDive API have a simple basic endpoint. You can get all type of similar recommendation of a movie, music etc.

GET

https://tastedive.com/api/similar

  • Example Response

    {"Similar": {"Info": [{"Name": "!!!", "Type": "music"}], "Results": [{"Name": "Meeting Of Important People", "Type": "music"}, {"Name": "La Tour Montparnasse Infernale", "Type": "movie"}, {"Name": "Young & Sick", "Type": "music"}, {"Name": "The Vanity Project", "Type": "music"}, {"Name": "Tyler Bryant & The Shakedown", "Type": "music"}, {"Name": "Sombear", "Type": "music"}, {"Name": "Thirsty Fish", "Type": "music"}, {"Name": "Better Luck Next Time", "Type": "music"}, {"Name": "The High Court", "Type": "music"}, {"Name": "Stars Of Track And Field", "Type": "music"}, {"Name": "Beachwood Sparks", "Type": "music"}, {"Name": "Tinted Windows", "Type": "music"}, {"Name": "Promise Of Redemption", "Type": "music"}, {"Name": "Zach Gill", "Type": "music"}, {"Name": "The Music", "Type": "music"}, {"Name": "Chappo", "Type": "music"}, {"Name": "Kisses", "Type": "music"}, {"Name": "The Young Romans", "Type": "music"}, {"Name": "Jarle Bernhoft", "Type": "music"}, {"Name": "The Postelles", "Type": "music"}]}}

Parameters

  • Query String Parameters

    Query Param Required/Optional Type
    q Required String
    type Optional String
    info Optional Integer(Default = 0)
    limit Optional Integer(Default = 20)
    k Required String

Parameters Details

query (?q=)

It is the search query; consists of a series (at least one) of bands, movies, TV shows, podcasts, books, authors and/or games, separated by commas. Sometimes it is useful to specify the type of a certain resource in the query (e.g. if a movie and a book share the same title). You can do this by using the “band:”, “movie:”, “show:”, “podcast:”, “book:”, “author:” or “game:” operators, for example: ” band:underworld, movie:harry potter, book:trainspotting “. It is the required parameter.

type

It is the query type, specifies the desired type of results.It is of type string. It can be one of the following: music, movies, shows, podcasts, books, authors, games. It is optional, if not specified, the results can have mixed types.

info

It is the additional information is provided for the recommended items, like a description and a related Youtube clip (when available) and its wikipedia link. It is of type Integer having the values 0 or 1. When set to 1 it specifies, default is 0.

limit

It specifies the maximum number of recommendations to retrieve. It is optional and of type integer. It default value is 20.

API-Key (k)

Your API access key. It is the required feild. You can access the recommendation without this key also but for the limited requests. Using this key, you can perform 300 requests per hour. Please provide a description of your product, together with some usage estimates. This allows us to increase the quota of certain applications that need it and get a better understanding of how the service is being used.

Querying Endpoints

The TasteDive Endpoint, filterable and searchable, can return precise recommendations for TV shows to watch based on films liked by the user, music to listen liked by maximum user, etc. The API responds to standard URL queries: users can search the API using basic query strings.

Query basics

A question mark (?) always demarcates the beginning of a URL query string:

# Basic pattern
https://tastedive.com/api/similar?{query string}

# Example query - recommendations of movie Guardians Of The Galaxy Vol. 2.
https://tastedive.com/api/similar?q=Guardians Of The Galaxy Vol. 2

Queries can contain multiple parameters. An ampersand (&) separates each parameter:

# Basic pattern
https://tastedive.com/api/similar?{param1}&{param2}&{param3}

# Example query - information about the movie and the similiar one.
https://tastedive.com/api/similar?limit=1&q=Guardians Of The Galaxy Vol. 2

A few useful calls

Basics with API-Key

Each entry displays a collection of fields and corresponding data, e.g., an event has a classification, description, start_time, etc. Any of these data points may form the basis of a URL query:

# Basic pattern
https://tastedive.com/api/similar?{query}={value}&k=YOUR API-KEY

# Example query
https://tastedive.com/api/similar?q=Guardians Of The Galaxy Vol. 2&k=YOUR API-KEY

  • Example Response

    {"Similar": {"Info": [{"Name": "Guardians Of The Galaxy Vol. 2", "Type": "movie"}], "Results": [{"Name": "Thor: Ragnarok", "Type": "movie"}, {"Name": "Star Wars: The Last Jedi", "Type": "movie"}, {"Name": "Spider-Man: Homecoming", "Type": "movie"}, {"Name": "Avengers: Infinity War", "Type": "movie"}, {"Name": "Power Rangers", "Type": "movie"}, {"Name": "Deadpool 2", "Type": "movie"}, {"Name": "Black Panther", "Type": "movie"}, {"Name": "Jumanji: Welcome To The Jungle", "Type": "movie"}, {"Name": "Bright", "Type": "movie"}, {"Name": "Pirates Of The Caribbean: Dead Men Tell No Tales", "Type": "movie"}, {"Name": "The Hitman's Bodyguard", "Type": "movie"}, {"Name": "Ready Player One", "Type": "movie"}, {"Name": "Kingsman: The Golden Circle", "Type": "movie"}, {"Name": "Baywatch", "Type": "movie"}, {"Name": "The Fate Of The Furious", "Type": "movie"}, {"Name": "The Divergent Series: Insurgent", "Type": "movie"}, {"Name": "Independence Day: Resurgence", "Type": "movie"}, {"Name": "Captain Marvel", "Type": "movie"}, {"Name": "Assassin's Creed", "Type": "movie"}, {"Name": "Ant-Man And The Wasp", "Type": "movie"}]}}

And again, the API also accepts multiple parameters, separated by an ampersand (&):

# For more than one parameter values
https://tastedive.com/api/similar?limit=1&q=Thor: Ragnarok&k=YOUR API-KEY

Note: type the spaces if a value has multiple words, e.g, Guardians Of The Galaxy Vol. 2. The API will automatically replace spaces with the correct encoding (“%20”).

Info

When verbose set to 1 in the request, each item can also contains the following additional keys:

Items Information
wTeaser item description
wUrl item Wikipedia URL
yUrl item Youtube clip URL
yID item Youtube clip ID 
# Basic pattern
https://tastedive.com/api/similar?{query}={value}&k=YOUR API-KEY&info=1

# Example query
https://tastedive.com/api/similar?info=1&q=Thor: Ragnarok&k=YOUR API-KEY
  • Example Response
{
"Similar": {
    "Info": [
        {
            "Name": "Thor: Ragnarok",
            "Type": "movie",
            "wTeaser": "\n\n\nThor: Ragnarok is a 2017 American superhero film based on the Marvel Comics character Thor, produced by Marvel Studios and distributed by Walt Disney Studios Motion Pictures. It is the sequel to 2011's Thor and 2013's Thor: The Dark World, and the seventeenth film in the Marvel Cinematic Universe (MCU). The film is directed by Taika Waititi from a screenplay by Eric Pearson and the writing team of Craig Kyle and Christopher Yost, and stars Chris Hemsworth as Thor alongside Tom Hiddleston, Cate Blanchett, Idris Elba, Jeff Goldblum, Tessa Thompson, Karl Urban, Mark Ruffalo, and Anthony Hopkins. In Thor: Ragnarok, Thor must escape the alien planet Sakaar in time to save Asgard from Hela and the impending Ragnarök.\n",
            "wUrl": "https://en.wikipedia.org/wiki/Thor:_Ragnarok",
            "yUrl": "https://www.youtube-nocookie.com/embed/ue80QwXMRHg",
            "yID": "ue80QwXMRHg"
        }
    ],
    "Results": [
        {
            "Name": "Avengers: Infinity War",
            "Type": "movie",
            "wTeaser": "\n\n\n\nAvengers: Infinity War is a 2018 American superhero film based on the Marvel Comics superhero team the Avengers, produced by Marvel Studios and distributed by Walt Disney Studios Motion Pictures. It is the sequel to 2012's The Avengers and 2015's Avengers: Age of Ultron, and the nineteenth film in the Marvel Cinematic Universe (MCU). It was directed by Anthony and Joe Russo, written by Christopher Markus and Stephen McFeely, and features an ensemble cast including Robert Downey Jr., Chris Hemsworth, Mark Ruffalo, Chris Evans, Scarlett Johansson, Benedict Cumberbatch, Don Cheadle, Tom Holland, Chadwick Boseman, Paul Bettany, Elizabeth Olsen, Anthony Mackie, Sebastian Stan, Danai Gurira, Letitia Wright, Dave Bautista, Zoe Saldana, Josh Brolin, and Chris Pratt. In the film, the Avengers and the Guardians of the Galaxy attempt to stop Thanos from collecting the all-powerful Infinity Stones.\n",
            "wUrl": "https://en.wikipedia.org/wiki/Avengers:_Infinity_War",
            "yUrl": "https://www.youtube-nocookie.com/embed/QwievZ1Tx-8",
            "yID": "QwievZ1Tx-8"
        }
    ]
}
}

HTTP Status Codes And Errors

APIs should define the functional, business view and abstract from implementation aspects. Success and error responses are a vital part to define how an API is used correctly.

  • GET

    GET requests are used to read either a single or a collection resource.

    GET requests for individual resources will usually generate a 404 if the resource does not exist

    GET requests for collection resources may return either 200 (if the collection is empty) or 404 (if the collection is missing)