# Endpoint-uri pentru tendințe și liste > Endpoint-urile pentru tendințe și liste întorc pagini ierarhizate de filme, seriale TV sau persoane. Folosește GET /3/trending/{media_type}/{time_window} pentru topuri pe zi și săptămână, plus căile de listă pentru filme și tv pentru titluri populare, bine cotate, în cinematografe, viitoare și în difuzare. Fiecare pagină are 20 de rezultate și este ținută în cache 30 de minute. ## 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" ``` Răspuns: ```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 } ``` ## Obține titlurile în tendințe `GET /3/trending/{media_type}/{time_window}` întoarce o pagină ierarhizată cu ce urmăresc sau caută oamenii chiar acum. `media_type` este `all`, `movie`, `tv` sau `person`. `time_window` este `day` sau `week`. Topurile pe zi se mișcă repede și se potrivesc unei benzi „în seara asta”. Topurile pe săptămână sunt mai stabile și se potrivesc unei pagini principale. Exemplul cere topul săptămânal de filme și afișează primele zece titluri. ```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 | Parametru | Loc | Obligatoriu | Descriere | | ------------- | ---------- | -------------------- | --------------------------------------------------------------------------------------------------------- | | `media_type` | cale | da | `all`, `movie`, `tv` sau `person`. | | `time_window` | cale | da | `day` sau `week`. | | `api_key` | interogare | una dintre cele două | Cheia ta. Folosește-o pe aceasta sau antetul `Authorization: Bearer`. | | `language` | interogare | nu | Etichetă TMDB precum `en-US` sau `ru-RU`. Sunt servite 14 limbi de bază, orice altceva revine la engleză. | | `page` | interogare | nu | Numărul paginii de la 1 la 500. Fiecare pagină are 20 de rezultate. | ### Câmpurile răspunsului | Câmp | Tip | Observații | | --------------------------------------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | `page` | număr întreg | Pagina pe care ai cerut-o. | | `results` | array | Obiecte de film, TV sau persoană, cel mai bun rang primul. | | `total_pages`, `total_results` | număr întreg | Totaluri de paginare. Topurile de tendințe raportează cel mult 500 de pagini și 10000 de rezultate. | | `media_type` | șir | `movie`, `tv` sau `person` la fiecare element de tendințe. Citește-l când ceri `all`. | | `id` | număr întreg | Folosește-l cu [filme](https://amodb.dev/ro/movies/), [seriale TV](https://amodb.dev/ro/tv-series/) sau [persoane](https://amodb.dev/ro/people/). | | `title`, `original_title` | șir | Elemente de film. Elementele TV folosesc `name` și `original_name`. | | `release_date`, `first_air_date` | șir | `YYYY-MM-DD` pentru elementele de film și TV. | | `genre_ids` | array | ID-uri numerice. Numele vin de la [genuri](https://amodb.dev/ro/genres/). | | `popularity`, `vote_average`, `vote_count` | număr | Intrări de clasament și scorul agregat al utilizatorilor. | | `poster_path`, `backdrop_path`, `profile_path` | șir sau null | Se adaugă la `https://img.amodb.dev/t/p/{size}`. | | `name`, `original_name`, `gender`, `known_for_department` | șir sau număr întreg | Elemente de persoană. `known_for` este un array gol la elementele de persoană din tendințe. | ### Exemplu de răspuns ```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 } ``` Răspunsul a fost preluat de la API-ul live și tăiat la 3 din cele 20 de intrări de pe pagina 1. Șirurile `overview` lungi sunt scurtate, iar rangurile și numărătorile se schimbă la fiecare reîmprospătare. ## Liste de filme Topurile de filme au aceeași structură: un array `results` paginat cu obiecte de film. `now_playing` și `upcoming` adaugă un obiect `dates` cu `minimum` și `maximum`, fereastra de lansare pe care o acoperă lista. Toate patru primesc `language`, `page` și `region`. | Metodă și cale | Întoarce | | ------------------------ | ----------------------------------------------------------------------- | | `GET /movie/now_playing` | Filme lansate în fereastra `dates` din jurul zilei de azi, plus `dates` | | `GET /movie/popular` | Filme ordonate după popularitatea curentă | | `GET /movie/top_rated` | Filme ordonate după scorul utilizatorilor | | `GET /movie/upcoming` | Filme cu o dată de lansare viitoare, plus `dates` | | `GET /movie/latest` | Un obiect de film: cea mai nouă intrare din catalog. Nu este o listă | Un obiect `dates` real arată așa: ```json { "dates": { "maximum": "2026-10-21", "minimum": "2026-09-09" } } ``` `region` este un cod ISO 3166-1 cu majuscule, precum `DE` sau `GB`. La `now_playing` și `upcoming` păstrează doar titlurile lansate în acea țară, deci lista este o mică parte din cea mondială. Un cod necunoscut întoarce o listă goală. La `popular` și `top_rated` doar înlocuiește `release_date` cu data locală și nu schimbă clasamentul. Ca să vezi unde rulează un film, asociază `now_playing` cu [program de proiecții](https://amodb.dev/ro/showtimes/). ## Liste TV Topurile TV întorc aceleași câmpuri de paginare. Elementele folosesc `name`, `original_name`, `first_air_date` și `origin_country` în locul numelor de la filme. Toate patru primesc `language` și `page`. | Metodă și cale | Întoarce | Parametri suplimentari | | ---------------------- | ------------------------------------------------------------------------- | ---------------------- | | `GET /tv/airing_today` | Seriale cu un episod difuzat azi | `timezone` | | `GET /tv/on_the_air` | Seriale cu un episod difuzat în zilele următoare | `timezone` | | `GET /tv/popular` | Seriale ordonate după popularitatea curentă | niciunul | | `GET /tv/top_rated` | Seriale ordonate după scorul utilizatorilor | niciunul | | `GET /tv/latest` | Un obiect de serial TV: cea mai nouă intrare din catalog. Nu este o listă | niciunul | `timezone` este un nume IANA precum `Europe/Rome`. Decide ce zi calendaristică se numără ca „azi”, deci `airing_today` întoarce un set diferit pentru `Asia/Tokyo` decât pentru `Pacific/Auckland`. Listele TV nu au parametrul `region`. ## Liste de persoane `GET /person/popular` întoarce o listă paginată de persoane ordonate după popularitate, cu `language` și `page`. Fiecare intrare are `id`, `name`, `original_name`, `known_for_department`, `gender`, `profile_path`, `popularity` și un array `known_for` de până la 3 carduri de film sau TV, fiecare cu `media_type`. Deschide o persoană la [persoane](https://amodb.dev/ro/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 nu oferă `person/latest` sau fluxurile `changes`. ## Alege lista potrivită pentru un ecran | Ecran | Apel | Reîmprospătare | | ------------------------------------- | --------------------------------------- | -------------------------------- | | Rândul principal al paginii de start | `/trending/all/week` | Cel mult la fiecare 30 de minute | | Fila „În cinematografe” | `/movie/now_playing` cu `region`-ul tău | Cel mult la fiecare 30 de minute | | Fila „În curând” | `/movie/upcoming` cu `region`-ul tău | Cel mult la fiecare 30 de minute | | Banda „Diseară la TV” | `/tv/airing_today` cu un `timezone` | Cel mult la fiecare 30 de minute | | Preferatele tuturor timpurilor | `/movie/top_rated` | Zilnic ajunge | | Persoanele pe care le caută lumea | `/trending/person/day` | Cel mult la fiecare 30 de minute | | Cele mai populare persoane în general | `/person/popular` | Cel mult la fiecare 30 de minute | ## Erori | HTTP | status_code | Când | | ---- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------- | | 401 | 7 | Cheia lipsește sau este greșită. | | 402 | 36 | Perioada planului s-a încheiat. | | 404 | 34 | Calea nu există, de exemplu un nume de listă scris greșit sau un `media_type` ori `time_window` care nu este în listele de mai sus. | | 405 | 37 | Ai folosit o metodă de scriere pe o cale de listă. | | 429 | 25 | Ai depășit cererile pe minut. Așteaptă numărul de secunde din `Retry-After`. | | 500 | 11 | Un `page` peste 500. | Tabelul complet este pe pagina [erori](https://amodb.dev/ro/errors/). Limitele pe plan sunt la [limite de cereri](https://amodb.dev/ro/rate-limits/). ## Note practice - Marginea ține în cache listele trending, popular, now playing și on the air 30 de minute, iar fiecare cheie partajează aceeași intrare. Un job de reîmprospătare care rulează la fiecare 30 de minute ajunge. - Paginile merg de la 1 la 500. Listele populare raportează `total_results` 20001, ceea ce este un plafon și nu o numărătoare reală. Dincolo de pagina 500, folosește [descoperire](https://amodb.dev/ro/discover/) cu `sort_by` și filtre, care ajunge la titluri pe care un top nu le arată niciodată. - Elementele din liste conțin doar câmpurile necesare unui card. Pentru durată, imdb_id sau credite, apelează [detalii film](https://amodb.dev/ro/movies/) cu `append_to_response`, o dată pentru fiecare card pe care îl deschide utilizatorul. - `language` controlează limba titlurilor și a descrierilor. Titlurile fără traducere revin în textul original, deci verifică dacă sunt șiruri goale înainte să afișezi un card. - Stochează `id`-ul dintr-o listă, nu poziția. Rangurile se schimbă la fiecare reîmprospătare. ## Întrebări și răspunsuri ### Cât timp sunt ținute în cache listele de tendințe și populare? Marginea ține în cache listele trending, popular, now playing și on the air 30 de minute și partajează fiecare intrare între chei. Interogarea mai deasă de 30 de minute întoarce aceeași pagină și consumă cereri degeaba. ### Câte pagini pot citi dintr-o listă? Paginile merg de la 1 la 500, cu câte 20 de rezultate, aceleași limite ca la TMDB. Pentru o răsfoire mai adâncă folosește discover, care filtrează după gen, an, distribuție sau companie în loc să urmeze un singur top fix. ### Ce liste acceptă parametrul region? now_playing și upcoming primesc region ca un cod de țară din două litere majuscule, precum GB, și păstrează doar titlurile lansate acolo. popular și top_rated îl acceptă, dar doar înlocuiesc release_date cu data locală. Listele TV nu au region. airing_today și on_the_air folosesc timezone. ### Pot filtra un top după gen? Nu pe aceste căi. Elementele din liste poartă genre_ids pentru afișare. Ca să filtrezi după gen folosește discover cu with_genres și transformă ID-urile în nume cu endpoint-urile listei de genuri. ## Pagini conexe - [API detalii film](https://amodb.dev/ro/movies/): API detalii film cu aceleași căi și același JSON ca TMDB v3. Preia un film după ID, adaugă credite, evaluări și atmosferă cu append_to_response, în 14 limbi. - [API seriale TV](https://amodb.dev/ro/tv-series/): API seriale TV cu căile și JSON-ul TMDB v3. Preia un serial după ID cu sezoane, rețele și următorul episod, plus clasificări de conținut și furnizori. - [API discover](https://amodb.dev/ro/discover/): API discover cu filtrele TMDB v3. Listează filme și seriale după gen, distribuție, companie, cuvânt-cheie, an, evaluare, durată și furnizor, cu sortare. - [Genuri și liste de referință](https://amodb.dev/ro/genres/): API listă de genuri cu căi TMDB v3: ID-uri de gen pentru filme și TV cu nume traduse, plus liste de țări, limbi, meserii, clasificări și furnizori de vizionare. - [Program de proiecții în cinema](https://amodb.dev/ro/showtimes/): API program proiecții: cinematografe și ore ale unui film într-o țară, sau un rezumat pe țări. Îmbină-l în detalii sau combină-l cu now_playing. - [Limite de cereri](https://amodb.dev/ro/rate-limits/): amodb limitează fiecare cheie în cereri pe minut, în fereastră glisantă de 60 de secunde: 20, 40 sau 120. Citește antetele și tratează 429 cu Retry-After. Actualizat: 2026-10-18. Source: https://amodb.dev/ro/trending-lists/