类型与查找列表
类型和查找接口返回只需加载一次的小型参考列表:14 种语言的电影和电视剧类型 ID 与名称,以及国家、语言、幕后职务、年龄分级和流媒体平台。它们使用 TMDB v3 的路径和结构,无需分页,很少变化,可缓存一天。
获取电影类型列表
GET / 把每个电影类型返回为一个 id 和一个 name。这些 ID 就是列表条目中 genre_ids 携带的数字,也是发现中 with_genres 所需的值。名称遵循 language 参数。
示例加载列表并构建 ID 到名称的映射,这是大多数应用首先需要的东西。
curl -s "https://api.amodb.dev/3/genre/movie/list?language=en-US" \
-H "Authorization: Bearer $AMODB_KEY"const url = 'https://api.amodb.dev/3/genre/movie/list?language=en-US';
const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.AMODB_KEY}` } });
if (!res.ok) throw new Error(`amodb returned ${res.status}`);
const { genres } = await res.json();
const names = new Map(genres.map((g) => [g.id, g.name]));
console.log(names.get(878), names.size);import os
import requests
r = requests.get(
"https://api.amodb.dev/3/genre/movie/list",
params={"language": "en-US"},
headers={"Authorization": f"Bearer {os.environ['AMODB_KEY']}"},
timeout=10,
)
r.raise_for_status()
names = {g["id"]: g["name"] for g in r.json()["genres"]}
print(names[878], len(names))<?php
$url = 'https://api.amodb.dev/3/genre/movie/list?language=en-US';
$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");
}
$names = [];
foreach (json_decode($body, true)['genres'] as $g) {
$names[$g['id']] = $g['name'];
}
echo $names[878], ' ', count($names), PHP_EOL;package main
import (
"encoding/json"
"fmt"
"net/http"
"os"
"time"
)
type Genres struct {
Genres []struct {
ID int `json:"id"`
Name string `json:"name"`
} `json:"genres"`
}
func main() {
url := "https://api.amodb.dev/3/genre/movie/list?language=en-US"
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 g Genres
if err := json.NewDecoder(res.Body).Decode(&g); err != nil {
panic(err)
}
names := map[int]string{}
for _, x := range g.Genres {
names[x.ID] = x.Name
}
fmt.Println(names[878], len(names))
}参数
api_key查询二选一你的密钥。使用它,或使用Authorization: Bearer请求头。language查询en-US、ru-RU或pt-BR这样的 TMDB 标签。名称以该语言返回。默认en-US。
响应字段
| 字段 | 类型 | 说明 |
|---|---|---|
genres | array | 一个响应中包含整个列表,不分页。 |
genres[].id | integer | 稳定的类型 ID。 |
genres[].name | string | 所请求语言的类型名称。 |
示例响应
{
"genres": [
{ "id": 12, "name": "Adventure" },
{ "id": 14, "name": "Fantasy" },
{ "id": 16, "name": "Animation" },
{ "id": 18, "name": "Drama" }
]
}响应包含 27 个类型,按 ID 排序。这里只保留前 4 个。
类型 ID
两个类型路径都返回这 27 个类型,按 ID 排序。下面的名称是英文名。其他语言返回相同的 ID 和翻译后的名称。
| ID | 名称 |
|---|---|
| 12 | Adventure |
| 14 | Fantasy |
| 16 | Animation |
| 18 | Drama |
| 27 | Horror |
| 28 | Action |
| 35 | Comedy |
| 36 | History |
| 37 | Western |
| 53 | Thriller |
| 80 | Crime |
| 99 | Documentary |
| 878 | Science Fiction |
| 9648 | Mystery |
| 10402 | Music |
| 10749 | Romance |
| 10751 | Family |
| 10752 | War |
| 10759 | Action & Adventure |
| 10762 | Kids |
| 10763 | News |
| 10764 | Reality |
| 10765 | Sci-Fi & Fantasy |
| 10766 | Soap |
| 10767 | Talk |
| 10768 | War & Politics |
| 10770 | TV Movie |
电视剧类型列表
GET /3/genre/tv/list 接受同样的 language 参数并返回完全相同的列表,所以一份 ID 到名称的映射就能覆盖电影和电视剧。在列表数据中,ID 10759 以及 10762 到 10768 只出现在电视剧条目上,而 28、12 和 878 这样的 ID 出现在电影条目上。在发现中筛选电视剧时,请使用电视剧的 ID,例如科幻与奇幻的 10765。
查找列表
这些路径返回用于表单、筛选器和设置界面的参考数据。全部需要密钥,都不接受 page。
| 方法和路径 | 参数 | 每一项或结构 |
|---|---|---|
GET / | 无 | { iso_ 数组 |
GET / | 无 | { iso_ 数组 |
GET / | 无 | 由 14 个 ru-RU 这样的字符串组成的数组 |
GET / | 无 | { department, jobs } 数组,其中 jobs 列出职务名称 |
GET / | 无 | 以国家代码为键的 { certifications },共 10 个国家 |
GET / | 无 | 以国家代码为键的 { certifications },目录中每个国家一个键 |
GET / | language | { iso_ 的 { results } |
GET / | language、watch_region | 平台的 { results } |
GET / | language、watch_region | 平台的 { results } |
/ 和 / 会忽略 language,始终返回相同的名称。地区列表中的 native_name 遵循 language。amodb 不提供 /。
一个分级条目写明分级名称、含义及其排序。条目按国家代码分组,所以一次调用覆盖所有市场。电影列表包含分级说明文字。在电视剧列表中,meaning 是空字符串。
{
"certifications": {
"US": [
{ "certification": "PG", "meaning": "Some material may not be suitable for children under 10.", "order": 3 },
{ "certification": "R", "meaning": "Under 17 requires accompanying parent or adult guardian.", "order": 5 }
]
}
}示例缩减为 6 个美国条目中的 2 个。电影列表覆盖 AU、BR、CA、DE、ES、FR、GB、IT、RU 和 US。
一个平台条目包含 provider_id、provider_name、logo_path、display_priority 和 display_priorities,后者是国家代码到优先级的映射。不带 watch_region 时会得到所有平台。带 watch_region=US 时只保留服务该国家的平台。未知地区返回空的 results 数组。请传入来自 / 的代码。平台标志从图片主机加载,见图片。
{
"display_priorities": { "AT": 1, "DE": 1, "GB": 1, "JP": 1, "US": 3 },
"display_priority": 3,
"logo_path": "/gMZdpavHmxFNnLpMHwVxfqeux2g.png",
"provider_name": "Amazon Prime Video",
"provider_id": 9
}这是 / 中的一个条目。
错误
| HTTP | status_code | 何时出现 |
|---|---|---|
| 401 | 7 | 密钥缺失或错误。 |
| 402 | 36 | 套餐周期已结束。 |
| 404 | 34 | 路径不存在,例如 /genre/book/list。 |
| 405 | 37 | 你对查找路径使用了写入方法。 |
| 429 | 25 | 你超过了每分钟请求数。请等待 Retry-After 秒。 |
实用说明
- 启动时按语言各加载一次列表,保存在内存或文件中。边缘节点把
/configuration路径缓存 24 小时,所以你这边每天刷新一次就够了。 - 在数据库中保存类型 ID,而不是名称。名称会随语言变化,ID 不会。
- 两个类型路径返回同样的 27 项,所以一份映射覆盖电影和电视剧。ID 10759 以及 10762 到 10768 只出现在电视剧条目上。
- 发现中的
with_genres=28,12表示同时是动作和冒险。with_genres=28|12表示二者之一。 - 类型名称遵循
language参数。语言中 14 种基础语言之外的标签回退到英语,在某些语言中个别名称仍是英文,例如意大利语中的10759。