查找与搜索方法
学习并练习TMDB API中的查找和搜索方法。
我们将在这节课中讨论两种在 TMDB 上搜索电影、电视剧和人物的方法。
find 接口
我们可以使用 TMDB 的 find 接口，通过一个字符串类型的路径参数 external_id，仅凭外部 ID 来搜索数据库中的对象。该方法会搜索所有类型的对象（电影、电视剧和人物），并将结果以单一 JSON 响应返回。
注意： find 接口使用外部 ID 作为路径参数。有关外部 ID 的详细信息以及如何获取它们，请参阅本课程相关内容。
支持的外部数据源及其适用对象如下：
| 名称 | 类型 | 电影 | 电视剧 | 电视剧季 | 电视剧集 | 人物 |
|---|---|---|---|---|---|---|
| IMDb ID | 媒体数据库 | ✓ | ✓ | ✗ | ✓ | ✓ |
| TVDB ID | 媒体数据库 | ✗ | ✓ | ✓ | ✓ | ✗ |
| 社交 ID | ✓ | ✓ | ✗ | ✗ | ✓ | |
| 社交 ID | ✓ | ✓ | ✗ | ✗ | ✓ | |
| 社交 ID | ✓ | ✓ | ✗ | ✗ | ✓ |
此接口的输入查询参数如下：
| 名称 | 类型 | 类别 | 描述 |
|---|---|---|---|
| language | 字符串 | 可选 | 使用 ISO_3166_1 代码指定语言，用于获取对应语言的翻译数据。仅适用于支持该功能的字段。默认值为 en-US。 |
| external_source | 字符串 | 必需 | 指定用于查找对象的外部数据源，需与所用外部 ID 匹配。 |
返回的 JSON 响应中包含的对象如下：
| 对象 | 类型 | 类别 | 描述 |
|---|---|---|---|
| movie_results | 对象数组 | 可选 | 若传入的是电影的外部 ID，则返回对应的电影详情。 |
| person_results | 对象数组 | 可选 | 若传入的是人物的外部 ID，则返回对应人物的信息。 |
| tv_results | 对象数组 | 可选 | 若传入的是电视剧的外部 ID，则返回对应电视剧的详情。 |
| tv_episode_results | 对象数组 | 可选 | 若传入的是电视剧某一集的外部 ID，则返回该集的详情。 |
| tv_season_results | 对象数组 | 可选 | 若传入的是电视剧某一季的外部 ID，则返回该季的详情。 |
让我们通过下方代码工具尝试运行一个 find 方法的示例。请确保在运行程序前已正确填写 API_KEY、对象的 EXTERNAL_ID 以及 EXTERNAL_SOURCE。虽然我们可以通过相关课程了解如何获取任意对象的外部 ID，但目前可以使用以下示例外部 ID 及其来源来查找《蜘蛛侠：无路可退》。
| 外部数据源 | 外部 ID |
|---|---|
| facebook_id | SpiderManMovie |
| imdb_id | tt10872600 |
| instagram_id | spidermanmovie |
| twitter_id | spidermanmovie |
点击“运行”按钮，根据外部 ID 查找该电影。
1import json 2import requests 3from pprint import pprint 4 5api_key = '{{API_KEY}}' 6language = 'en-US' 7external_source = '{{EXTERNAL_SOURCE}}' 8 9response = requests.get("https://api.themoviedb.org/3/find/{{EXTERNAL_ID}}", 10 params={'api_key': api_key, 11 'language': language, 12 'external_source': external_source}) 13 14# 美化并打印 JSON 响应 15pprint(response.json())
我们已经成功通过 IMDb ID 找到了该电影的信息。如需进一步探索结果，可重新输入 EXTERNAL_ID 与 EXTERNAL_SOURCE 的值。
find 方法在开发者已有工具系统时非常有用，便于将其集成到现有服务中。
search 接口
基于文本的搜索是互联网上最常用的搜索方式之一。我们提供一个查询字符串，系统将返回可能的匹配项。
对于 TMDB 的文本搜索，我们使用 search 接口。该接口通过一个类型为字符串的查询参数 query，可在数据库中搜索任意对象。基于文本的搜索会考虑所有原始名称、翻译名称、替代名称及标题。
此处是关注的基地址：
1https://api.themoviedb.org/3/search?api_key={ourTMDBapikey}&query="ourQUERYstring"
此接口的输入查询参数如下：
| 名称 | 类型 | 类别 | 描述 |
|---|---|---|---|
| query | 字符串 | 必需 | 用于搜索的文本查询内容，其值必须进行 URI 编码。 |
| page | 整数 | 可选 | 指定要查询的页码，取值范围为 1 到 1000（含）。默认值为 1。 |
输出 JSON 响应中的对象如下：
| 对象 | 类型 | 类别 | 描述 |
|---|---|---|---|
| page | 整数 | 可选 | 当前查询的页码。 |
| results | 对象数组 | 可选 | 返回指定页面上所有最接近的匹配项（含详细信息），例如第一页有 21 个匹配项，第二页有 20 个等。 |
| total_pages | 整数 | 可选 | 在 TMDB 中包含匹配结果的总页数。 |
| total_results | 整数 | 可选 | 在 TMDB 中所有最接近匹配项的总数。 |
现在，我们可以通过下方代码工具尝试运行一个基于文本的搜索示例。在运行程序前，请确保已填写正确的 API_KEY。点击“运行”按钮，获取查询字符串的所有搜索结果。
1import json 2import requests 3from pprint import pprint 4 5api_key = '{{API_KEY}}' 6query = 'the+office' 7page = 1 8 9response = requests.get("https://api.themoviedb.org/3/search/tv", 10 params={'api_key': api_key, 11 'query': query, 12 'page': page}) 13 14# 美化并打印 JSON 响应 15pprint(response.json())
我们已成功获取了电视剧《办公室》的所有可能匹配结果。您可以在第 9 行修改基础 URL，以搜索 TMDB 中的不同对象。例如，若要搜索电影，可使用以下地址：
1https://api.themoviedb.org/3/search/movie
同样，若要搜索人物，可使用以下命令：
1https://api.themoviedb.org/3/search/person