# Tendenze e endpoint delle liste > Gli endpoint di tendenze e liste restituiscono pagine ordinate di film, serie TV o persone. Usa GET /3/trending/{media_type}/{time_window} per le classifiche del giorno e della settimana, e i percorsi di liste movie e tv per i titoli popolari, più votati, in sala, in arrivo o in onda. Ogni pagina ha 20 risultati e resta in cache 30 minuti. ## Endpoint `GET /3/trending/{media_type}/{time_window}` ```bash curl "https://api.amodb.dev/3/trending/movie/week?language=en-US" \ -H "Authorization: Bearer $AMODB_KEY" ``` Risposta: ```json { "page": 1, "results": [ { "adult": false, "backdrop_path": "/mBZKC8ActTlM4W3HEGI1Cl1RtO3.jpg", "genre_ids": [ 878, 9648, 28 ], "id": 1058424, "original_language": "ko", "original_title": "호프", "overview": "In the remote South Korean village of Hope Harbor, police chief Bum-seok and officer Sung-ae are called to investigate a mysterious creature wreaking havoc on the community. But all is not as it seems, and perceptions can be misleading. Wha...", "popularity": 368.4952, "poster_path": "/bcK5naYzzfY0JBCgrPrsrbV6NO1.jpg", "release_date": "2026-07-15", "title": "Hope", "video": false, "vote_average": 6.9, "vote_count": 256, "media_type": "movie" }, { "adult": false, "backdrop_path": "/5YfPIIMzGBkIjHt3PTXBWyfBTGS.jpg", "genre_ids": [ 28, 14 ], "id": 1153576, "original_language": "en", "original_title": "Street Fighter", "overview": "In 1993, estranged Street Fighters Ryu and Ken Masters are thrown back into combat when the mysterious Chun-Li recruits them for the next World Warrior Tournament: a brutal clash of fists, fate, and fury. But behind this battle royale lies...", "popularity": 225.4202, "poster_path": "/utKzCSCz2HtXwcDGfWLj2IHhSob.jpg", "release_date": "2026-10-13", "title": "Street Fighter", "video": false, "vote_average": 6.365, "vote_count": 85, "media_type": "movie" }, { "adult": false, "backdrop_path": "/tanwf7KOwQ6dxZzehKsXkffIJOd.jpg", "genre_ids": [ 878, 28, 12 ], "id": 969681, "original_language": "en", "original_title": "Spider-Man: Brand New Day", "overview": "Fighting crime full-time as Spider-Man in a world that doesn't remember him—and the pressure of seeing his old friends move on without him—sparks a change in Peter Parker he may not have the power to control. But that transformation might a...", "popularity": 655.4447, "poster_path": "/bjiS5ipwxb9JFy3XRRN4OAilSeX.jpg", "release_date": "2026-07-29", "title": "Spider-Man: Brand New Day", "video": false, "vote_average": 8.469, "vote_count": 5725, "media_type": "movie" } ], "total_pages": 500, "total_results": 10000 } ``` ## Ottenere i titoli di tendenza `GET /3/trending/{media_type}/{time_window}` restituisce una pagina ordinata di ciò che le persone guardano o cercano in questo momento. `media_type` è `all`, `movie`, `tv` o `person`. `time_window` è `day` o `week`. Le classifiche del giorno cambiano in fretta e vanno bene per una fascia «stasera». Le classifiche della settimana sono più stabili e vanno bene per una home page. L'esempio chiede la classifica settimanale dei film e stampa i primi dieci titoli. ```bash curl -s "https://api.amodb.dev/3/trending/movie/week?language=en-US&page=1" \ -H "Authorization: Bearer $AMODB_KEY" ``` ```js const url = 'https://api.amodb.dev/3/trending/movie/week?language=en-US&page=1'; const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.AMODB_KEY}` } }); if (!res.ok) throw new Error(`amodb returned ${res.status}`); const chart = await res.json(); for (const [i, m] of chart.results.slice(0, 10).entries()) { console.log(i + 1, m.title, m.release_date); } ``` ```python import os import requests r = requests.get( "https://api.amodb.dev/3/trending/movie/week", params={"language": "en-US", "page": 1}, headers={"Authorization": f"Bearer {os.environ['AMODB_KEY']}"}, timeout=10, ) r.raise_for_status() for i, m in enumerate(r.json()["results"][:10], start=1): print(i, m["title"], m.get("release_date")) ``` ```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"); } $chart = json_decode($body, true); foreach (array_slice($chart['results'], 0, 10) as $i => $m) { echo ($i + 1), ' ', $m['title'], ' ', $m['release_date'] ?? '', PHP_EOL; } ``` ```go package main import ( "encoding/json" "fmt" "net/http" "os" "time" ) type Chart struct { Results []struct { Title string `json:"title"` ReleaseDate string `json:"release_date"` } `json:"results"` } func main() { url := "https://api.amodb.dev/3/trending/movie/week?language=en-US&page=1" req, _ := http.NewRequest("GET", url, 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 chart Chart if err := json.NewDecoder(res.Body).Decode(&chart); err != nil { panic(err) } for i, m := range chart.Results { if i == 10 { break } fmt.Println(i+1, m.Title, m.ReleaseDate) } } ``` ### Parametri | Parametro | In | Obbligatorio | Descrizione | | ------------- | -------- | ------------ | ----------------------------------------------------------------------------------------------------- | | `media_type` | percorso | sì | `all`, `movie`, `tv` o `person`. | | `time_window` | percorso | sì | `day` o `week`. | | `api_key` | query | uno dei due | La tua chiave. Usa questa o l'header `Authorization: Bearer`. | | `language` | query | no | Tag TMDB come `en-US` o `ru-RU`. Sono servite 14 lingue di base, tutto il resto ripiega sull'inglese. | | `page` | query | no | Numero di pagina da 1 a 500. Ogni pagina contiene 20 risultati. | ### Campi della risposta | Campo | Tipo | Note | | --------------------------------------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | `page` | intero | La pagina richiesta. | | `results` | array | Oggetti di film, serie TV o persone, prima la posizione migliore. | | `total_pages`, `total_results` | intero | Totali di paginazione. Le classifiche di tendenza dichiarano al massimo 500 pagine e 10000 risultati. | | `media_type` | stringa | `movie`, `tv` o `person` su ogni elemento di tendenza. Leggilo quando richiedi `all`. | | `id` | intero | Da usare con [film](https://amodb.dev/it/movies/), [serie TV](https://amodb.dev/it/tv-series/) o [persone](https://amodb.dev/it/people/). | | `title`, `original_title` | stringa | Elementi dei film. Gli elementi delle serie TV usano `name` e `original_name`. | | `release_date`, `first_air_date` | stringa | `YYYY-MM-DD` per gli elementi di film e serie TV. | | `genre_ids` | array | ID numerici. I nomi vengono da [generi](https://amodb.dev/it/genres/). | | `popularity`, `vote_average`, `vote_count` | numero | Dati di classifica e punteggio aggregato degli utenti. | | `poster_path`, `backdrop_path`, `profile_path` | stringa o null | Da accodare a `https://img.amodb.dev/t/p/{size}`. | | `name`, `original_name`, `gender`, `known_for_department` | stringa o intero | Elementi delle persone. `known_for` è un array vuoto sugli elementi di persone in tendenza. | ### Risposta di esempio ```json { "page": 1, "results": [ { "adult": false, "backdrop_path": "/7ULXMNvmZSi13zN3EZjz8wbER9B.jpg", "genre_ids": [28, 53], "id": 1561726, "original_language": "en", "original_title": "Masterplan", "overview": "When a legendary thief sets his sights on the Mona Lisa, he recruits two young strangers to help him before...", "popularity": 189.8286, "poster_path": "/3x3AfF0qVwSUDDciTaNKcPHZUN8.jpg", "release_date": "2026-10-16", "title": "Masterplan", "video": false, "vote_average": 7.279, "vote_count": 61, "media_type": "movie" }, { "adult": false, "backdrop_path": "/mBZKC8ActTlM4W3HEGI1Cl1RtO3.jpg", "genre_ids": [878, 9648, 28], "id": 1058424, "original_language": "ko", "original_title": "호프", "overview": "In the remote South Korean village of Hope Harbor, police chief Bum-seok and officer Sung-ae are called to...", "popularity": 294.6518, "poster_path": "/bcK5naYzzfY0JBCgrPrsrbV6NO1.jpg", "release_date": "2026-07-15", "title": "Hope", "video": false, "vote_average": 6.917, "vote_count": 246, "media_type": "movie" }, { "adult": false, "backdrop_path": "/5YfPIIMzGBkIjHt3PTXBWyfBTGS.jpg", "genre_ids": [28, 14], "id": 1153576, "original_language": "en", "original_title": "Street Fighter", "overview": "In 1993, estranged Street Fighters Ryu and Ken Masters are thrown back into combat when the mysterious Chun...", "popularity": 209.3923, "poster_path": "/utKzCSCz2HtXwcDGfWLj2IHhSob.jpg", "release_date": "2026-10-13", "title": "Street Fighter", "video": false, "vote_average": 6.316, "vote_count": 76, "media_type": "movie" } ], "total_pages": 500, "total_results": 10000 } ``` La risposta è stata recuperata dall'API reale e tagliata a 3 delle 20 voci della pagina 1. Le stringhe `overview` lunghe sono accorciate, e posizioni e conteggi cambiano a ogni aggiornamento. ## Liste di film Le classifiche dei film condividono un'unica struttura: un array `results` paginato di oggetti film. `now_playing` e `upcoming` aggiungono un oggetto `dates` con `minimum` e `maximum`, la finestra di uscita che la lista copre. Tutte e quattro accettano `language`, `page` e `region`. | Metodo e percorso | Restituisce | | ------------------------ | ------------------------------------------------------------------ | | `GET /movie/now_playing` | Film usciti nella finestra `dates` intorno a oggi, più `dates` | | `GET /movie/popular` | Film ordinati per popolarità attuale | | `GET /movie/top_rated` | Film ordinati per punteggio degli utenti | | `GET /movie/upcoming` | Film con una data di uscita futura, più `dates` | | `GET /movie/latest` | Un oggetto film: la voce più recente del catalogo. Non è una lista | Un vero oggetto `dates` ha questo aspetto: ```json { "dates": { "maximum": "2026-10-21", "minimum": "2026-09-09" } } ``` `region` è un codice ISO 3166-1 maiuscolo come `DE` o `GB`. Su `now_playing` e `upcoming` tiene solo i titoli usciti in quel paese, quindi la lista è una piccola parte di quella mondiale. Un codice sconosciuto restituisce una lista vuota. Su `popular` e `top_rated` sostituisce soltanto `release_date` con la data locale e non cambia la classifica. Per vedere dove si proietta un film, abbina `now_playing` agli [orari delle proiezioni](https://amodb.dev/it/showtimes/). ## Liste di serie TV Le classifiche delle serie TV restituiscono gli stessi campi di paginazione. Gli elementi usano `name`, `original_name`, `first_air_date` e `origin_country` al posto dei nomi dei film. Tutte e quattro accettano `language` e `page`. | Metodo e percorso | Restituisce | Parametri aggiuntivi | | ---------------------- | ---------------------------------------------------------------------- | -------------------- | | `GET /tv/airing_today` | Serie con un episodio in onda oggi | `timezone` | | `GET /tv/on_the_air` | Serie con un episodio in onda nei prossimi giorni | `timezone` | | `GET /tv/popular` | Serie ordinate per popolarità attuale | nessuno | | `GET /tv/top_rated` | Serie ordinate per punteggio degli utenti | nessuno | | `GET /tv/latest` | Un oggetto serie TV: la voce più recente del catalogo. Non è una lista | nessuno | `timezone` è un nome IANA come `Europe/Rome`. Decide quale giorno di calendario conta come «oggi», quindi `airing_today` restituisce un insieme diverso per `Asia/Tokyo` rispetto a `Pacific/Auckland`. Le liste delle serie TV non hanno il parametro `region`. ## Liste di persone `GET /person/popular` restituisce una lista paginata di persone ordinate per popolarità, con `language` e `page`. Ogni voce ha `id`, `name`, `original_name`, `known_for_department`, `gender`, `profile_path`, `popularity` e un array `known_for` di al massimo 3 schede di film o serie TV, ciascuna con `media_type`. Apri una persona nella pagina [persone](https://amodb.dev/it/people/). ```json { "page": 1, "results": [ { "adult": false, "gender": 1, "id": 1247604, "known_for_department": "Acting", "name": "Agnez Mo", "original_name": "Agnez Mo", "popularity": 45.8988, "profile_path": "/7GuBJxf5szQRCKLk3iG2ztfCo39.jpg", "known_for": [ { "adult": false, "backdrop_path": "/pF0qkRsrHkdYadPWY9AMeFZfcwk.jpg", "first_air_date": "2022-02-03", "genre_ids": [10759], "id": 108978, "name": "Reacher", "origin_country": ["US"], "original_language": "en", "original_name": "Reacher", "overview": "Jack Reacher, a veteran military police investigator, has just recently enter...", "popularity": 411.841, "poster_path": "/f1VCQIG2iCyOookdgOzwtUpwWC0.jpg", "vote_average": 8.1, "vote_count": 3508, "media_type": "tv" } ] } ], "total_pages": 1001, "total_results": 20001 } ``` amodb non offre `person/latest` né i feed `changes`. ## Scegliere la lista giusta per una schermata | Schermata | Chiamata | Aggiornamento | | --------------------------------- | ---------------------------------------- | ------------------------- | | Fascia principale della home page | `/trending/all/week` | Al massimo ogni 30 minuti | | Scheda «Al cinema» | `/movie/now_playing` con la tua `region` | Al massimo ogni 30 minuti | | Scheda «In arrivo» | `/movie/upcoming` con la tua `region` | Al massimo ogni 30 minuti | | Fascia «Stasera in TV» | `/tv/airing_today` con un `timezone` | Al massimo ogni 30 minuti | | Preferiti di sempre | `/movie/top_rated` | Basta una volta al giorno | | Persone cercate in questo momento | `/trending/person/day` | Al massimo ogni 30 minuti | | Persone più popolari in assoluto | `/person/popular` | Al massimo ogni 30 minuti | ## Errori | HTTP | status_code | Quando | | ---- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------ | | 401 | 7 | La chiave manca o è sbagliata. | | 402 | 36 | Il periodo del piano è terminato. | | 404 | 34 | Il percorso non esiste, per esempio un nome di lista scritto male o un `media_type` o `time_window` che non è nelle liste qui sopra. | | 405 | 37 | Hai usato un metodo di scrittura su un percorso di lista. | | 429 | 25 | Hai superato le richieste al minuto. Attendi i secondi di `Retry-After`. | | 500 | 11 | Una `page` sopra 500. | La tabella completa è nella pagina [errori](https://amodb.dev/it/errors/). I limiti per piano sono in [limiti di richieste](https://amodb.dev/it/rate-limits/). ## Note pratiche - L'edge mette in cache per 30 minuti le liste di tendenze, popolari, in sala e in onda, e ogni chiave condivide la stessa voce. Basta un job di aggiornamento ogni 30 minuti. - Le pagine vanno da 1 a 500. Le liste dei popolari dichiarano un `total_results` di 20001, che è un tetto e non un conteggio reale. Oltre la pagina 500 usa [discover](https://amodb.dev/it/discover/) con `sort_by` e filtri, che raggiunge titoli che una classifica non mostra mai. - Gli elementi delle liste contengono solo i campi necessari per una scheda. Per durata, imdb_id o crediti chiama i [dettagli del film](https://amodb.dev/it/movies/) con `append_to_response`, una volta per ogni scheda che l'utente apre. - `language` controlla la lingua di titoli e trame. I titoli senza traduzione tornano nel testo originale, quindi controlla le stringhe vuote prima di mostrare una scheda. - Salva l'`id` di una lista, non la posizione. Le posizioni cambiano a ogni aggiornamento. ## Domande e risposte ### Per quanto tempo restano in cache le liste di tendenze e popolari? L'edge mette in cache per 30 minuti le liste di tendenze, popolari, in sala e in onda, e condivide ogni voce tra le chiavi. Interrogare più spesso di ogni 30 minuti restituisce la stessa pagina e spreca richieste. ### Quante pagine posso leggere da una lista? Le pagine vanno da 1 a 500 con 20 risultati ciascuna, gli stessi limiti di TMDB. Per una navigazione più profonda usa discover, che filtra per genere, anno, cast o società invece di seguire un'unica classifica fissa. ### Quali liste accettano il parametro region? now_playing e upcoming prendono region come codice paese di due lettere maiuscole come GB e tengono solo i titoli usciti lì. popular e top_rated lo accettano ma sostituiscono soltanto release_date con la data locale. Le liste delle serie TV non hanno region. airing_today e on_the_air usano timezone. ### Posso filtrare una classifica per genere? Non su questi percorsi. Gli elementi delle liste portano genre_ids per la visualizzazione. Per filtrare per genere usa discover con with_genres, e trasforma gli ID in nomi con gli endpoint delle liste dei generi. ## 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 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. - [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. - [Orari delle proiezioni al cinema](https://amodb.dev/it/showtimes/): API orari delle proiezioni: restituisce cinema e orari di un film in un paese, o un riepilogo per paese. Uniscila ai dettagli o abbinala a now_playing. - [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/trending-lists/