类型与查找列表

类型和查找接口返回只需加载一次的小型参考列表:14 种语言的电影和电视剧类型 ID 与名称,以及国家、语言、幕后职务、年龄分级和流媒体平台。它们使用 TMDB v3 的路径和结构,无需分页,很少变化,可缓存一天。

更新于 以 Markdown 查看

获取电影类型列表

GET /3/genre/movie/list 把每个电影类型返回为一个 id 和一个 name。这些 ID 就是列表条目中 genre_ids 携带的数字,也是发现中 with_genres 所需的值。名称遵循 language 参数。

示例加载列表并构建 ID 到名称的映射,这是大多数应用首先需要的东西。

bashjspyphpgo
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。

响应字段

字段类型说明
genresarray一个响应中包含整个列表,不分页。
genres[].idinteger稳定的类型 ID。
genres[].namestring所请求语言的类型名称。

示例响应

JSON
{
  "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名称
12Adventure
14Fantasy
16Animation
18Drama
27Horror
28Action
35Comedy
36History
37Western
53Thriller
80Crime
99Documentary
878Science Fiction
9648Mystery
10402Music
10749Romance
10751Family
10752War
10759Action & Adventure
10762Kids
10763News
10764Reality
10765Sci-Fi & Fantasy
10766Soap
10767Talk
10768War & Politics
10770TV Movie

电视剧类型列表

GET /3/genre/tv/list 接受同样的 language 参数并返回完全相同的列表,所以一份 ID 到名称的映射就能覆盖电影和电视剧。在列表数据中,ID 10759 以及 10762 到 10768 只出现在电视剧条目上,而 28、12 和 878 这样的 ID 出现在电影条目上。在发现中筛选电视剧时,请使用电视剧的 ID,例如科幻与奇幻的 10765。

查找列表

这些路径返回用于表单、筛选器和设置界面的参考数据。全部需要密钥,都不接受 page。

方法和路径参数每一项或结构
GET /configuration/countries无{ iso_3166_1, english_name, native_name } 数组
GET /configuration/languages无{ iso_639_1, english_name, name } 数组
GET /configuration/primary_translations无由 14 个 ru-RU 这样的字符串组成的数组
GET /configuration/jobs无{ department, jobs } 数组,其中 jobs 列出职务名称
GET /certification/movie/list无以国家代码为键的 { certifications },共 10 个国家
GET /certification/tv/list无以国家代码为键的 { certifications },目录中每个国家一个键
GET /watch/providers/regionslanguage{ iso_3166_1, english_name, native_name } 的 { results }
GET /watch/providers/movielanguage、watch_region平台的 { results }
GET /watch/providers/tvlanguage、watch_region平台的 { results }

/configuration/countries 和 /configuration/languages 会忽略 language,始终返回相同的名称。地区列表中的 native_name 遵循 language。amodb 不提供 /configuration/timezones。

一个分级条目写明分级名称、含义及其排序。条目按国家代码分组,所以一次调用覆盖所有市场。电影列表包含分级说明文字。在电视剧列表中,meaning 是空字符串。

JSON
{
  "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 数组。请传入来自 /watch/providers/regions 的代码。平台标志从图片主机加载,见图片。

JSON
{
  "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
}

这是 /watch/providers/movie?watch_region=US 中的一个条目。

错误

HTTPstatus_code何时出现
4017密钥缺失或错误。
40236套餐周期已结束。
40434路径不存在,例如 /genre/book/list。
40537你对查找路径使用了写入方法。
42925你超过了每分钟请求数。请等待 Retry-After 秒。

每个错误码的详情见错误。套餐限制见速率限制。

实用说明

  • 启动时按语言各加载一次列表,保存在内存或文件中。边缘节点把 /configuration 路径缓存 24 小时,所以你这边每天刷新一次就够了。
  • 在数据库中保存类型 ID,而不是名称。名称会随语言变化,ID 不会。
  • 两个类型路径返回同样的 27 项,所以一份映射覆盖电影和电视剧。ID 10759 以及 10762 到 10768 只出现在电视剧条目上。
  • 发现中的 with_genres=28,12 表示同时是动作和冒险。with_genres=28|12 表示二者之一。
  • 类型名称遵循 language 参数。语言中 14 种基础语言之外的标签回退到英语,在某些语言中个别名称仍是英文,例如意大利语中的 10759。