搜索 API

搜索接口把文本查询转成 ID。GET /3/search/movie 查找电影,同级路径查找电视剧、人物、系列合集、公司和关键词,multi 一次搜索全部。JSON 与 TMDB v3 一致,每页 20 条,边缘缓存查询 10 分钟。

更新于 以 Markdown 查看

搜索电影

GET /3/search/movie 接收文本查询,返回分页的匹配电影列表,最佳匹配排在最前。用它把用户输入的内容转成电影 ID,再用这个 ID 调用电影详情。

示例搜索《盗梦空间》,限定为 2010 年,并打印 ID、标题和上映日期。

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

响应字段

字段类型说明
pageinteger你请求的页码。
resultsarray最多 20 条,最佳匹配在前。
total_pages、total_resultsinteger此查询结果集的大小。上限为 500 页和 10000 条结果。
idinteger用于详情接口的电影 ID。
title、original_titlestring本地化标题和原始标题。
original_languagestring电影制作语言的两位代码。
overviewstring本地化文本,没有译文时为空。
release_datestringYYYY-MM-DD,没有日期的作品为空。
genre_idsarray of integers类型 ID,不是名称。用类型映射。
poster_path、backdrop_pathstring 或 null拼接到 https://img.amodb.dev/t/p/{size}。
popularity、vote_average、vote_countnumber排名和评分值。
adult、videobooleanadult 始终为 false。被标记为视频内容的条目,video 为 true。

示例响应

JSON
{
  "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://api.amodb.dev/3,都需要 query,并返回相同的 page、results、total_pages 和 total_results 外层结构。每个接口也都接受 1 到 500 的 page。所有接口都接受 include_adult 并忽略它。

方法和路径查找内容额外参数条目字段
GET /search/tv电视剧first_air_date_year、year、languagename、original_name、first_air_date、origin_country
GET /search/person人物languagename、original_name、known_for_department、gender、profile_path、known_for
GET /search/multi电影、电视剧和人物合并languagemedia_type 加上该类型的字段
GET /search/collection电影系列合集languagename、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_air_date_year=2010 做同样的搜索则不会。两个参数都传时,必须同时匹配。人物条目最多带 3 个 known_for 作品,每个都有 media_type。/search/multi 会忽略 year。

在这里找到的实体可以继续查看电视剧、人物、系列合集、公司和电视网以及关键词。

multi 搜索

media_type 是 movie、tv 或 person,它告诉你该期望哪些字段。电影条目带有 title,电视剧和人物条目带有 name。

JavaScript
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 当作没有结果处理。

HTTPstatus_code何时出现
4017密钥缺失或错误。
40236套餐周期已结束。
40537你调用了写入方法。
42925超过每分钟请求数。请等待 Retry-After 秒。
50011电影、multi、关键词、公司或系列合集查询没有匹配,或 page 超出 1 到 500。
50424后端未在时限内响应。请重试一次。

完整列表见错误,各窗口见速率限制。

实用说明

  • 边缘缓存会把搜索结果保留 10 分钟,并在各密钥之间共享该副本。每次调用仍然计入你每分钟 20、40 或 120 个请求,因为速率限制在缓存之前执行。
  • 做搜索框时,在最后一次按键后等待 300 毫秒,并取消正在进行的请求。每次按键都发请求的搜索框,可能在几秒内用完每分钟 20 个请求的套餐。
  • 在你这一侧把查询用作缓存键之前,先转成小写并去掉首尾空白。
  • 要按 IMDb ID 查找作品,请跳过搜索,使用按外部 ID 查找。
  • /search/keyword 返回的关键词 ID 可用于发现 API 的 with_keywords 筛选,公司 ID 可用于 with_companies。