Trending Movies

This API provides a pre-sorted feed of the most popular and highly-downloaded movies right now. Perfect for populating the “Featured” or “Hot” sections of your streaming app.

Endpoint

POST /api/v1/movies/trending

Request Parameters

The following parameters are accepted in the request body:

Field	Type	Required	Description	Example
limit	integer	Optional	Results per page (Max 50, Default 20).	10
page	integer	Optional	Page number for pagination.	1

Request Examples

cURL

curl -X POST https://heavstal.com.ng/api/v1/movies/trending \
-H "Content-Type: application/json" \
-H "x-api-key: <YOUR_API_KEY>" \
-d '{"limit": 5}'

JavaScript (Fetch)

const response = await fetch('https://heavstal.com.ng/api/v1/movies/trending', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': '<YOUR_API_KEY>'
  },
  body: JSON.stringify({ limit: 5 })
});

const res = await response.json();
console.log(res.data.movies);

Heavstal SDK

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

// Number = results per page (Max 50, Default 20)
const hotMovies = await movies.trending(5);
console.log(`Trending #1: ${hotMovies.movies[0].title}`);

Python

import requests

url = "https://heavstal.com.ng/api/v1/movies/trending"
headers = {
    "Content-Type": "application/json",
    "x-api-key": "<YOUR_API_KEY>"
}
payload = {
    "limit": 5
}

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

Response Examples

Success Response

{
  "status": "success",
  "creator": "HEAVSTAL TECH",
  "cached": false,
  "cache_ttl": 21600,
  "data": {
    "count": 5,
    "page": 1,
    "movies": [
      {
        "id": 2934,
        "title": "Superbad",
        "year": 2007,
        "rating": 7.6,
        "genres": ["Action", "Comedy"],
        "poster": "https://yts.gg/assets/images/movies/Superbad_2007/large-cover.jpg"
      },
      {
        "id": 8462,
        "title": "Avengers: Infinity War",
        "year": 2018,
        "rating": 8.4,
        "genres": ["Action", "Adventure", "Drama", "Fantasy", "Sci-Fi"],
        "poster": "https://yts.gg/assets/images/movies/avengers_infinity_war_2018/large-cover.jpg"
      }
    ]
  }
}

Error Response

{
  "status": "error",
  "error": "Failed to fetch trending movies."
}