# Trending and list endpoints > The trending and list endpoints return ranked pages of movies, TV series or people. Use GET /3/trending/{media_type}/{time_window} for day and week charts, plus the movie and tv list paths for popular, top rated, now playing, upcoming, airing today and on the air titles. Every page holds 20 results and is cached for 30 minutes. ## Endpoint `GET /3/trending/{media_type}/{time_window}` ```bash curl "https://api.amodb.dev/3/trending/movie/week?language=en-US" \ -H "Authorization: Bearer $AMODB_KEY" ``` Response: ```json { "page": 1, "results": [ { "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 investigate a mysterious creature wreaking havoc on the community. But all is not as it seems, and perceptions can be misleading. Wha...", "popularity": 294.6518, "poster_path": "/bcK5naYzzfY0JBCgrPrsrbV6NO1.jpg", "release_date": "2026-07-15", "title": "Hope", "video": false, "vote_average": 6.91, "vote_count": 255, "media_type": "movie" }, { "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 revealing they are long-lost siblings… and oh yes, by the way, he is their father. Thrown into a chaotic reunion they never asked fo...", "popularity": 189.8286, "poster_path": "/3x3AfF0qVwSUDDciTaNKcPHZUN8.jpg", "release_date": "2026-10-16", "title": "Masterplan", "video": false, "vote_average": 7.236, "vote_count": 72, "media_type": "movie" }, { "adult": false, "backdrop_path": "/tanwf7KOwQ6dxZzehKsXkffIJOd.jpg", "genre_ids": [ 878, 28, 12 ], "id": 969681, "original_language": "en", "original_title": "Spider-Man: Brand New Day", "overview": "Fighting crime full-time as Spider-Man in a world that doesn't remember him—and the pressure of seeing his old friends move on without him—sparks a change in Peter Parker he may not have the power to control. But that transformation might a...", "popularity": 663.5004, "poster_path": "/bjiS5ipwxb9JFy3XRRN4OAilSeX.jpg", "release_date": "2026-07-29", "title": "Spider-Man: Brand New Day", "video": false, "vote_average": 8.467, "vote_count": 5706, "media_type": "movie" } ], "total_pages": 500, "total_results": 10000 } ``` ## Get trending titles `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. ```bash curl -s "https://api.amodb.dev/3/trending/movie/week?language=en-US&page=1" \ -H "Authorization: Bearer $AMODB_KEY" ``` ```js 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); } ``` ```python 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 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; } ``` ```go 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](https://amodb.dev/movies/), [TV series](https://amodb.dev/tv-series/) or [people](https://amodb.dev/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](https://amodb.dev/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](https://amodb.dev/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](https://amodb.dev/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](https://amodb.dev/errors/) page. Limits per plan are on [rate limits](https://amodb.dev/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](https://amodb.dev/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](https://amodb.dev/movies/) 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. ## Questions and answers ### 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. ## Related pages - [Movie details API](https://amodb.dev/movies/): Movie details API with the same paths and JSON as TMDB v3. Get one movie by id, add credits, ratings and moods with append_to_response, in 14 languages. - [TV series API](https://amodb.dev/tv-series/): TV series API with the same paths and JSON as TMDB v3. Get a show by id with seasons, networks and the next episode, plus content ratings and watch providers. - [Discover API](https://amodb.dev/discover/): Discover API with the same filters as TMDB v3. List movies and TV shows by genre, cast, company, keyword, year, rating, runtime and provider, with sorting. - [Genres and lookup lists](https://amodb.dev/genres/): Genre list API with TMDB v3 paths: movie and TV genre ids with translated names, plus countries, languages, jobs, certifications and watch provider lists. - [Cinema showtimes](https://amodb.dev/showtimes/): Movie showtimes API that returns venues and screening times for a movie in one country, or a country summary. Merge it into details or pair it with now_playing. - [Rate limits](https://amodb.dev/rate-limits/): amodb limits each key by requests per minute in a sliding 60 second window: 20, 40 or 120 by plan. Read the rate limit headers and handle 429 with Retry-After. Updated: 2026-10-18. Source: https://amodb.dev/trending-lists/