Build with Couchmate

What you get

For each airing: the show's or movie's name, the episode, when it starts and ends, its channels, and whether it's live or new. It comes with links to its room, a short link and its page on Couchmate, and three share images: a link preview, a square and a story.

The API doesn't give descriptions, cast, ratings or a whole guide.

Get a key

Save your account, then open Profile and choose Developer. Make a key there. It's free.

Open Developer

Which key to use

Publishable keys are for the browser. They go in your site's pages, where anyone can see them, so each one is locked to the origins you list, like https://example.com. http://localhost works too, for testing.

Secret keys are for your server (or curl). You see one only once, when you make it, and it's refused in any browser.

An example

From a page on a site your publishable key lists:

const response = await fetch("https://couchmate.com/api/v1/airings?titleId=12", {
  headers: { Authorization: "Bearer cm_pk_your_publishable_key" },
});
const { airings } = await response.json();
for (const airing of airings) {
  const link = document.createElement("a");
  link.href = airing.links.room;
  link.textContent = new Date(airing.startsAt).toLocaleString();
  document.querySelector("#couchmate").append(link);
}

Limits

A publishable key can make 120 requests a minute, and a secret key 600. An account can have up to 5 keys. Over a limit, the API answers 429 until the minute is up.

Show where the data comes from

Every airing has an attribution list: the providers whose listings it uses, each with a name and a url. Show each name, linked to its url, next to the data, as “Listings by TV Media”. Data sources says more about each one.

Reference and terms

The reference lists every endpoint and field. Its Test Request console sends requests from couchmate.com, which works with every publishable key, so you don't need to list it. A secret key is refused there, as in any browser.

Using the API means agreeing to the Developer Terms.

API reference