node-tvmaze v1.0.0

Node-TvMaze

A Promise based node.js wrapper for the public TVmaze API.

TVmaze API is public with no need for an API key but limitations apply, read more.

Instillation

This can be installed via NPM via:

npm i --save node-tvmaze

Or cloned via Git from:

https://github.com/kennyist/node-tvmaze.git

Usage

You can easily import node-tvmaze and use straight away for example:

const Tvmaze = require('node-tvmaze');

Tvmaze.search("firefly")
      .then(response => {
        // Response is a JSON object of the results
        resposne.map(item => {
          // Loop through results and print the show name
          console.log(item.show.name);
        })
      })
      .catch(error => {
        // Error is a Request returned error
        console.log(error.body); // log the readable part of the error object
      });

See Request for more error details.

Testing

This module uses Mocha tests that can be run by using:

npm test

Endpoints

All endpoints are fully JSdoc documented

• Searching
• Lookup
• Schedule
• Show information
• People information
• Other functions

Options

All endpoints allow for options options parameter, this is where you can define request header values or switch from https to http, default value:

{
  https: true,
  header: {
    'User-Agent': `node-tvmaze/${VERSION}`
  }
}

To switch to http you can simply add {https: false} to the last parameter of each endpoint. Must be done per call.

Searching

search(string, options) ⇒ Promise

Search through all shows on TVmaze in order or relevance.

Example:

search("Firefly").
     then(response => {
       console.log(response);
     })
     .catch(error => {
       console.log(error);
     })

API Call example: http://api.tvmaze.com/search/shows?q=firefly

https://www.tvmaze.com/api#show-search

singleSearch(string, options) ⇒ Promise

Return single search result, including more detailed show information

Example:

sinlgeSearch("Firefly", ['episodes']).
     then(response => {
       console.log(response);
     })
     .catch(error => {
       console.log(error);
     })

API Call example: http://api.tvmaze.com/singlesearch/shows?q=firefly

https://www.tvmaze.com/api#show-single-search

searchPeople(string, options) ⇒ Promise

Search through all people on TVmaze in order or relevance.

Example:

searchPeople("Stephen Colbert").
     then(response => {
       console.log(response);
     })
     .catch(error => {
       console.log(error);
     })

API Call example: http://api.tvmaze.com/search/people?q=Stephen%20Colbert

https://www.tvmaze.com/api#people-search

Lookup

https://www.tvmaze.com/api#show-lookup

lookupThetvdb(id, options) ⇒ Promise

Lookup a TV show using a TVdb ID

Example:

lookupThetvdb("270701").
     then(response => {
       console.log(response);
     })
     .catch(error => {
       console.log(error);
     })

API Call example: http://api.tvmaze.com/lookup/shows?thetvdb=270701

lookupImdb(id, options) ⇒ Promise

Lookup a TV show using a IMDB ID

Example:

lookupImdb("tt3530232").
     then(response => {
       console.log(response);
     })
     .catch(error => {
       console.log(error);
     })

API Call example: http://api.tvmaze.com/lookup/shows?imdb=tt3530232

lookupTvrage(id, options) ⇒ Promise

Lookup a TV show using a TVrage ID

Example:

lookupTvrage(270701).
     then(response => {
       console.log(response);
     })
     .catch(error => {
       console.log(error);
     })

API Call example: http://api.tvmaze.com/lookup/shows?thetvdb=270701

Schedule

schedule(countryCode, date, options) ⇒ Promise

Get the TV schedule for a country and date

Example:

schedule("GB", "2019-03-23").
     then(response => {
       console.log(response);
     })
     .catch(error => {
       console.log(error);
     })

API Call example: http://api.tvmaze.com/schedule?country=GB&date=2019-03-23

https://www.tvmaze.com/api#schedule

fullSchedule(options) ⇒ Promise

Get the every future episode known to TVmaze

Example:

schedule().
     then(response => {
       console.log(response);
     })
     .catch(error => {
       console.log(error);
     })

API Call example: http://api.tvmaze.com/schedule/full

https://www.tvmaze.com/api#full-schedule

Shows

show(showid, emded, options) ⇒ Promise

Get the main information for a show, supports embedding

Example:

show("396", ['episodes']).
     then(response => {
       console.log(response);
     })
     .catch(error => {
       console.log(error);
     })

API Call example: http://api.tvmaze.com/shows/396?embed=episodes

https://www.tvmaze.com/api#show-main-information https://www.tvmaze.com/api#embedding

episodes(showid, specials, options) ⇒ Promise

Get a complete list of episodes in airing order

Example:

episodes(396, true).
     then(response => {
       console.log(response);
     })
     .catch(error => {
       console.log(error);
     })

API Call example: http://api.tvmaze.com/shows/396/episodes?specials=1

https://www.tvmaze.com/api#show-episode-list

episode(showid, season, episode, options) ⇒ Promise

Get information for a single episode of a show

Example:

episode(396, 1, 1).
     then(response => {
       console.log(response);
     })
     .catch(error => {
       console.log(error);
     })

API Call example: http://api.tvmaze.com/shows/396/episodebynumber?season=1&number=1

https://www.tvmaze.com/api#episode-by-number

episodesByDate(showid, date, options) ⇒ Promise

Get episodes aired on a date

Example:

episodesByDate(321, "2019-03-15").
     then(response => {
       console.log(response);
     })
     .catch(error => {
       console.log(error);
     })

API Call example: http://api.tvmaze.com/shows/321/episodesbydate?date=2019-03-15

https://www.tvmaze.com/api#episodes-by-date

seasons(showid, options) ⇒ Promise

Get season list information

Example:

seasons(321).
     then(response => {
       console.log(response);
     })
     .catch(error => {
       console.log(error);
     })

API Call example: http://api.tvmaze.com/shows/321/seasons

https://www.tvmaze.com/api#show-seasons

seasonEpisodes(seasonid, options) ⇒ Promise

Get all episodes for a season

Example:

seasonEpisodes(1).
     then(response => {
       console.log(response);
     })
     .catch(error => {
       console.log(error);
     })

API Call example: http://api.tvmaze.com/seasons/1/episodes

https://www.tvmaze.com/api#season-episodes

cast(showid, options) ⇒ Promise

Get cast information

Example:

cast(174).
     then(response => {
       console.log(response);
     })
     .catch(error => {
       console.log(error);
     })

API Call example: http://api.tvmaze.com/shows/174/cast

https://www.tvmaze.com/api#show-cast

crew(showid, options) ⇒ Promise

Get crew information

Example:

crew(49).
     then(response => {
       console.log(response);
     })
     .catch(error => {
       console.log(error);
     })

API Call example: http://api.tvmaze.com/shows/49/crew

https://www.tvmaze.com/api#show-crew

aliases(showid, options) ⇒ Promise

Get all show aliases

Example:

aliases(49).
     then(response => {
       console.log(response);
     })
     .catch(error => {
       console.log(error);
     })

API Call example: http://api.tvmaze.com/shows/49/akas

https://www.tvmaze.com/api#show-aka

showsIndex(page, options) ⇒ Promise

Get the full list of shows and details on TVmaze (250 results per page, in ID order)

Example:

showsIndex(1).
     then(response => {
       console.log(response);
     })
     .catch(error => {
       console.log(error);
     })

API Call example: http://api.tvmaze.com/shows?page=1

https://www.tvmaze.com/api#show-index

showUpdates(options) ⇒ Promise

Get the full list of show IDs and last updated timestamp (ID order)

Example:

showUpdates().
     then(response => {
       console.log(response);
     })
     .catch(error => {
       console.log(error);
     })

API Call example: http://api.tvmaze.com/updates/shows

https://www.tvmaze.com/api#show-updates

People

person(personid, embed, options) ⇒ Promise

Get all information for a person, Supports embed

Example:

person(37135, ['castcredits']).
     then(response => {
       console.log(response);
     })
     .catch(error => {
       console.log(error);
     })

API Call example: http://api.tvmaze.com/people/37135?embed=castcredits

https://www.tvmaze.com/api#person-main-information https://www.tvmaze.com/api#embedding

personCastCredits(personid, embed, options) ⇒ Promise

Get cast credits for a person, supports embedding

Example:

personCastCredits(37135, ['show']).
     then(response => {
       console.log(response);
     })
     .catch(error => {
       console.log(error);
     })

API Call example: http://api.tvmaze.com/people/37135/castcredits?embed=show

https://www.tvmaze.com/api#person-cast-credits https://www.tvmaze.com/api#embedding

personCrewCredits(personid, embed, options) ⇒ Promise

Get crew credits for a person, supports embedding

Example:

personCrewCredits(100, ['show']).
     then(response => {
       console.log(response);
     })
     .catch(error => {
       console.log(error);
     })

API Call example: http://api.tvmaze.com/people/37135/crewcredits?embed=show

https://www.tvmaze.com/api#person-crew-credits https://www.tvmaze.com/api#embedding

Other

lookup(type, id, options) ⇒ Promise

Lookup a TV show using Tvdb ID, IMDB ID or Tvrage ID

Example:

lookup('imdb', "tt2758770").
     then(response => {
       console.log(response);
     })
     .catch(error => {
       console.log(error);
     })

API Call example: http://api.tvmaze.com/lookup/shows?imdb=tt2758770

https://www.tvmaze.com/api#show-lookup

sendRequest(path, options) ⇒ Promise

Send API request and return JSON

Example:

sendRequest("people/250/castcredits", {
    query: {
        embed: ['show']
      }
    })
     .then(response => {
       console.log(response);
     })
     .catch(error => {
       console.log(error);
     })

API Call example: http://api.tvmaze.com/people/250/crewcredits?embed=show

© 2019 Tristan 'Kennyist' Cunningham - www.tristanjc.com