Search TV Shows

This API provides a fast and reliable way to search for TV shows by name. It returns a clean array of matching shows, including basic metadata like status, genres, rating, and cover images.

Endpoint

POST /api/v1/tv/search

Request Parameters

The following parameters are accepted in the request body:

Field	Type	Required	Description	Example
`query`	`string`	Yes	The TV show name to search for.	`Breaking Bad`

Request Examples

curl -X POST https://heavstal.com.ng/api/v1/tv/search \
-H "Content-Type: application/json" \
-H "x-api-key: <YOUR_API_KEY>" \
-d '{"query": "Breaking Bad"}'

const response = await fetch('https://heavstal.com.ng/api/v1/tv/search', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': '<YOUR_API_KEY>'
  },
  body: JSON.stringify({
    query: "Breaking Bad"
  })
});

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

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

// Search for a TV show
const results = await tv.search("Breaking Bad");
console.log(results.shows[0].name);

import requests

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

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

{
  "status": "success",
  "creator": "HEAVSTAL TECH",
  "cached": false,
  "cache_ttl": 43200,
  "data": {
    "count": 1,
    "shows": [
      {
        "id": 169,
        "name": "Breaking Bad",
        "status": "Ended",
        "genres": ["Drama", "Crime", "Thriller"],
        "rating": 9.2,
        "image": "https://static.tvmaze.com/uploads/images/medium_portrait/0/2400.jpg",
        "summary": "Breaking Bad follows protagonist Walter White, a chemistry teacher who lives in New Mexico with his wife and teenage son who has cerebral palsy."
      }
    ]
  }
}

{
  "error": "Search query is required.",
  "status": 400
}