TV Schedule

This API provides a complete daily schedule of TV broadcasts for a specific country. If no date or country is provided, it defaults to today in the US.

Note

Responses are cached on the edge for 1 hour for fast response.

Endpoint

POST /api/v1/tv/schedule

Request Parameters

The following parameters are accepted in the request body:

Field	Type	Required	Description	Example
country	string	Optional	ISO country code. Defaults to US.	GB
date	string	Optional	Date in YYYY-MM-DD format. Defaults to today.	2026-05-29

Request Examples

cURL

curl -X POST https://heavstal.com.ng/api/v1/tv/schedule \
-H "Content-Type: application/json" \
-H "x-api-key: <YOUR_API_KEY>" \
-d '{"country": "US", "date": "2026-05-29"}'

JavaScript (Fetch)

const response = await fetch('https://heavstal.com.ng/api/v1/tv/schedule', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': '<YOUR_API_KEY>'
  },
  body: JSON.stringify({
    country: "US",
    date: "2026-05-29"
  })
});

const res = await response.json();
console.log(`Found ${res.data.count} shows airing.`);

Heavstal SDK

import { tv } from '@heavstal/api';

// Get schedule for Great Britain for today
const schedule = await tv.schedule("GB");
console.log(schedule.schedule[0].show);

Python

import requests

url = "https://heavstal.com.ng/api/v1/tv/schedule"
headers = {
    "Content-Type": "application/json",
    "x-api-key": "<YOUR_API_KEY>"
}
payload = {
    "country": "US"
}

response = requests.post(url, headers=headers, json=payload)
print(response.json()["data"]["schedule"][0]["show"])

Response Examples

Success Response

{
  "status": "success",
  "creator": "HEAVSTAL TECH",
  "cached": false,
  "cache_ttl": 3600,
  "data": {
    "country": "US",
    "date": "2026-05-29",
    "count": 1,
    "schedule": [
      {
        "id": 1234,
        "show": "The Tonight Show",
        "episode_name": "Special Guest Star",
        "season": 12,
        "number": 45,
        "channel": "NBC",
        "time": "23:35",
        "runtime": 60
      }
    ]
  }
}

Error Response

{
  "error": "Failed to fetch TV schedule",
  "details": "Invalid country code."
}