# 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. ## Endpoint `GET /3/movie/{movie_id}/keywords` ```bash curl "https://api.amodb.dev/3/movie/550/keywords" \ -H "Authorization: Bearer $AMODB_KEY" ``` Risposta: ```json { "id": 550, "keywords": [ { "id": 818, "name": "based on novel or book" }, { "id": 825, "name": "support group" }, { "id": 851, "name": "dual identity" } ] } ``` ## Ottenere le parole chiave di un film `GET /3/movie/{movie_id}/keywords` 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](https://amodb.dev/it/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. ```bash 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" ``` ```js 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)); } ``` ```python 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 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; } ``` ```go 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 | Parametro | In | Obbligatorio | Descrizione | | ---------- | -------- | ------------ | ------------------------------------------------------------- | | `movie_id` | percorso | sì | ID numerico del film, per esempio `550`. | | `api_key` | query | uno dei due | La tua chiave. Usa questa o l'header `Authorization: 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 ```json { "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 /3/tv/{series_id}/keywords` 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`. ```json { "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 ?? data.results` e trattarli allo stesso modo. ## Schede delle parole chiave e i loro film | Metodo e percorso | Restituisce | Parametri | | ---------------------------------- | ---------------------------------------------------------------------------------- | ------------------ | | `GET /keyword/{keyword_id}` | `{ id, name }` | nessuno | | `GET /keyword/{keyword_id}/movies` | 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](https://amodb.dev/it/trending-lists/), 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 `/discover/tv?with_keywords=` per le serie TV. ## Combinare le parole chiave con discover Per tutto ciò che va oltre una semplice lista, filtra in [discover](https://amodb.dev/it/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 | `/discover/movie?with_keywords=818` | | Film con entrambe le due parole chiave | `/discover/movie?with_keywords=818,4565` | | Film senza una parola chiave | `/discover/movie?without_keywords=818` | | Serie TV con una parola chiave | `/discover/tv?with_keywords=9712` | | Serie TV con l'una o l'altra di due parole chiave | `/discover/tv?with_keywords=818%7C9712` | | Una parola chiave dentro un genere | `/discover/movie?with_keywords=818&with_genres=18` | 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 /3/search/keyword?query=heist`. Restituisce una lista paginata di coppie `id` e `name`, 20 per pagina. Vedi [ricerca](https://amodb.dev/it/search/) 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](https://amodb.dev/it/errors/) per tutti i codici e [limiti di richieste](https://amodb.dev/it/rate-limits/) per i limiti dei piani. ## Note pratiche - Salva l'`id` della 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_keywords` per 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. ## Domande e risposte ### Perché la risposta delle serie TV usa results mentre i film usano keywords? È così che TMDB v3 le struttura, e amodb la mantiene perché i client esistenti funzionino. I film restituiscono un array keywords. Le serie TV restituiscono gli stessi oggetti sotto results. Leggi data.keywords ?? data.results. ### Come trovo l'id di una parola chiave dal suo nome? Chiama il percorso di ricerca delle parole chiave con una query, per esempio /3/search/keyword?query=heist. Restituisce una lista paginata di coppie id e name. Scegli la corrispondenza esatta e salva l'id. ### Posso usare lo stesso id di parola chiave per film e serie TV? Sì. Un id di parola chiave è lo stesso valore in discover per i film e in discover per le serie TV, quindi with_keywords funziona su entrambi i percorsi. Salva un id per tema e riusalo per entrambi i tipi di contenuto. ### Come combino più parole chiave in una query? Unisci gli id in with_keywords con una virgola per richiederli tutti, o con una barra verticale per accettarne uno qualsiasi. Usa without_keywords per escludere degli id. Tieni l'URL entro il limite di lunghezza del tuo client HTTP. ## Pagine correlate - [API Discover](https://amodb.dev/it/discover/): API Discover con gli stessi filtri di TMDB v3. Elenca film e serie TV per genere, cast, società, parola chiave, anno, voto, durata e piattaforma. - [API di ricerca](https://amodb.dev/it/search/): API di ricerca con percorsi e JSON di TMDB v3. Trova film, serie, persone, collezioni, società e parole chiave per testo, con filtri anno e paginazione. - [API dei dettagli del film](https://amodb.dev/it/movies/): API dettagli film con gli stessi percorsi e JSON di TMDB v3. Ottieni un film per ID, aggiungi crediti, valutazioni e mood con append_to_response, in 14 lingue. - [API delle serie TV](https://amodb.dev/it/tv-series/): API serie TV con gli stessi percorsi e JSON di TMDB v3. Ottieni una serie per ID con stagioni, emittenti e prossimo episodio, più classificazioni e piattaforme. - [Generi e liste di riferimento](https://amodb.dev/it/genres/): API generi con percorsi TMDB v3: ID dei generi di film e serie TV con nomi tradotti, più liste di paesi, lingue, mestieri, classificazioni e piattaforme. - [Avvio rapido](https://amodb.dev/it/quickstart/): Fai la prima chiamata ad amodb: ottieni una chiave, richiedi i dettagli di un film in curl, JavaScript, Python, PHP o Go, carica la locandina. Meno di 2 minuti. Aggiornato: 2026-10-18. Source: https://amodb.dev/it/keywords/