API ключавых слоў
Эндпоінты ключавых слоў вяртаюць тэгі сюжэта, прывязаныя да фільма або серыяла, кожны як id і назва. Можна знайсці адно ключавое слова, пералічыць фільмы з ім або перадаць id у discover праз with_keywords, каб пабудаваць тэматычныя старонкі. Фільмы адказваюць пад ключом keywords, серыялы пад ключом results.
Атрыманне ключавых слоў фільма
GET / вяртае тэгі сюжэта аднаго фільма. Ключавое слова гэта кароткая фраза, напрыклад тэма, месца дзеяння або тып крыніцы, і яно мае лікавы id, які можна выкарыстоўваць у пошуку па фільтрах.
У прыкладзе загружаюцца ключавыя словы фільма, а потым у discover запытваюцца самыя папулярныя фільмы з тым жа першым ключавым словам.
curl -s "https://api.amodb.dev/3/movie/550/keywords" \
-H "Authorization: Bearer $AMODB_KEY"
curl -s "https://api.amodb.dev/3/discover/movie?with_keywords=818&sort_by=popularity.desc" \
-H "Authorization: Bearer $AMODB_KEY"const base = 'https://api.amodb.dev/3';
const headers = { Authorization: `Bearer ${process.env.AMODB_KEY}` };
const kw = await fetch(`${base}/movie/550/keywords`, { headers });
if (!kw.ok) throw new Error(`keywords failed with ${kw.status}`);
const { keywords } = await kw.json();
console.log(keywords.map((k) => `${k.id}:${k.name}`).join(', '));
if (keywords.length > 0) {
const first = keywords[0];
const found = await fetch(`${base}/discover/movie?with_keywords=${first.id}&sort_by=popularity.desc`, { headers });
if (!found.ok) throw new Error(`discover failed with ${found.status}`);
const page = await found.json();
console.log(first.name, page.results.slice(0, 5).map((m) => m.title));
}import os
import requests
base = "https://api.amodb.dev/3"
headers = {"Authorization": f"Bearer {os.environ['AMODB_KEY']}"}
r = requests.get(f"{base}/movie/550/keywords", headers=headers, timeout=10)
r.raise_for_status()
keywords = r.json()["keywords"]
print(", ".join(f"{k['id']}:{k['name']}" for k in keywords))
if keywords:
first = keywords[0]
d = requests.get(
f"{base}/discover/movie",
params={"with_keywords": first["id"], "sort_by": "popularity.desc"},
headers=headers,
timeout=10,
)
d.raise_for_status()
print(first["name"], [m["title"] for m in d.json()["results"][:5]])<?php
function amodb_get(string $url): array {
$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");
}
return json_decode($body, true);
}
$base = 'https://api.amodb.dev/3';
$keywords = amodb_get("$base/movie/550/keywords")['keywords'];
if ($keywords) {
$first = $keywords[0];
$found = amodb_get("$base/discover/movie?with_keywords={$first['id']}&sort_by=popularity.desc");
$titles = array_column(array_slice($found['results'], 0, 5), 'title');
echo $first['name'], ': ', implode(', ', $titles), PHP_EOL;
}package main
import (
"encoding/json"
"fmt"
"net/http"
"os"
"time"
)
var client = &http.Client{Timeout: 10 * time.Second}
func get(path string, out any) error {
req, _ := http.NewRequest("GET", "https://api.amodb.dev/3"+path, nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("AMODB_KEY"))
res, err := client.Do(req)
if err != nil {
return err
}
defer res.Body.Close()
if res.StatusCode != http.StatusOK {
return fmt.Errorf("amodb returned %s", res.Status)
}
return json.NewDecoder(res.Body).Decode(out)
}
type Keywords struct {
Keywords []struct {
ID int `json:"id"`
Name string `json:"name"`
} `json:"keywords"`
}
type Page struct {
Results []struct {
Title string `json:"title"`
} `json:"results"`
}
func main() {
var kw Keywords
if err := get("/movie/550/keywords", &kw); err != nil {
panic(err)
}
if len(kw.Keywords) == 0 {
return
}
first := kw.Keywords[0]
var page Page
if err := get(fmt.Sprintf("/discover/movie?with_keywords=%d&sort_by=popularity.desc", first.ID), &page); err != nil {
panic(err)
}
fmt.Println(first.Name)
for i, m := range page.Results {
if i == 5 {
break
}
fmt.Println(" ", m.Title)
}
}Параметры
movie_idшляхабавязковыЛікавы id фільма, напрыклад550.api_keyзапытадзін з двухВаш ключ. Выкарыстоўвайце яго або загаловакAuthorization: Bearer.
Палі адказу
| Поле | Тып | Заўвагі |
|---|---|---|
id | цэлы лік | Id фільма. |
keywords | масіў | Аб’екты з id і name. Пусты, калі ў фільма іх няма. |
keywords[].id | цэлы лік | Id ключавога слова. Выкарыстоўвайце яго ў with_keywords і ў шляхах ключавых слоў ніжэй. |
keywords[].name | радок | Тэкст ключавога слова. |
Прыклад адказу
{
"id": 550,
"keywords": [
{ "id": 818, "name": "based on novel or book" },
{ "id": 825, "name": "support group" },
{ "id": 851, "name": "dual identity" }
]
}Сапраўдны адказ змяшчае 14 ключавых слоў. Гэты скарочаны да першых 3. Назвы ключавых слоў не перакладаюцца, таму language тут не дзейнічае.
Ключавыя словы серыяла
GET / прымае той жа ключ і вяртае тыя ж аб’екты, але масіў называецца results. Id у шляху гэта id серыяла, напрыклад 1396.
{
"id": 1396,
"results": [
{ "id": 1508, "name": "new mexico" },
{ "id": 2231, "name": "drug dealer" }
]
}Сапраўдны адказ змяшчае 29 запісаў, а гэты скарочаны да першых 2. Кліент, які абслугоўвае абодва тыпы медыя, можа чытаць data.keywords ? і апрацоўваць іх аднолькава.
Запісы ключавых слоў і іх фільмы
| Метад і шлях | Што вяртае | Параметры |
|---|---|---|
GET / | { id, name } | няма |
GET / | Спіс фільмаў па старонках з id, page, results, total_pages, total_results | language, page |
Абодва шляхі выкарыстоўваюць лікавы id з масіва ключавых слоў. Спіс фільмаў дае ту ж форму запісу, што іншыя спісы фільмаў, уключна з genre_ids і poster_path, плюс id ключавога слова зверху. include_adult прымаецца і ігнаруецца. Старонка пасля total_pages вяртае пусты масіў results. Спісу серыялаў для ключавога слова няма, таму для серыялаў выкарыстоўвайце /.
Спалучэнне ключавых слоў з discover
Для ўсяго, што большае за простую выбарку, фільтруйце ў пошуку па фільтрах. Ён сартуе, ідзе па старонках і спалучае ключавыя словы з іншымі фільтрамі, а таксама ахоплівае серыялы разам з фільмамі.
| Мэта | Радок запыту |
|---|---|
| Фільмы з адным ключавым словам | / |
| Фільмы з абодвума з двух ключавых слоў | / |
| Фільмы без ключавога слова | / |
| Серыялы з ключавым словам | / |
| Серыялы з любым з двух ключавых слоў | / |
| Адно ключавое слова ўнутры жанру | / |
Коска паміж id азначае ўсе з іх. Запішыце вертыкальную рыску паміж id, як у with_keywords=818|4565, каб супасці з любым. Вынікі discover кэшуюцца на edge на 30 хвілін.
Пошук id ключавога слова
Каб ператварыць тэкст у id, выклічце GET /. Ён вяртае спіс пар id і name па старонках, па 20 на старонку. Поўны набор шляхоў пошуку гл. на старонцы пошук. Пошук ключавых слоў, які нічога не знаходзіць, цяпер адказвае 500 са status_code 11 замест пустога спіса. Адказы пошуку кэшуюцца на 10 хвілін, але кожны выклік усё роўна ўлічваецца ў вашых запытах у хвіліну, таму адкладайце выклікі ў полі з падказкамі.
Памылкі
| HTTP | status_code | Калі |
|---|---|---|
| 401 | 7 | Ключ адсутнічае або няправільны. |
| 402 | 36 | Тэрмін дзеяння плана скончыўся. |
| 404 | 34 | Няма ключавога слова з гэтым id у /keyword/{keyword_id} і яго спісе фільмаў. |
| 405 | 37 | Вы выкарысталі метад запісу на шляху ключавых слоў. |
| 429 | 25 | Вы перавысілі ліміт запытаў у хвіліну. Пачакайце Retry-After секунд. |
| 500 | 11 | Запыт /search/keyword, які нічога не знаходзіць. |
Невядомы id фільма або серыяла на шляхах ключавых слоў не дае 404. Вы атрымліваеце HTTP 200 з id і пустым масівам.
Усе коды гл. на старонцы памылкі, а ліміты планаў на старонцы ліміты запытаў.
Практычныя заўвагі
- Захоўвайце
idключавога слова, а не назву. Назву могуць перафармуляваць, id не змяняецца. - Спісы ключавых слоў кэшуюцца разам з дэталямі назвы, на 6 гадзін. Для старонак з тэгамі хопіць штотыднёвага абнаўлення.
- У адной назвы кароткі спіс тэгаў. Для тэматычных старонак пачынайце з id ключавога слова і пералічвайце яго назвы ў discover, а не наадварот.
- Выкарыстоўвайце
without_keywords, каб прыбраць шум, напрыклад тэг, які вы ніколі не хочаце бачыць на сямейнай старонцы. - Пусты масіў гэта нармальны адказ для малавядомых назваў. Хавайце радок з тэгамі замест таго, каб паказваць памылку.