How long are trending and popular lists cached?

The edge caches trending, popular, now playing and on the air lists for 30 minutes and shares each entry across keys. Polling faster than every 30 minutes returns the same page and spends requests for nothing.

How many pages can I read from a list?

Pages run from 1 to 500 with 20 results each, the same limits as TMDB. For deeper browsing use discover, which filters by genre, year, cast or company instead of following one fixed chart.

Which lists accept the region parameter?

now_playing and upcoming take region as an uppercase two letter country code such as GB and keep only titles released there. popular and top_rated accept it but only swap release_date for the local date. The TV lists have no region. airing_today and on_the_air use timezone.

Can I filter a chart by genre?

Not on these paths. List items carry genre_ids for display. To filter by genre use discover with with_genres, and turn ids into names with the genre list endpoints.

Trending movies API: popular, top rated, now playing lists

GET /3/trending/{media_type}/{time_window} returns a ranked page of what people are watching or looking up right now. media_type is all, movie, tv or person. time_window is day or week. Day charts move fast and suit a "tonight" strip. Week charts are steadier and suit a home page.

The example asks for the weekly movie chart and prints the first ten titles.

curl JavaScript Python PHP Go

curl -s "https://api.amodb.dev/3/trending/movie/week?language=en-US&page=1" \
  -H "Authorization: Bearer $AMODB_KEY"

const url = 'https://api.amodb.dev/3/trending/movie/week?language=en-US&page=1';
const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.AMODB_KEY}` } });
if (!res.ok) throw new Error(`amodb returned ${res.status}`);
const chart = await res.json();
for (const [i, m] of chart.results.slice(0, 10).entries()) {
  console.log(i + 1, m.title, m.release_date);
}

import os
import requests

r = requests.get(
    "https://api.amodb.dev/3/trending/movie/week",
    params={"language": "en-US", "page": 1},
    headers={"Authorization": f"Bearer {os.environ['AMODB_KEY']}"},
    timeout=10,
)
r.raise_for_status()
for i, m in enumerate(r.json()["results"][:10], start=1):
    print(i, m["title"], m.get("release_date"))

<?php
$url = 'https://api.amodb.dev/3/trending/movie/week?language=en-US&page=1';
$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 10,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('AMODB_KEY')],
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($status !== 200) {
    throw new RuntimeException("amodb returned $status");
}
$chart = json_decode($body, true);
foreach (array_slice($chart['results'], 0, 10) as $i => $m) {
    echo ($i + 1), ' ', $m['title'], ' ', $m['release_date'] ?? '', PHP_EOL;
}

package main

import (
	"encoding/json"
	"fmt"
	"net/http"
	"os"
	"time"
)

type Chart struct {
	Results []struct {
		Title       string `json:"title"`
		ReleaseDate string `json:"release_date"`
	} `json:"results"`
}

func main() {
	url := "https://api.amodb.dev/3/trending/movie/week?language=en-US&page=1"
	req, _ := http.NewRequest("GET", url, nil)
	req.Header.Set("Authorization", "Bearer "+os.Getenv("AMODB_KEY"))
	client := &http.Client{Timeout: 10 * time.Second}
	res, err := client.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	if res.StatusCode != http.StatusOK {
		panic(res.Status)
	}
	var chart Chart
	if err := json.NewDecoder(res.Body).Decode(&chart); err != nil {
		panic(err)
	}
	for i, m := range chart.Results {
		if i == 10 {
			break
		}
		fmt.Println(i+1, m.Title, m.ReleaseDate)
	}
}

Parameters

Parameter	In	Required	Description
`media_type`	path	yes	`all`, `movie`, `tv` or `person`.
`time_window`	path	yes	`day` or `week`.
`api_key`	query	one of two	Your key. Use this or the `Authorization: Bearer` header.
`language`	query	no	TMDB tag such as `en-US` or `ru-RU`. 14 base languages are served, anything else falls back to English.
`page`	query	no	Page number from 1 to 500. Each page holds 20 results.

Response fields

Field	Type	Notes
`page`	integer	The page you asked for.
`results`	array	Movie, TV or person objects, best rank first.
`total_pages`, `total_results`	integer	Paging totals. Trending charts report at most 500 pages and 10000 results.
`media_type`	string	`movie`, `tv` or `person` on every trending item. Read it when you request `all`.
`id`	integer	Use it with movies, TV series or people.
`title`, `original_title`	string	Movie items. TV items use `name` and `original_name`.
`release_date`, `first_air_date`	string	`YYYY-MM-DD` for movies and TV items.
`genre_ids`	array	Numeric ids. Names come from genres.
`popularity`, `vote_average`, `vote_count`	number	Ranking inputs and the aggregate user score.
`poster_path`, `backdrop_path`, `profile_path`	string or null	Append to `https://img.amodb.dev/t/p/{size}`.
`name`, `original_name`, `gender`, `known_for_department`	string or integer	Person items. `known_for` is an empty array on trending person items.

Example response

JSON

{
  "page": 1,
  "results": [
    {
      "adult": false,
      "backdrop_path": "/7ULXMNvmZSi13zN3EZjz8wbER9B.jpg",
      "genre_ids": [28, 53],
      "id": 1561726,
      "original_language": "en",
      "original_title": "Masterplan",
      "overview": "When a legendary thief sets his sights on the Mona Lisa, he recruits two young strangers to help him before...",
      "popularity": 189.8286,
      "poster_path": "/3x3AfF0qVwSUDDciTaNKcPHZUN8.jpg",
      "release_date": "2026-10-16",
      "title": "Masterplan",
      "video": false,
      "vote_average": 7.279,
      "vote_count": 61,
      "media_type": "movie"
    },
    {
      "adult": false,
      "backdrop_path": "/mBZKC8ActTlM4W3HEGI1Cl1RtO3.jpg",
      "genre_ids": [878, 9648, 28],
      "id": 1058424,
      "original_language": "ko",
      "original_title": "호프",
      "overview": "In the remote South Korean village of Hope Harbor, police chief Bum-seok and officer Sung-ae are called to...",
      "popularity": 294.6518,
      "poster_path": "/bcK5naYzzfY0JBCgrPrsrbV6NO1.jpg",
      "release_date": "2026-07-15",
      "title": "Hope",
      "video": false,
      "vote_average": 6.917,
      "vote_count": 246,
      "media_type": "movie"
    },
    {
      "adult": false,
      "backdrop_path": "/5YfPIIMzGBkIjHt3PTXBWyfBTGS.jpg",
      "genre_ids": [28, 14],
      "id": 1153576,
      "original_language": "en",
      "original_title": "Street Fighter",
      "overview": "In 1993, estranged Street Fighters Ryu and Ken Masters are thrown back into combat when the mysterious Chun...",
      "popularity": 209.3923,
      "poster_path": "/utKzCSCz2HtXwcDGfWLj2IHhSob.jpg",
      "release_date": "2026-10-13",
      "title": "Street Fighter",
      "video": false,
      "vote_average": 6.316,
      "vote_count": 76,
      "media_type": "movie"
    }
  ],
  "total_pages": 500,
  "total_results": 10000
}

The reply was fetched from the live API and cut to 3 of the 20 entries on page 1. Long overview strings are shortened, and ranks and counts change on every refresh.

Movie lists

The movie charts share one shape: a paged results array of movie objects. now_playing and upcoming add a dates object with minimum and maximum, the release window the list covers. All four take language, page and region.

Method and path	Returns
`GET /movie/now_playing`	Movies released inside the `dates` window around today, plus `dates`
`GET /movie/popular`	Movies ranked by current popularity
`GET /movie/top_rated`	Movies ranked by user score
`GET /movie/upcoming`	Movies with a release date ahead, plus `dates`
`GET /movie/latest`	One movie object: the newest entry in the catalog. It is not a list

A real dates object looks like this:

JSON

{ "dates": { "maximum": "2026-10-21", "minimum": "2026-09-09" } }

region is an uppercase ISO 3166-1 code such as DE or GB. On now_playing and upcoming it keeps only titles released in that country, so the list is a small part of the worldwide one. An unknown code returns an empty list. On popular and top_rated it only swaps release_date for the local date and does not change the ranking. To see where a film plays, pair now_playing with showtimes.

TV lists

TV charts return the same paging fields. Items use name, original_name, first_air_date and origin_country in place of the movie names. All four take language and page.

Method and path	Returns	Extra parameters
`GET /tv/airing_today`	Series with an episode airing today	`timezone`
`GET /tv/on_the_air`	Series with an episode airing in the coming days	`timezone`
`GET /tv/popular`	Series ranked by current popularity	none
`GET /tv/top_rated`	Series ranked by user score	none
`GET /tv/latest`	One TV series object: the newest entry in the catalog. It is not a list	none

timezone is an IANA name such as Europe/Rome. It decides which calendar day counts as "today", so airing_today returns a different set for Asia/Tokyo than for Pacific/Auckland. The TV lists have no region parameter.

People lists

GET /person/popular returns a paged list of people ranked by popularity, with language and page. Each entry has id, name, original_name, known_for_department, gender, profile_path, popularity and a known_for array of up to 3 movie or TV cards, each with media_type. Open a person on people.

JSON

{
  "page": 1,
  "results": [
    {
      "adult": false,
      "gender": 1,
      "id": 1247604,
      "known_for_department": "Acting",
      "name": "Agnez Mo",
      "original_name": "Agnez Mo",
      "popularity": 45.8988,
      "profile_path": "/7GuBJxf5szQRCKLk3iG2ztfCo39.jpg",
      "known_for": [
        {
          "adult": false,
          "backdrop_path": "/pF0qkRsrHkdYadPWY9AMeFZfcwk.jpg",
          "first_air_date": "2022-02-03",
          "genre_ids": [10759],
          "id": 108978,
          "name": "Reacher",
          "origin_country": ["US"],
          "original_language": "en",
          "original_name": "Reacher",
          "overview": "Jack Reacher, a veteran military police investigator, has just recently enter...",
          "popularity": 411.841,
          "poster_path": "/f1VCQIG2iCyOookdgOzwtUpwWC0.jpg",
          "vote_average": 8.1,
          "vote_count": 3508,
          "media_type": "tv"
        }
      ]
    }
  ],
  "total_pages": 1001,
  "total_results": 20001
}

amodb does not offer person/latest or the changes feeds.

Pick the right list for a screen

Screen	Call	Refresh
Home page hero row	`/trending/all/week`	Every 30 minutes at most
"In cinemas" tab	`/movie/now_playing` with your `region`	Every 30 minutes at most
"Coming soon" tab	`/movie/upcoming` with your `region`	Every 30 minutes at most
"Tonight on TV" strip	`/tv/airing_today` with a `timezone`	Every 30 minutes at most
All time favourites	`/movie/top_rated`	Daily is enough
People people are looking up	`/trending/person/day`	Every 30 minutes at most
Most popular people overall	`/person/popular`	Every 30 minutes at most

Errors

HTTP	status_code	When
401	7	The key is missing or wrong.
402	36	The plan period has ended.
404	34	The path does not exist, for example a misspelled list name or a `media_type` or `time_window` that is not in the lists above.
405	37	You used a write method on a list path.
429	25	You went over your requests per minute. Wait for the `Retry-After` seconds.
500	11	A `page` above 500.

The full table is on the errors page. Limits per plan are on rate limits.

Practical notes

The edge caches trending, popular, now playing and on the air lists for 30 minutes, and every key shares the same entry. A refresh job that runs every 30 minutes is enough.
Pages go from 1 to 500. Popular lists report total_results of 20001, which is a cap and not a real count. Past page 500, use discover with sort_by and filters, which reaches titles a chart never shows.
List items hold only the fields needed for a card. For runtime, imdb_id or credits call movie details with append_to_response, once per card that the user opens.
language controls the language of titles and overviews. Titles without a translation come back in the original text, so check for empty strings before you render a card.
Store the id from a list, not the position. Ranks change on every refresh.

Get trending titles

Parameters

Response fields

Example response

Movie lists

TV lists

People lists

Pick the right list for a screen

Errors

Practical notes