搜索 API
搜索接口把文本查询转成 ID。GET /3/search/movie 查找电影,同级路径查找电视剧、人物、系列合集、公司和关键词,multi 一次搜索全部。JSON 与 TMDB v3 一致,每页 20 条,边缘缓存查询 10 分钟。
搜索电影
GET /3/search/movie 接收文本查询,返回分页的匹配电影列表,最佳匹配排在最前。用它把用户输入的内容转成电影 ID,再用这个 ID 调用电影详情。
示例搜索《盗梦空间》,限定为 2010 年,并打印 ID、标题和上映日期。
curl -sSf --get "https://api.amodb.dev/3/search/movie" \
--data-urlencode "query=inception" \
--data-urlencode "year=2010" \
-H "Authorization: Bearer $AMODB_KEY"const params = new URLSearchParams({ query: 'inception', year: '2010', language: 'en-US' });
const res = await fetch(`https://api.amodb.dev/3/search/movie?${params}`, {
headers: { Authorization: `Bearer ${process.env.AMODB_KEY}` },
});
if (!res.ok) throw new Error(`amodb returned ${res.status}`);
const { results, total_results } = await res.json();
console.log(`${total_results} matches`);
for (const m of results.slice(0, 5)) console.log(m.id, m.title, m.release_date);import os
import requests
r = requests.get(
"https://api.amodb.dev/3/search/movie",
params={"query": "inception", "year": 2010, "language": "en-US"},
headers={"Authorization": f"Bearer {os.environ['AMODB_KEY']}"},
timeout=10,
)
r.raise_for_status()
data = r.json()
print(data["total_results"], "matches")
for m in data["results"][:5]:
print(m["id"], m["title"], m["release_date"])<?php
$url = 'https://api.amodb.dev/3/search/movie?' . http_build_query([
'query' => 'inception',
'year' => 2010,
'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");
}
$data = json_decode($body, true);
foreach (array_slice($data['results'], 0, 5) as $m) {
echo $m['id'], ' ', $m['title'], ' ', $m['release_date'], PHP_EOL;
}package main
import (
"encoding/json"
"fmt"
"net/http"
"net/url"
"os"
"time"
)
type SearchPage struct {
TotalResults int `json:"total_results"`
Results []struct {
ID int `json:"id"`
Title string `json:"title"`
ReleaseDate string `json:"release_date"`
} `json:"results"`
}
func main() {
q := url.Values{"query": {"inception"}, "year": {"2010"}, "language": {"en-US"}}
req, _ := http.NewRequest("GET", "https://api.amodb.dev/3/search/movie?"+q.Encode(), 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 p SearchPage
if err := json.NewDecoder(res.Body).Decode(&p); err != nil {
panic(err)
}
fmt.Println(p.TotalResults, "matches")
for _, m := range p.Results {
fmt.Println(m.ID, m.Title, m.ReleaseDate)
}
}参数
query查询必填要搜索的文本。请做 URL 编码:空格变为%20或+。api_key查询二选一你的密钥。使用它,或使用Authorization: Bearer请求头。year查询四位数年份。保留在任何国家有该年上映日期的电影。primary_release_year查询四位数年份。只匹配首次上映日期,所以返回的作品可能比year少。region查询大写的两位国家代码,例如US。已知该国日期时,用该国日期替换release_date。它不会移除作品。include_adult查询接受但被忽略。成人作品永远不会返回。language查询en-US或it-IT这样的 TMDB 标签。提供 14 种基础语言,其他语言回退到英文。默认en-US。page查询页码,1 到 500。默认 1。
响应字段
| 字段 | 类型 | 说明 |
|---|---|---|
page | integer | 你请求的页码。 |
results | array | 最多 20 条,最佳匹配在前。 |
total_pages、total_results | integer | 此查询结果集的大小。上限为 500 页和 10000 条结果。 |
id | integer | 用于详情接口的电影 ID。 |
title、original_title | string | 本地化标题和原始标题。 |
original_language | string | 电影制作语言的两位代码。 |
overview | string | 本地化文本,没有译文时为空。 |
release_date | string | YYYY-MM-DD,没有日期的作品为空。 |
genre_ids | array of integers | 类型 ID,不是名称。用类型映射。 |
poster_path、backdrop_path | string 或 null | 拼接到 https:/。 |
popularity、vote_average、vote_count | number | 排名和评分值。 |
adult、video | boolean | adult 始终为 false。被标记为视频内容的条目,video 为 true。 |
示例响应
{
"page": 1,
"results": [
{
"adult": false,
"backdrop_path": "/zSBVQIvx4UIHoFf1oDvixHyIQrz.jpg",
"genre_ids": [28, 878, 80],
"id": 27205,
"original_language": "en",
"original_title": "Inception",
"overview": "Cobb, a skilled thief who commits corporate espionage by infiltrating the subconscious of his targets is of...",
"popularity": 60.9811,
"poster_path": "/xlaY2zyzMfkhk0HSC5VUwzoZPU1.jpg",
"release_date": "2010-07-15",
"title": "Inception",
"video": false,
"vote_average": 8.373,
"vote_count": 40459
},
{
"adult": false,
"backdrop_path": "/p8K8Z4yjaslJx5mTsIC5L6LJxQB.jpg",
"genre_ids": [16, 28, 53],
"id": 64956,
"original_language": "en",
"original_title": "Inception: The Cobol Job",
"overview": "Cobb, Arthur and Nash are enlisted by Cobol Engineering.",
"popularity": 1.9401,
"poster_path": "/sNxqwtyHMNQwKWoFYDqcYTui5Ok.jpg",
"release_date": "2010-12-07",
"title": "Inception: The Cobol Job",
"video": false,
"vote_average": 7.2,
"vote_count": 320
},
{
"adult": false,
"backdrop_path": null,
"genre_ids": [10402],
"id": 973484,
"original_language": "en",
"original_title": "Inception: Music from the Motion Picture",
"overview": "The Special Features Blu-ray disc contains a lossless DTS-HD MA 5.1 surround mix of the Inception soundtrack.",
"popularity": 0.4911,
"poster_path": "/7uM4DyRVAcgagvhZoWrkrqMPbqV.jpg",
"release_date": "2010-12-07",
"title": "Inception: Music from the Motion Picture",
"video": true,
"vote_average": 7,
"vote_count": 3
}
],
"total_pages": 1,
"total_results": 3
}响应包含全部三条匹配结果。它取自线上 API,只缩短了较长的 overview 字符串。
其他搜索接口
下面每个路径都使用同一个基础地址 https:/,都需要 query,并返回相同的 page、results、total_pages 和 total_results 外层结构。每个接口也都接受 1 到 500 的 page。所有接口都接受 include_adult 并忽略它。
| 方法和路径 | 查找内容 | 额外参数 | 条目字段 |
|---|---|---|---|
GET /search/tv | 电视剧 | first_air_date_year、year、language | name、original_name、first_air_date、origin_country |
GET /search/person | 人物 | language | name、original_name、known_for_department、gender、profile_path、known_for |
GET /search/multi | 电影、电视剧和人物合并 | language | media_type 加上该类型的字段 |
GET /search/collection | 电影系列合集 | language | name、original_name、overview、poster_path、backdrop_path |
GET /search/company | 制作公司 | 无 | name、logo_path、origin_country |
GET /search/keyword | 关键词 | 无 | id、name |
对于电视剧,first_air_date_year 只保留首播日期在该年的剧集,而 year 还会保留更早开播、但在该年播出过的剧集。用 year=2010 搜索 the 会返回 1989 年首播的《辛普森一家》,用 first_ 做同样的搜索则不会。两个参数都传时,必须同时匹配。人物条目最多带 3 个 known_for 作品,每个都有 media_type。/search/multi 会忽略 year。
在这里找到的实体可以继续查看电视剧、人物、系列合集、公司和电视网以及关键词。
multi 搜索
media_type 是 movie、tv 或 person,它告诉你该期望哪些字段。电影条目带有 title,电视剧和人物条目带有 name。
const byType = { movie: [], tv: [], person: [] };
for (const r of results) byType[r.media_type]?.push(r.title || r.name);
console.log(byType);错误
/search/tv 和 /search/person 对没有匹配的查询返回 HTTP 200、空的 results 数组和为 0 的 total_results。目前 /search/movie、/search/multi、/search/keyword、/search/company 和 /search/collection 对同样的情况返回 HTTP 500 和 status_code 11。除非你确定匹配的查询也反复出现 500,否则请把这些路径上的 500 当作没有结果处理。
| HTTP | status_code | 何时出现 |
|---|---|---|
| 401 | 7 | 密钥缺失或错误。 |
| 402 | 36 | 套餐周期已结束。 |
| 405 | 37 | 你调用了写入方法。 |
| 429 | 25 | 超过每分钟请求数。请等待 Retry-After 秒。 |
| 500 | 11 | 电影、multi、关键词、公司或系列合集查询没有匹配,或 page 超出 1 到 500。 |
| 504 | 24 | 后端未在时限内响应。请重试一次。 |