New

How to use the TVBuzer API

In order to use the TvBuzer API you must first request an access key, here.

Do not call the API from other ip adresses except the two you configured as your account will be suspended.

We provide a free, fast and clean JSON RPC based architecture API that's easy to use, returns JSON and conforms to the HATEOAS and HAL principles.

The available endpoints are documented below.
The provided samples are executed with Frederic Guillot's json rpc client (https://github.com/fguillot/JsonRPC), but of course you can use any client library.

Setup and authentication

The authentication is built into the service url, which looks like this http://www.tvbuzer.com/Api/Shows/v1/johndoe/hfdskfh5445hj45hjh

Here is an example how to build it:

$baseUrl = "http://www.tvbuzer.com";
$userName = "your tvbuzer username";
$apiKey = "your api key";
$serviceUrl = sprintf('%s/api/Shows/v1/%s/%s', $baseUrl, $userName, $apiKey);

$client = new Client($serviceUrl, 5, true);

                

Endpoints

Search

Show search

The search method allows you to search a show by name. The search is fragment based, and allows pagination.

The most common usecase for this endpoint is when you're building a local mapping of show names to TVBuzer ID's and want to make sure that you're mapping to exactly the right show, and not to a different show that happens to have the same name. By presenting each show's basic information in a UI, you can have the end-user pick a specific entry from that list, and have your application store the chosen show's ID or URL. Any subsequent requests for information on that show can then be directly made to that show's URL.

Pagination is provided by default so you can load data progressively.

  • The parameters are:
  • show name : string
  • page number: integer
  • results per page : integer

Code sample:


$result = $client->execute('search', array("game of thrones", 1, 30));
var_dump($result);
array(1) {
  [0]=>
  array(8) {
    ["id"]=>
    string(4) "7548"
    ["name"]=>
    string(15) "Game of Thrones"
    ["name_url"]=>
    string(15) "Game-of-Thrones"
    ["country"]=>
    string(2) "US"
    ["release_date"]=>
    string(10) "2011-04-17"
    ["end_date"]=>
    NULL
    ["status"]=>
    string(16) "Returning Series"
    ["genres"]=>
    array(6) {
      [0]=>
      array(9) {
        ["id"]=>
        string(3) "104"
        ["name"]=>
        string(7) "Fantasy"
        ["description"]=>
        NULL
        ["summary"]=>
        NULL
        ["image_path"]=>
        string(39) "3f/3f55bca615d17cb8c0e18355c717e1b9-104"
        ["name_url"]=>
        string(7) "Fantasy"
        ["create_date"]=>
        string(19) "2012-11-28 22:36:00"
        ["modify_date"]=>
        string(19) "2016-10-24 08:50:05"
        ["pageviews"]=>
        string(7) "7601898"
      }
      [1]=>
      array(9) {
        ["id"]=>
        string(3) "111"
        ["name"]=>
        string(5) "Drama"
        ["description"]=>
        NULL
        ["summary"]=>
        NULL
        ["image_path"]=>
        string(39) "6d/6d93658f44500cf7f88e935c200f88a3-111"
        ["name_url"]=>
        string(5) "Drama"
        ["create_date"]=>
        string(19) "2012-11-29 14:13:33"
        ["modify_date"]=>
        string(19) "2016-10-24 08:50:05"
        ["pageviews"]=>
        string(8) "46840756"
      }

    }
  }
}

                

Showinfo - Show single search

In some scenarios you might want to immediately return information based on a user's query and you have the TVBuzzer ID from a previous search, without the intermediary step of presenting them all the possible matches. In that case, you can use the singlesearch endpoint which either returns exactly one result, or no result at all.

As opposed to the regular search endpoint, the singlesearch endpoint allows embedding additional information in the result.

  • The parameters are:
  • showId: integer

Code sample:

$result = $client->execute('showinfo', array(7897));
var_dump($result);
array(22) {
  ["id"]=>
  string(4) "7897"
  ["remote_id"]=>
  string(5) "14894"
  ["url_cover_portrait"]=>
  string(66) "http://static0.tvbuzer.com/images/shows/generic/7897-3-110-160.jpg"
  ["url_cover_image_source"]=>
  NULL
  ["name"]=>
  string(19) "Six Days of Justice"
  ["name_url"]=>
  string(19) "Six-Days-of-Justice"
  ["country"]=>
  string(2) "UK"
  ["channel"]=>
  string(10) "ITV London"
  ["release_date"]=>
  string(10) "1972-04-10"
  ["end_date"]=>
  string(10) "1975-05-19"
  ["status"]=>
  string(14) "Canceled/Ended"
  ["classification"]=>
  string(8) "Scripted"
  ["genres"]=>
  array(4) {
    [0]=>
    array(9) {
      ["id"]=>
      string(2) "74"
      ["name"]=>
      string(5) "Crime"
      ["description"]=>
      NULL
      ["summary"]=>
      NULL
      ["image_path"]=>
      string(38) "44/4418445bd28a5ff241cca7f8f38dfa63-74"
      ["name_url"]=>
      string(5) "Crime"
      ["create_date"]=>
      string(19) "2012-11-27 23:18:14"
      ["modify_date"]=>
      string(19) "2016-10-24 08:50:05"
      ["pageviews"]=>
      string(8) "15755207"
    }
    [1]=>
    array(9) {
      ["id"]=>
      string(2) "94"
      ["name"]=>
      string(7) "Mystery"
      ["description"]=>
      NULL
      ["summary"]=>
      NULL
      ["image_path"]=>
      string(38) "d8/d852353e71296f62ea7ba91a8485a0df-94"
      ["name_url"]=>
      string(7) "Mystery"
      ["create_date"]=>
      string(19) "2012-11-28 20:06:51"
      ["modify_date"]=>
      string(19) "2016-10-24 08:50:05"
      ["pageviews"]=>
      string(8) "11117012"
    }
  }
  ["airtime"]=>
  string(5) "12:00"
  ["airday"]=>
  string(6) "Monday"
  ["airdate"]=>
  NULL
  ["description"]=>
  string(140) "Six players must collaborate to solve nontrivia logic games within"
  ["status_label"]=>
  string(5) "Ended"
  ["is_popular"]=>
  string(1) "0"
  ["imported_from"]=>
  string(10) "tvrage.com"
  ["pageviews"]=>
  string(1) "0"
  ["cast"]=>
  array(115) {
    [0]=>
    array(3) {
      ["id"]=>
      string(7) "8037873"
      ["actor_name"]=>
      string(13) "Mollie Sugden"
      ["character_name"]=>
      string(10) "Mrs. Dunne"
    }
    [1]=>
    array(3) {
      ["id"]=>
      string(7) "8038430"
      ["actor_name"]=>
      string(18) "Harold Bennett (1)"
      ["character_name"]=>
      string(13) "Patrick Scott"
    }
}
                    

Episodes list

If you have a TVBuzer show id you can retrieve the episodes list. Pagination is needed as some shows have quite a lot of data.

  • The parameters are:
  • showId : integer
  • page number: integer
  • results per page : integer

Code sample:

$result = $client->execute('episodeslist', array(55));
print_r($result);
Array
(
    [0] => Array
        (
            [id] => 8851
            [name] => The Last One (2)
            [is_special] =>
            [episode_season_number] => 18
            [season] => 10
            [release_date] => 2004-05-06
            [description] => Ross and Phoebe chase Rachel to the airport
        )

    [1] => Array
        (
            [id] => 8850
            [name] => The Last One (1)
            [is_special] =>
            [episode_season_number] => 17
            [season] => 10
            [release_date] => 2004-05-06
            [description] => Ross and Phoebe chase Rachel to the airport,
        )

);
                    

Rate limiting

API calls are rate limited to allow at least 20 calls every 10 seconds per IP address. If you exceed this rate, you might receive an HTTP 429 error. We say at least, because rate limiting takes place on the backend but not on the edge cache. So if your client is only requesting common/popular endpoints like shows or episodes (as opposed to more unique endpoints like searches or embedding), you're likely to never hit the limit. For an optimal throughput, simply let your client back off for a few seconds when it receives a 429.

Under special circumstances we may temporarily have to impose a stricter rate limit. So even if your client wouldn't normally exceed our rate limit, it's useful to gracefully handle HTTP 429 responses: simply retry the request after a small pause instead of treating it as a permanent failure.

While not required, we strongly recommend setting your client's HTTP User Agent to something that'll uniquely describe it. This allows us to identify your application in case of problems, or to proactively reach out to you.

Licensing

Use of the TVBuzer API is licensed by CC BY-SA. This means the data can freely be used for any purpose, as long as TVBuzer is properly credited as source. You can do this by linking back to TVBuzer from within your application or website, for example using the URLs available in the API.