# API di ricerca > Gli endpoint di ricerca trasformano un testo in ID. GET /3/search/movie trova film, e percorsi affini trovano serie TV, persone, collezioni, società e parole chiave, o tutti i contenuti insieme con multi. Il JSON segue TMDB v3, i risultati sono paginati a 20 per pagina e l'edge mette in cache una query per 10 minuti. ## Endpoint `GET /3/search/movie` ```bash curl "https://api.amodb.dev/3/search/movie?query=inception&year=2010" \ -H "Authorization: Bearer $AMODB_KEY" ``` Risposta: ```json { "page": 1, "results": [ { "adult": false, "backdrop_path": "/zSBVQIvx4UIHoFf1oDvixHyIQrz.jpg", "genre_ids": [ 28, 878, 80 ], "id": 27205, "original_language": "en", "original_title": "Inception", "overview": "Cobb, a skilled thief who commits corporate espionage by infiltrating the subconscious of his targets is offered a chance to regain his old life as payment for a task considered to be impossible: \"inception\", the implantation of another per...", "popularity": 60.9811, "poster_path": "/xlaY2zyzMfkhk0HSC5VUwzoZPU1.jpg", "release_date": "2010-07-15", "title": "Inception", "video": false, "vote_average": 8.373, "vote_count": 40461 }, { "adult": false, "backdrop_path": "/p8K8Z4yjaslJx5mTsIC5L6LJxQB.jpg", "genre_ids": [ 16, 28, 53 ], "id": 64956, "original_language": "en", "original_title": "Inception: The Cobol Job", "overview": "Cobb, Arthur and Nash are enlisted by Cobol Engineering.", "popularity": 1.9401, "poster_path": "/sNxqwtyHMNQwKWoFYDqcYTui5Ok.jpg", "release_date": "2010-12-07", "title": "Inception: The Cobol Job", "video": false, "vote_average": 7.2, "vote_count": 320 }, { "adult": false, "backdrop_path": null, "genre_ids": [ 10402 ], "id": 973484, "original_language": "en", "original_title": "Inception: Music from the Motion Picture", "overview": "The Special Features Blu-ray disc contains a lossless DTS-HD MA 5.1 surround mix of the Inception soundtrack.", "popularity": 0.4911, "poster_path": "/7uM4DyRVAcgagvhZoWrkrqMPbqV.jpg", "release_date": "2010-12-07", "title": "Inception: Music from the Motion Picture", "video": true, "vote_average": 7, "vote_count": 3 } ], "total_pages": 1, "total_results": 3 } ``` ## Cercare film `GET /3/search/movie` prende un testo di ricerca e restituisce una lista paginata di film corrispondenti, prima la corrispondenza migliore. Usalo per trasformare ciò che un utente ha digitato in un ID film, poi chiama i [dettagli del film](https://amodb.dev/it/movies/) con quell'ID. L'esempio cerca Inception, limitato al 2010, e stampa ID, titolo e data di uscita. ```bash curl -sSf --get "https://api.amodb.dev/3/search/movie" \ --data-urlencode "query=inception" \ --data-urlencode "year=2010" \ -H "Authorization: Bearer $AMODB_KEY" ``` ```js const params = new URLSearchParams({ query: 'inception', year: '2010', language: 'en-US' }); const res = await fetch(`https://api.amodb.dev/3/search/movie?${params}`, { headers: { Authorization: `Bearer ${process.env.AMODB_KEY}` }, }); if (!res.ok) throw new Error(`amodb returned ${res.status}`); const { results, total_results } = await res.json(); console.log(`${total_results} matches`); for (const m of results.slice(0, 5)) console.log(m.id, m.title, m.release_date); ``` ```python import os import requests r = requests.get( "https://api.amodb.dev/3/search/movie", params={"query": "inception", "year": 2010, "language": "en-US"}, headers={"Authorization": f"Bearer {os.environ['AMODB_KEY']}"}, timeout=10, ) r.raise_for_status() data = r.json() print(data["total_results"], "matches") for m in data["results"][:5]: print(m["id"], m["title"], m["release_date"]) ``` ```php 'inception', 'year' => 2010, 'language' => 'en-US', ]); $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"); } $data = json_decode($body, true); foreach (array_slice($data['results'], 0, 5) as $m) { echo $m['id'], ' ', $m['title'], ' ', $m['release_date'], PHP_EOL; } ``` ```go package main import ( "encoding/json" "fmt" "net/http" "net/url" "os" "time" ) type SearchPage struct { TotalResults int `json:"total_results"` Results []struct { ID int `json:"id"` Title string `json:"title"` ReleaseDate string `json:"release_date"` } `json:"results"` } func main() { q := url.Values{"query": {"inception"}, "year": {"2010"}, "language": {"en-US"}} req, _ := http.NewRequest("GET", "https://api.amodb.dev/3/search/movie?"+q.Encode(), nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("AMODB_KEY")) client := &http.Client{Timeout: 10 * time.Second} res, err := client.Do(req) if err != nil { panic(err) } defer res.Body.Close() if res.StatusCode != http.StatusOK { panic(res.Status) } var p SearchPage if err := json.NewDecoder(res.Body).Decode(&p); err != nil { panic(err) } fmt.Println(p.TotalResults, "matches") for _, m := range p.Results { fmt.Println(m.ID, m.Title, m.ReleaseDate) } } ``` ### Parametri | Parametro | In | Obbligatorio | Descrizione | | ---------------------- | ----- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------- | | `query` | query | sì | Testo da cercare. Codificalo per l'URL: gli spazi diventano `%20` o `+`. | | `api_key` | query | uno dei due | La tua chiave. Usa questa o l'header `Authorization: Bearer`. | | `year` | query | no | Anno di quattro cifre. Tiene i film con una qualsiasi data di uscita, in qualsiasi paese, in quell'anno. | | `primary_release_year` | query | no | Anno di quattro cifre. Corrisponde solo alla data di uscita principale, quindi può restituire meno titoli di `year`. | | `region` | query | no | Codice paese di 2 lettere maiuscole come `US`. Sostituisce `release_date` con la data in quel paese quando è nota. Non rimuove titoli. | | `include_adult` | query | no | Accettato e ignorato. I titoli per adulti non vengono mai restituiti. | | `language` | query | no | Tag TMDB come `en-US` o `it-IT`. Sono servite 14 lingue di base, tutto il resto ripiega sull'inglese. Predefinito `en-US`. | | `page` | query | no | Numero di pagina da 1 a 500. Predefinito 1. | ### Campi della risposta | Campo | Tipo | Note | | ------------------------------------------ | --------------- | ----------------------------------------------------------------------------------------------- | | `page` | intero | La pagina richiesta. | | `results` | array | Fino a 20 voci, prima la corrispondenza migliore. | | `total_pages`, `total_results` | intero | Dimensione dell'insieme di risultati per questa query. Limitata a 500 pagine e 10000 risultati. | | `id` | intero | ID del film per l'endpoint dei dettagli. | | `title`, `original_title` | stringa | Titolo localizzato e titolo originale. | | `original_language` | stringa | Codice di due lettere della lingua in cui è stato girato il film. | | `overview` | stringa | Testo localizzato, vuoto quando non esiste una traduzione. | | `release_date` | stringa | `YYYY-MM-DD`, vuota per i titoli senza data. | | `genre_ids` | array di interi | ID dei generi, non nomi. Associali con [generi](https://amodb.dev/it/genres/). | | `poster_path`, `backdrop_path` | stringa o null | Da accodare a `https://img.amodb.dev/t/p/{size}`. | | `popularity`, `vote_average`, `vote_count` | numero | Valori di classifica e di punteggio. | | `adult`, `video` | booleano | `adult` è sempre `false`. `video` è `true` per le voci segnate come contenuto video. | ### Risposta di esempio ```json { "page": 1, "results": [ { "adult": false, "backdrop_path": "/zSBVQIvx4UIHoFf1oDvixHyIQrz.jpg", "genre_ids": [28, 878, 80], "id": 27205, "original_language": "en", "original_title": "Inception", "overview": "Cobb, a skilled thief who commits corporate espionage by infiltrating the subconscious of his targets is of...", "popularity": 60.9811, "poster_path": "/xlaY2zyzMfkhk0HSC5VUwzoZPU1.jpg", "release_date": "2010-07-15", "title": "Inception", "video": false, "vote_average": 8.373, "vote_count": 40459 }, { "adult": false, "backdrop_path": "/p8K8Z4yjaslJx5mTsIC5L6LJxQB.jpg", "genre_ids": [16, 28, 53], "id": 64956, "original_language": "en", "original_title": "Inception: The Cobol Job", "overview": "Cobb, Arthur and Nash are enlisted by Cobol Engineering.", "popularity": 1.9401, "poster_path": "/sNxqwtyHMNQwKWoFYDqcYTui5Ok.jpg", "release_date": "2010-12-07", "title": "Inception: The Cobol Job", "video": false, "vote_average": 7.2, "vote_count": 320 }, { "adult": false, "backdrop_path": null, "genre_ids": [10402], "id": 973484, "original_language": "en", "original_title": "Inception: Music from the Motion Picture", "overview": "The Special Features Blu-ray disc contains a lossless DTS-HD MA 5.1 surround mix of the Inception soundtrack.", "popularity": 0.4911, "poster_path": "/7uM4DyRVAcgagvhZoWrkrqMPbqV.jpg", "release_date": "2010-12-07", "title": "Inception: Music from the Motion Picture", "video": true, "vote_average": 7, "vote_count": 3 } ], "total_pages": 1, "total_results": 3 } ``` La risposta contiene tutte e tre le corrispondenze. È stata recuperata dall'API reale e sono state accorciate solo le stringhe `overview` lunghe. ## Altri endpoint di ricerca Tutti i percorsi qui sotto condividono la base `https://api.amodb.dev/3`, richiedono `query` e restituiscono la stessa busta `page`, `results`, `total_pages` e `total_results`. Ognuno accetta anche `page` da 1 a 500. `include_adult` è accettato ovunque e ignorato. | Metodo e percorso | Trova | Parametri aggiuntivi | Campi delle voci | | ------------------------ | ----------------------------- | ----------------------------------------- | -------------------------------------------------------------------------------------- | | `GET /search/tv` | Serie TV | `first_air_date_year`, `year`, `language` | `name`, `original_name`, `first_air_date`, `origin_country` | | `GET /search/person` | Persone | `language` | `name`, `original_name`, `known_for_department`, `gender`, `profile_path`, `known_for` | | `GET /search/multi` | Film, serie e persone insieme | `language` | `media_type` più i campi di quel tipo | | `GET /search/collection` | Collezioni di film | `language` | `name`, `original_name`, `overview`, `poster_path`, `backdrop_path` | | `GET /search/company` | Case di produzione | nessuno | `name`, `logo_path`, `origin_country` | | `GET /search/keyword` | Parole chiave | nessuno | `id`, `name` | Per le serie TV, `first_air_date_year` tiene le serie la cui prima messa in onda cade in quell'anno, mentre `year` tiene anche le serie più vecchie andate in onda in quell'anno. Una ricerca di `the` con `year=2010` restituisce The Simpsons, andata in onda per la prima volta nel 1989, mentre la stessa ricerca con `first_air_date_year=2010` no. Se invii entrambi, devono corrispondere entrambi. Le voci delle persone portano fino a 3 titoli `known_for`, ciascuno con `media_type`. `/search/multi` ignora `year`. Le entità trovate qui proseguono nelle pagine [serie TV](https://amodb.dev/it/tv-series/), [persone](https://amodb.dev/it/people/), [collezioni](https://amodb.dev/it/collections/), [società ed emittenti](https://amodb.dev/it/companies-networks/) e [parole chiave](https://amodb.dev/it/keywords/). ### Ricerca multi `media_type` è `movie`, `tv` o `person`, e ti dice quali campi aspettarti. Le voci dei film portano `title` e quelle di serie TV e persone portano `name`. ```js const byType = { movie: [], tv: [], person: [] }; for (const r of results) byType[r.media_type]?.push(r.title || r.name); console.log(byType); ``` ## Errori `/search/tv` e `/search/person` rispondono a una query senza corrispondenze con HTTP 200, un array `results` vuoto e `total_results` pari a 0. Al momento `/search/movie`, `/search/multi`, `/search/keyword`, `/search/company` e `/search/collection` rispondono allo stesso caso con HTTP 500 e `status_code` 11. Tratta un 500 su quei percorsi come «nessun risultato», a meno che non si ripeta per query che sai corrispondere. | HTTP | status_code | Quando | | ---- | ----------- | ---------------------------------------------------------------------------------------------------------------- | | 401 | 7 | La chiave manca o è sbagliata. | | 402 | 36 | Il periodo del piano è terminato. | | 405 | 37 | Hai chiamato un metodo di scrittura. | | 429 | 25 | Oltre le tue richieste al minuto. Attendi i secondi di `Retry-After`. | | 500 | 11 | Una query di film, multi, parole chiave, società o collezioni senza corrispondenze, o una `page` fuori da 1-500. | | 504 | 24 | Il backend non ha risposto in tempo. Riprova una volta. | Vedi [errori](https://amodb.dev/it/errors/) per l'elenco completo e [limiti di richieste](https://amodb.dev/it/rate-limits/) per le finestre. ## Note pratiche - L'edge mette in cache una ricerca per 10 minuti e condivide la copia tra le chiavi. Ogni chiamata conta comunque nelle tue 20, 40 o 120 richieste al minuto, perché il limite viene prima della cache. - Per una casella di ricerca, aspetta 300 ms dopo l'ultima battuta e annulla la richiesta in corso. Una casella che invia a ogni tasto può consumare in pochi secondi un piano da 20 richieste al minuto. - Metti in minuscolo e togli gli spazi ai bordi della query prima di usarla come chiave di cache dalla tua parte. - Per cercare un titolo per ID IMDb, salta la ricerca e usa la [ricerca per ID esterno](https://amodb.dev/it/find-by-external-id/). - Un ID di parola chiave da `/search/keyword` alimenta il filtro `with_keywords` di [discover](https://amodb.dev/it/discover/), e un ID di società alimenta `with_companies`. ## Domande e risposte ### Quanti risultati restituisce una pagina di ricerca? Ogni pagina contiene 20 risultati, e il parametro page va da 1 a 500. Leggi total_pages e total_results dalla risposta, e restringi le query vaghe con year o primary_release_year. ### Le ricerche in cache contano comunque nel mio limite di richieste? Sì. L'edge mette in cache una ricerca per 10 minuti e condivide quella copia tra le chiavi, ma il controllo della chiave e il limite di richieste vengono prima della consultazione della cache, quindi ogni chiamata conta una volta. ### Posso cercare per ID IMDb con questi endpoint? No. Usa invece GET /3/find/{external_id} con external_source=imdb_id. Restituisce movie_results, tv_results e person_results per quell'ID, ed è descritto nella pagina della ricerca per ID esterno. ### In che lingua sono i risultati? Il parametro language imposta titoli e trame, predefinito en-US. I tag fuori dalle 14 lingue di base ripiegano sull'inglese. I titoli originali restano disponibili in original_title e original_name. ## Pagine correlate - [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. - [API dei dettagli della persona](https://amodb.dev/it/people/): API dettagli persona con gli stessi percorsi e JSON di TMDB v3. Ottieni attore o troupe per ID, con biografia, filmografia, ID esterni e lista dei popolari. - [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. - [Ricerca per ID esterno](https://amodb.dev/it/find-by-external-id/): Cerca un film, una serie o una persona per ID IMDb, TVDB, Wikidata o Kinopoisk con l'endpoint find di TMDB, e leggi ID esterni e dati Wikidata di un titolo. - [Limiti di richieste](https://amodb.dev/it/rate-limits/): amodb limita ogni chiave per richieste al minuto in una finestra scorrevole di 60 secondi: 20, 40 o 120 in base al piano. Leggi gli header, gestisci il 429. Aggiornato: 2026-10-18. Source: https://amodb.dev/it/search/