API słów kluczowych
Endpointy słów kluczowych zwracają tagi fabularne przypisane do filmu lub serialu, każdy jako ID i nazwę. Możesz sprawdzić jedno słowo kluczowe, wypisać filmy, które je mają, albo przekazać ID do discover przez with_keywords, by budować strony tematyczne. Filmy odpowiadają pod keywords, seriale pod results.
Pobieranie słów kluczowych filmu
GET / zwraca tagi fabularne jednego filmu. Słowo kluczowe to krótka fraza, na przykład temat, miejsce akcji lub rodzaj pierwowzoru, i ma numeryczne ID, które możesz ponownie użyć w discover.
Przykład pobiera słowa kluczowe filmu, a potem prosi discover o najpopularniejsze filmy z jego pierwszym słowem kluczowym.
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)
}
}Parametry
movie_idpathwymaganyNumeryczne ID filmu, na przykład550.api_keyqueryjeden z dwóchTwój klucz. Użyj go albo nagłówkaAuthorization: Bearer.
Pola odpowiedzi
| Pole | Typ | Uwagi |
|---|---|---|
id | integer | ID filmu. |
keywords | array | Obiekty z id i name. Puste, gdy film nie ma żadnych. |
keywords[].id | integer | ID słowa kluczowego. Użyj go w with_keywords i w poniższych ścieżkach słów kluczowych. |
keywords[].name | string | Tekst słowa kluczowego. |
Przykładowa odpowiedź
{
"id": 550,
"keywords": [
{ "id": 818, "name": "based on novel or book" },
{ "id": 825, "name": "support group" },
{ "id": 851, "name": "dual identity" }
]
}Prawdziwa odpowiedź zawiera 14 słów kluczowych. Ta jest przycięta do pierwszych 3. Nazwy słów kluczowych nie są tłumaczone, więc language nie ma tu wpływu.
Słowa kluczowe serialu
GET / przyjmuje ten sam klucz i zwraca te same obiekty, ale tablica nazywa się results. ID w ścieżce to ID serialu, na przykład 1396.
{
"id": 1396,
"results": [
{ "id": 1508, "name": "new mexico" },
{ "id": 2231, "name": "drug dealer" }
]
}Prawdziwa odpowiedź zawiera 29 pozycji, a ta jest przycięta do pierwszych 2. Klient obsługujący oba typy mediów może czytać data.keywords ? i traktować je tak samo.
Rekordy słów kluczowych i ich filmy
| Metoda i ścieżka | Zwraca | Parametry |
|---|---|---|
GET / | { id, name } | brak |
GET / | Lista filmów z paginacją z id, page, results, total_pages, total_results | language, page |
Obie ścieżki używają numerycznego ID z tablicy słów kluczowych. Lista filmów ma ten sam kształt pozycji co inne listy filmów, w tym genre_ids i poster_path, plus id słowa kluczowego na górze. include_adult jest przyjmowane i ignorowane. Strona za total_pages zwraca pustą tablicę results. Nie ma listy seriali dla słowa kluczowego, więc dla seriali użyj /.
Łączenie słów kluczowych z discover
Do wszystkiego poza zwykłą listą filtruj w discover. Sortuje, dzieli na strony i łączy słowa kluczowe z innymi filtrami, a obejmuje seriale tak samo jak filmy.
| Cel | Ciąg zapytania |
|---|---|
| Filmy z jednym słowem kluczowym | / |
| Filmy z oboma z dwóch słów kluczowych | / |
| Filmy bez słowa kluczowego | / |
| Seriale ze słowem kluczowym | / |
| Seriale z którymkolwiek z dwóch słów kluczowych | / |
| Jedno słowo kluczowe w obrębie gatunku | / |
Przecinek między ID oznacza wszystkie. Wpisz kreskę pionową między ID, jak w with_keywords=818|4565, by dopasować dowolne. Wyniki discover są w cache na edge przez 30 minut.
Wyszukiwanie ID słowa kluczowego
Aby zamienić tekst na ID, wywołaj GET /. Zwraca listę z paginacją par id i name, po 20 na stronę. Pełny zestaw ścieżek wyszukiwania zobacz w wyszukiwanie. Wyszukiwanie słowa kluczowego, które nic nie znajduje, obecnie odpowiada 500 z status_code 11 zamiast pustej listy. Odpowiedzi wyszukiwania są w cache przez 10 minut, ale każde wywołanie nadal liczy się do twoich żądań na minutę, więc w polu z podpowiedziami stosuj debounce.
Błędy
| HTTP | status_code | Kiedy |
|---|---|---|
| 401 | 7 | Brakuje klucza lub jest błędny. |
| 402 | 36 | Okres planu dobiegł końca. |
| 404 | 34 | Brak słowa kluczowego o tym ID w /keyword/{keyword_id} i jego liście filmów. |
| 405 | 37 | Użyto metody zapisu na ścieżce słowa kluczowego. |
| 429 | 25 | Przekroczono limit żądań na minutę. Poczekaj tyle sekund, ile podaje Retry-After. |
| 500 | 11 | Zapytanie /search/keyword, które nic nie znajduje. |
Nieznane ID filmu lub serialu w ścieżkach słów kluczowych to nie 404. Dostajesz HTTP 200 z ID i pustą tablicą.
Wszystkie kody zobacz w błędy, a limity planów w limity żądań.
Praktyczne uwagi
- Zapisuj
idsłowa kluczowego, a nie nazwę. Nazwę można przeformułować, ID się nie zmienia. - Listy słów kluczowych są w cache razem ze szczegółami tytułu, przez 6 godzin. Cotygodniowe odświeżanie stron z tagami w zupełności wystarcza.
- Pojedynczy tytuł ma krótką listę tagów. Dla stron tematycznych zacznij od ID słowa kluczowego i wypisz jego tytuły w discover, a nie odwrotnie.
- Użyj
without_keywords, by usunąć szum, na przykład tag, którego nigdy nie chcesz na stronie rodzinnej. - Pusta tablica to poprawna odpowiedź dla mało znanych tytułów. Ukryj wiersz tagów zamiast pokazywać błąd.