# 热门与榜单接口 > 热门与榜单接口返回电影、电视剧或人物的排名分页。GET /3/trending/{media_type}/{time_window} 给出日榜和周榜，电影和电视剧榜单路径给出热门、高分、正在上映等。每页 20 条，缓存 30 分钟。 ## 接口 `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" ``` 响应: ```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": 368.4952, "poster_path": "/bcK5naYzzfY0JBCgrPrsrbV6NO1.jpg", "release_date": "2026-07-15", "title": "Hope", "video": false, "vote_average": 6.9, "vote_count": 256, "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-Li recruits them for the next World Warrior Tournament: a brutal clash of fists, fate, and fury. But behind this battle royale lies...", "popularity": 225.4202, "poster_path": "/utKzCSCz2HtXwcDGfWLj2IHhSob.jpg", "release_date": "2026-10-13", "title": "Street Fighter", "video": false, "vote_average": 6.365, "vote_count": 85, "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": 655.4447, "poster_path": "/bjiS5ipwxb9JFy3XRRN4OAilSeX.jpg", "release_date": "2026-07-29", "title": "Spider-Man: Brand New Day", "video": false, "vote_average": 8.469, "vote_count": 5725, "media_type": "movie" } ], "total_pages": 500, "total_results": 10000 } ``` ## 获取热门作品 `GET /3/trending/{media_type}/{time_window}` 返回人们此刻正在观看或查询内容的排名分页。`media_type` 为 `all`、`movie`、`tv` 或 `person`。`time_window` 为 `day` 或 `week`。日榜变化很快，适合今晚栏目。周榜更稳定，适合首页。 示例请求每周电影榜并打印前十部作品。 ```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) } } ``` ### 参数 | 参数 | 位置 | 必填 | 说明 | | ------------- | -- | --- | ---------------------------------------------------- | | `media_type` | 路径 | 是 | `all`、`movie`、`tv` 或 `person`。 | | `time_window` | 路径 | 是 | `day` 或 `week`。 | | `api_key` | 查询 | 二选一 | 你的密钥。使用它，或使用 `Authorization: Bearer` 请求头。 | | `language` | 查询 | 否 | `en-US` 或 `ru-RU` 这样的 TMDB 标签。提供 14 种基础语言，其他一律回退到英文。 | | `page` | 查询 | 否 | 页码，1 到 500。每页 20 条结果。 | ### 响应字段 | 字段 | 类型 | 说明 | | ------------------------------------------------------ | ---------------- | ----------------------------------------------------------------------------------------------------------------- | | `page` | integer | 你请求的页码。 | | `results` | array | 电影、电视剧或人物对象，排名最高的在前。 | | `total_pages`、`total_results` | integer | 分页总数。热门榜最多报告 500 页和 10000 条结果。 | | `media_type` | string | 每个热门条目上的 `movie`、`tv` 或 `person`。请求 `all` 时请读取它。 | | `id` | integer | 配合[电影](https://amodb.dev/zh/movies/)、[电视剧](https://amodb.dev/zh/tv-series/)或[人物](https://amodb.dev/zh/people/)使用。 | | `title`、`original_title` | string | 电影条目。电视剧条目使用 `name` 和 `original_name`。 | | `release_date`、`first_air_date` | string | 电影和电视剧条目的 `YYYY-MM-DD`。 | | `genre_ids` | array | 数字 ID。名称来自[类型](https://amodb.dev/zh/genres/)。 | | `popularity`、`vote_average`、`vote_count` | number | 排名依据和汇总用户评分。 | | `poster_path`、`backdrop_path`、`profile_path` | string 或 null | 拼接到 `https://img.amodb.dev/t/p/{size}`。 | | `name`、`original_name`、`gender`、`known_for_department` | string 或 integer | 人物条目。热门人物条目的 `known_for` 是空数组。 | ### 示例响应 ```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 } ``` 响应取自线上 API，并缩减为第 1 页 20 条中的 3 条。较长的 `overview` 字符串已缩短，排名和计数在每次刷新时都会变化。 ## 电影榜单 电影榜单结构相同：由电影对象组成的分页 `results` 数组。`now_playing` 和 `upcoming` 还会多一个带 `minimum` 和 `maximum` 的 `dates` 对象，即榜单覆盖的上映窗口。四个榜单都接受 `language`、`page` 和 `region`。 | 方法和路径 | 返回内容 | | ------------------------ | --------------------------------- | | `GET /movie/now_playing` | 在今天前后 `dates` 窗口内上映的电影，外加 `dates` | | `GET /movie/popular` | 按当前热度排名的电影 | | `GET /movie/top_rated` | 按用户评分排名的电影 | | `GET /movie/upcoming` | 上映日期在未来的电影，外加 `dates` | | `GET /movie/latest` | 一个电影对象：目录中最新的条目。它不是列表 | 真实的 `dates` 对象如下： ```json { "dates": { "maximum": "2026-10-21", "minimum": "2026-09-09" } } ``` `region` 是大写的 ISO 3166-1 代码，例如 `DE` 或 `GB`。在 `now_playing` 和 `upcoming` 上，它只保留在该国上映的作品，所以榜单只是全球榜单的一小部分。未知代码返回空列表。在 `popular` 和 `top_rated` 上，它只是把 `release_date` 换成当地日期，不改变排名。想知道一部电影在哪里放映，请把 `now_playing` 与[放映时间](https://amodb.dev/zh/showtimes/)搭配使用。 ## 电视剧榜单 电视剧榜单返回相同的分页字段。条目用 `name`、`original_name`、`first_air_date` 和 `origin_country` 代替电影的字段名。四个榜单都接受 `language` 和 `page`。 | 方法和路径 | 返回内容 | 额外参数 | | ---------------------- | ---------------------- | ---------- | | `GET /tv/airing_today` | 今天有一集播出的剧集 | `timezone` | | `GET /tv/on_the_air` | 未来几天内有一集播出的剧集 | `timezone` | | `GET /tv/popular` | 按当前热度排名的剧集 | 无 | | `GET /tv/top_rated` | 按用户评分排名的剧集 | 无 | | `GET /tv/latest` | 一个电视剧对象：目录中最新的条目。它不是列表 | 无 | `timezone` 是 IANA 名称，例如 `Europe/Rome`。它决定哪个日历日算作今天，所以 `airing_today` 对 `Asia/Tokyo` 与对 `Pacific/Auckland` 返回的集合不同。电视剧榜单没有 `region` 参数。 ## 人物榜单 `GET /person/popular` 返回按热度排名的人物分页列表，接受 `language` 和 `page`。每个条目有 `id`、`name`、`original_name`、`known_for_department`、`gender`、`profile_path`、`popularity` 和一个 `known_for` 数组，其中最多有 3 张电影或电视剧卡片，每张都带 `media_type`。在[人物](https://amodb.dev/zh/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 不提供 `person/latest` 或 `changes` 数据流。 ## 为每个界面选对榜单 | 界面 | 调用 | 刷新 | | --------- | ----------------------------------- | ----------- | | 首页主视觉行 | `/trending/all/week` | 最多每 30 分钟一次 | | 影院热映标签页 | 带你的 `region` 的 `/movie/now_playing` | 最多每 30 分钟一次 | | 即将上映标签页 | 带你的 `region` 的 `/movie/upcoming` | 最多每 30 分钟一次 | | 今晚电视栏目 | 带 `timezone` 的 `/tv/airing_today` | 最多每 30 分钟一次 | | 历来最爱 | `/movie/top_rated` | 每天一次就够 | | 人们正在查询的人物 | `/trending/person/day` | 最多每 30 分钟一次 | | 总体最热门的人物 | `/person/popular` | 最多每 30 分钟一次 | ## 错误 | HTTP | status_code | 何时出现 | | ---- | ----------- | ------------------------------------------------------- | | 401 | 7 | 密钥缺失或错误。 | | 402 | 36 | 套餐周期已结束。 | | 404 | 34 | 路径不存在，例如拼错的榜单名称，或不在上面列表中的 `media_type` 或 `time_window`。 | | 405 | 37 | 你对榜单路径使用了写入方法。 | | 429 | 25 | 超过了每分钟请求数。请等待 `Retry-After` 秒。 | | 500 | 11 | `page` 超过 500。 | 完整表格见[错误](https://amodb.dev/zh/errors/)页面。各套餐的限制见[速率限制](https://amodb.dev/zh/rate-limits/)。 ## 实用说明 - 边缘缓存会把热门、流行、正在上映和正在播出的榜单保留 30 分钟，所有密钥共享同一个条目。每 30 分钟运行一次的刷新任务就足够了。 - 页码范围为 1 到 500。热门榜单报告的 `total_results` 为 20001，这是上限而不是真实数量。超过第 500 页后，请使用带 `sort_by` 和筛选条件的[发现 API](https://amodb.dev/zh/discover/)，它能触达榜单永远不会显示的作品。 - 榜单条目只包含卡片所需的字段。要获取片长、imdb_id 或演职员，请在用户每打开一张卡片时，用 `append_to_response` 调用[电影详情](https://amodb.dev/zh/movies/)一次。 - `language` 控制标题和简介的语言。没有译文的标题会以原文返回，所以渲染卡片前请检查空字符串。 - 保存榜单中的 `id`，而不是位置。排名在每次刷新时都会变化。 ## 常见问题 ### 热门和流行榜单缓存多久？ 边缘缓存会把热门、流行、正在上映和正在播出的榜单保留 30 分钟，并在各密钥之间共享每个条目。轮询频率高于每 30 分钟一次只会得到同一页，并白白消耗请求。 ### 一个榜单我能读取多少页？ 页码范围是 1 到 500，每页 20 条结果，与 TMDB 的限制相同。要更深入地浏览，请使用 discover，它按类型、年份、演员或公司筛选，而不是沿着某一个固定榜单。 ### 哪些榜单接受 region 参数？ now_playing 和 upcoming 接受 region，需为大写两位国家代码，例如 GB，并只保留在该国上映的作品。popular 和 top_rated 也接受它，但只是把 release_date 换成当地日期。电视剧榜单没有 region，airing_today 和 on_the_air 使用 timezone。 ### 可以按类型筛选榜单吗？ 这些路径不行。榜单条目带有 genre_ids 供展示。要按类型筛选，请使用带 with_genres 的 discover，并用类型列表接口把 ID 转成名称。 ## 相关页面 - [电影详情 API](https://amodb.dev/zh/movies/): 路径和 JSON 与 TMDB v3 相同的电影详情 API：按 ID 取电影，用 append_to_response 加入演职员和评分，支持 14 种语言。 - [电视剧 API](https://amodb.dev/zh/tv-series/): 路径和 JSON 与 TMDB v3 相同的电视剧 API。按 ID 获取剧集的季、电视网和下一集，以及内容分级和观看平台。 - [发现 API](https://amodb.dev/zh/discover/): 与 TMDB v3 筛选条件相同的 discover API。按类型、演员、公司、关键词、年份、评分、时长和平台列出电影和剧集，并可排序。 - [类型与查找列表](https://amodb.dev/zh/genres/): 采用 TMDB v3 路径的类型列表 API：带译名的电影和电视剧类型 ID，以及国家、语言、职务、年龄分级和流媒体平台列表。 - [影院放映时间](https://amodb.dev/zh/showtimes/): 返回某国家某部电影的影院和放映时间的 API，也可只取国家汇总。可并入详情调用，或与 now_playing 搭配使用。 - [速率限制](https://amodb.dev/zh/rate-limits/): amodb 按滑动 60 秒窗口内每分钟请求数限制每个密钥：按套餐为 20、40 或 120。读取速率限制响应头，并用 Retry-After 处理 429。 更新于: 2026-10-18. Source: https://amodb.dev/zh/trending-lists/