Quick start

A key, the first call and the answer, in five minutes.

1. Get a key

Sign in with Google at your account. Your free key is made at once and shown on the account page. It is also saved in this browser, so Try it on every docs page already has it.

2. Make the first call

Yesterday on one channel. The free key reads yesterday on every channel we list.

curl "https://api.tvschedule.org/v1/channels/ch_jw83a3xg/schedule/yesterday" \
  -H "X-API-Key: $TVS_KEY"

Do not have a channel id yet? Find one with /v1/channels/search/{q} or list a country with /v1/countries/{cc}/channels.

3. Read the answer

Every answer is one shape: data holds the rows, meta holds the count, the date and anything else about the answer. Every time is UTC with a Z.

{
  "data": [ { "start": "...Z", "stop": "...Z", "title": "..." } ],
  "meta": { "count": 38, "date": "YYYY-MM-DD", "plan": "free" }
}

Your limits ride in the headers of every answer: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset and X-Quota-Remaining. /v1/usage tells you the same at any time and is never counted.

Next

Read the listings guide for time zones and whole countries, or the shows guide to follow a programme. To use the API from an assistant, add the MCP server.