API delle parole chiave
Gli endpoint delle parole chiave restituiscono i tag di trama associati a un film o a una serie TV, ciascuno come id e nome. Puoi cercare una parola chiave, elencare i film che la portano, oppure passare gli id a discover con with_keywords per costruire pagine a tema. I film rispondono sotto keywords, le serie TV sotto results.
Ottenere le parole chiave di un film
GET / restituisce i tag di trama di un film. Una parola chiave è una breve espressione come un tema, un'ambientazione o un tipo di fonte, e ha un ID numerico che puoi riusare in discover.
L'esempio carica le parole chiave di un film e poi chiede a discover i film più popolari che condividono la sua prima parola chiave.
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)
}
}Parametri
movie_idpercorsoobbligatorioID numerico del film, per esempio550.api_keyqueryuno dei dueLa tua chiave. Usa questa o l'headerAuthorization: Bearer.
Campi della risposta
| Campo | Tipo | Note |
|---|---|---|
id | intero | L'ID del film. |
keywords | array | Oggetti con id e name. Vuoto quando il film non ne ha. |
keywords[].id | intero | ID della parola chiave. Usalo in with_keywords e nei percorsi delle parole chiave qui sotto. |
keywords[].name | stringa | Il testo della parola chiave. |
Risposta di esempio
{
"id": 550,
"keywords": [
{ "id": 818, "name": "based on novel or book" },
{ "id": 825, "name": "support group" },
{ "id": 851, "name": "dual identity" }
]
}La risposta reale contiene 14 parole chiave. Questa è tagliata alle prime 3. I nomi delle parole chiave non sono tradotti, quindi language qui non ha effetto.
Parole chiave di una serie TV
GET / prende la stessa chiave e restituisce gli stessi oggetti, ma l'array si chiama results. L'ID nel percorso è quello della serie, per esempio 1396.
{
"id": 1396,
"results": [
{ "id": 1508, "name": "new mexico" },
{ "id": 2231, "name": "drug dealer" }
]
}La risposta reale contiene 29 voci e questa è tagliata alle prime 2. Un client che serve entrambi i tipi di contenuto può leggere data.keywords ? e trattarli allo stesso modo.
Schede delle parole chiave e i loro film
| Metodo e percorso | Restituisce | Parametri |
|---|---|---|
GET / | { id, name } | nessuno |
GET / | Lista paginata di film con id, page, results, total_pages, total_results | language, page |
Entrambi i percorsi usano l'ID numerico di un array di parole chiave. La lista dei film dà la stessa struttura di elemento delle altre liste di film, compresi genre_ids e poster_path, più l'id della parola chiave in cima. include_adult è accettato e ignorato. Una pagina oltre total_pages restituisce un array results vuoto. Non esiste una lista di serie per una parola chiave, quindi usa / per le serie TV.
Combinare le parole chiave con discover
Per tutto ciò che va oltre una semplice lista, filtra in discover. Ordina, pagina e combina le parole chiave con altri filtri, e copre le serie TV oltre ai film.
| Obiettivo | Stringa di query |
|---|---|
| Film con una parola chiave | / |
| Film con entrambe le due parole chiave | / |
| Film senza una parola chiave | / |
| Serie TV con una parola chiave | / |
| Serie TV con l'una o l'altra di due parole chiave | / |
| Una parola chiave dentro un genere | / |
Una virgola tra gli ID significa tutti. Scrivi una barra verticale tra gli ID, come in with_keywords=818|4565, per far corrispondere uno qualsiasi. I risultati di discover restano in cache sull'edge per 30 minuti.
Trovare l'ID di una parola chiave
Per trasformare un testo in un ID, chiama GET /. Restituisce una lista paginata di coppie id e name, 20 per pagina. Vedi ricerca per l'insieme dei percorsi di ricerca. Una ricerca di parole chiave che non corrisponde a nulla risponde attualmente 500 con status_code 11 invece di una lista vuota. Le risposte di ricerca restano in cache 10 minuti, ma ogni chiamata conta comunque nelle tue richieste al minuto, quindi applica un debounce a una casella con suggerimenti.
Errori
| HTTP | status_code | Quando |
|---|---|---|
| 401 | 7 | La chiave manca o è sbagliata. |
| 402 | 36 | Il periodo del piano è terminato. |
| 404 | 34 | Nessuna parola chiave con quell'ID su /keyword/{keyword_id} e sulla sua lista di film. |
| 405 | 37 | Hai usato un metodo di scrittura su un percorso di parole chiave. |
| 429 | 25 | Hai superato le richieste al minuto. Attendi i secondi di Retry-After. |
| 500 | 11 | Una query /search/keyword che non corrisponde a nulla. |
Un ID di film o serie sconosciuto sui percorsi delle parole chiave non è un 404. Ottieni un HTTP 200 con l'ID e un array vuoto.
Vedi errori per tutti i codici e limiti di richieste per i limiti dei piani.
Note pratiche
- Salva l'
iddella parola chiave, non il nome. Un nome può essere riformulato, un ID non cambia. - Le liste di parole chiave restano in cache insieme ai dettagli del titolo, per 6 ore. Un aggiornamento settimanale per le pagine dei tag è più che sufficiente.
- Un singolo titolo ha una breve lista di tag. Per le pagine a tema parti da un ID di parola chiave ed elenca i suoi titoli in discover, non il contrario.
- Usa
without_keywordsper togliere il rumore, per esempio un tag che non vuoi mai su una pagina per famiglie. - Un array vuoto è una risposta valida per i titoli poco noti. Nascondi la riga dei tag invece di mostrare un errore.