# Endpoints de em alta e de listas > Os endpoints de em alta e de listas retornam páginas ranqueadas de filmes, séries ou pessoas. Use GET /3/trending/{media_type}/{time_window} para os rankings do dia e da semana, e os caminhos de movie e tv para populares, mais bem avaliados, em cartaz, em breve, no ar hoje e no ar. Cada página tem 20 resultados, com cache de 30 minutos. ## 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" ``` Resposta: ```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 } ``` ## Obter os títulos em alta `GET /3/trending/{media_type}/{time_window}` retorna uma página ranqueada do que as pessoas estão assistindo ou pesquisando agora. `media_type` é `all`, `movie`, `tv` ou `person`. `time_window` é `day` ou `week`. Os rankings do dia mudam rápido e servem para uma faixa “hoje à noite”. Os rankings da semana são mais estáveis e servem para uma página inicial. O exemplo pede o ranking semanal de filmes e imprime os dez primeiros títulos. ```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) } } ``` ### Parâmetros | Parâmetro | Em | Obrigatório | Descrição | | ------------- | -------- | ----------- | ------------------------------------------------------------------------------------------------------- | | `media_type` | caminho | sim | `all`, `movie`, `tv` ou `person`. | | `time_window` | caminho | sim | `day` ou `week`. | | `api_key` | consulta | um dos dois | Sua chave. Use este parâmetro ou o header `Authorization: Bearer`. | | `language` | consulta | não | Tag do TMDB como `en-US` ou `ru-RU`. 14 idiomas base são atendidos, qualquer outro volta para o inglês. | | `page` | consulta | não | Número da página, de 1 a 500. Cada página tem 20 resultados. | ### Campos da resposta | Campo | Tipo | Observações | | --------------------------------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | `page` | inteiro | A página que você pediu. | | `results` | array | Objetos de filme, série ou pessoa, do melhor ranking para o pior. | | `total_pages`, `total_results` | inteiro | Totais de paginação. Os rankings em alta informam no máximo 500 páginas e 10000 resultados. | | `media_type` | string | `movie`, `tv` ou `person` em todo item em alta. Leia-o quando pedir `all`. | | `id` | inteiro | Use com [filmes](https://amodb.dev/pt/movies/), [séries de TV](https://amodb.dev/pt/tv-series/) ou [pessoas](https://amodb.dev/pt/people/). | | `title`, `original_title` | string | Itens de filme. Os itens de série usam `name` e `original_name`. | | `release_date`, `first_air_date` | string | `YYYY-MM-DD` para itens de filme e de série. | | `genre_ids` | array | Ids numéricos. Os nomes vêm de [gêneros](https://amodb.dev/pt/genres/). | | `popularity`, `vote_average`, `vote_count` | número | Dados do ranking e a nota agregada dos usuários. | | `poster_path`, `backdrop_path`, `profile_path` | string ou null | Acrescente a `https://img.amodb.dev/t/p/{size}`. | | `name`, `original_name`, `gender`, `known_for_department` | string ou inteiro | Itens de pessoa. `known_for` é um array vazio nos itens de pessoa em alta. | ### Exemplo de resposta ```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 } ``` A resposta veio da API real e foi cortada para 3 das 20 entradas da página 1. Os textos longos de `overview` estão abreviados, e posições e contagens mudam a cada atualização. ## Listas de filmes Os rankings de filmes têm um formato só: um array `results` paginado de objetos de filme. `now_playing` e `upcoming` acrescentam um objeto `dates` com `minimum` e `maximum`, a janela de lançamentos que a lista cobre. Os quatro aceitam `language`, `page` e `region`. | Método e caminho | Retorna | | ------------------------ | ----------------------------------------------------------------------- | | `GET /movie/now_playing` | Filmes lançados dentro da janela `dates` em torno de hoje, mais `dates` | | `GET /movie/popular` | Filmes ordenados pela popularidade atual | | `GET /movie/top_rated` | Filmes ordenados pela nota dos usuários | | `GET /movie/upcoming` | Filmes com data de lançamento no futuro, mais `dates` | | `GET /movie/latest` | Um objeto de filme: a entrada mais recente do catálogo. Não é uma lista | Um objeto `dates` real é assim: ```json { "dates": { "maximum": "2026-10-21", "minimum": "2026-09-09" } } ``` `region` é um código ISO 3166-1 em maiúsculas, como `DE` ou `GB`. Em `now_playing` e `upcoming` ele mantém só os títulos lançados nesse país, então a lista é uma parte pequena da mundial. Um código desconhecido retorna uma lista vazia. Em `popular` e `top_rated` ele só troca `release_date` pela data local e não muda a ordem. Para ver onde um filme está em cartaz, combine `now_playing` com [horários de sessões](https://amodb.dev/pt/showtimes/). ## Listas de séries Os rankings de séries retornam os mesmos campos de paginação. Os itens usam `name`, `original_name`, `first_air_date` e `origin_country` no lugar dos nomes dos filmes. Os quatro aceitam `language` e `page`. | Método e caminho | Retorna | Parâmetros extras | | ---------------------- | ----------------------------------------------------------------------- | ----------------- | | `GET /tv/airing_today` | Séries com um episódio no ar hoje | `timezone` | | `GET /tv/on_the_air` | Séries com um episódio no ar nos próximos dias | `timezone` | | `GET /tv/popular` | Séries ordenadas pela popularidade atual | nenhum | | `GET /tv/top_rated` | Séries ordenadas pela nota dos usuários | nenhum | | `GET /tv/latest` | Um objeto de série: a entrada mais recente do catálogo. Não é uma lista | nenhum | `timezone` é um nome IANA como `Europe/Rome`. Ele decide qual dia do calendário conta como “hoje”, então `airing_today` retorna um conjunto diferente para `Asia/Tokyo` e para `Pacific/Auckland`. As listas de séries não têm o parâmetro `region`. ## Listas de pessoas `GET /person/popular` retorna uma lista paginada de pessoas ordenadas por popularidade, com `language` e `page`. Cada entrada tem `id`, `name`, `original_name`, `known_for_department`, `gender`, `profile_path`, `popularity` e um array `known_for` com até 3 cards de filme ou de série, cada um com `media_type`. Abra uma pessoa em [pessoas](https://amodb.dev/pt/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 } ``` O amodb não oferece `person/latest` nem os feeds de `changes`. ## Escolher a lista certa para cada tela | Tela | Chamada | Atualização | | ------------------------------------- | --------------------------------------- | --------------------------- | | Faixa de destaque da página inicial | `/trending/all/week` | No máximo a cada 30 minutos | | Aba “Nos cinemas” | `/movie/now_playing` com o seu `region` | No máximo a cada 30 minutos | | Aba “Em breve” | `/movie/upcoming` com o seu `region` | No máximo a cada 30 minutos | | Faixa “Hoje à noite na TV” | `/tv/airing_today` com um `timezone` | No máximo a cada 30 minutos | | Favoritos de todos os tempos | `/movie/top_rated` | Uma vez por dia basta | | Pessoas que o público está procurando | `/trending/person/day` | No máximo a cada 30 minutos | | Pessoas mais populares no geral | `/person/popular` | No máximo a cada 30 minutos | ## Erros | HTTP | status_code | Quando | | ---- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | 401 | 7 | A chave está ausente ou incorreta. | | 402 | 36 | O período do plano terminou. | | 404 | 34 | O caminho não existe, por exemplo um nome de lista com erro de grafia ou um `media_type` ou `time_window` que não está nas listas acima. | | 405 | 37 | Você usou um método de escrita em um caminho de lista. | | 429 | 25 | Você passou do seu limite de requisições por minuto. Espere os segundos indicados em `Retry-After`. | | 500 | 11 | Um valor de `page` acima de 500. | A tabela completa está na página de [erros](https://amodb.dev/pt/errors/). Os limites por plano estão em [limites de requisições](https://amodb.dev/pt/rate-limits/). ## Notas práticas - O cache de borda guarda as listas de em alta, populares, em cartaz e no ar por 30 minutos, e todas as chaves compartilham a mesma entrada. Uma tarefa de atualização a cada 30 minutos basta. - As páginas vão de 1 a 500. As listas de populares informam `total_results` de 20001, que é um teto e não uma contagem real. Depois da página 500, use o [discover](https://amodb.dev/pt/discover/) com `sort_by` e filtros, que alcança títulos que um ranking nunca mostra. - Os itens da lista trazem só os campos necessários para um card. Para duração, imdb_id ou créditos, chame os [detalhes do filme](https://amodb.dev/pt/movies/) com `append_to_response`, uma vez por card que o usuário abrir. - `language` controla o idioma de títulos e sinopses. Títulos sem tradução voltam no texto original, então confira se há strings vazias antes de renderizar um card. - Guarde o `id` de uma lista, não a posição. As posições mudam a cada atualização. ## Perguntas e respostas ### Por quanto tempo as listas de em alta e de populares ficam em cache? O cache de borda guarda as listas de em alta, populares, em cartaz e no ar por 30 minutos e compartilha cada entrada entre as chaves. Consultar em menos de 30 minutos retorna a mesma página e gasta requisições à toa. ### Quantas páginas posso ler de uma lista? As páginas vão de 1 a 500, com 20 resultados cada, os mesmos limites do TMDB. Para navegar mais fundo, use o discover, que filtra por gênero, ano, elenco ou produtora em vez de seguir um único ranking fixo. ### Quais listas aceitam o parâmetro region? now_playing e upcoming recebem region como um código de país de duas letras em maiúsculas, como GB, e mantêm só os títulos lançados lá. popular e top_rated o aceitam, mas só trocam release_date pela data local. As listas de séries não têm region. airing_today e on_the_air usam timezone. ### Posso filtrar um ranking por gênero? Não nestes caminhos. Os itens da lista trazem genre_ids para exibição. Para filtrar por gênero, use o discover com with_genres e transforme os ids em nomes com os endpoints de lista de gêneros. ## Páginas relacionadas - [API de detalhes de filmes](https://amodb.dev/pt/movies/): API de detalhes de filmes com caminhos e JSON do TMDB v3. Busque um filme por id e junte créditos, avaliações e moods com append_to_response, em 14 idiomas. - [API de séries de TV](https://amodb.dev/pt/tv-series/): API de séries de TV com os mesmos caminhos e JSON do TMDB v3. Busque uma série por id com temporadas, emissoras, próximo episódio e classificações. - [API Discover](https://amodb.dev/pt/discover/): API Discover com os mesmos filtros do TMDB v3. Liste filmes e séries por gênero, elenco, produtora, palavra-chave, ano, nota, duração e provedor, com ordenação. - [Gêneros e listas de consulta](https://amodb.dev/pt/genres/): API de gêneros com caminhos do TMDB v3: ids de gênero de filmes e TV com nomes traduzidos, mais listas de países, idiomas, funções, classificações e provedores. - [Horários de sessões de cinema](https://amodb.dev/pt/showtimes/): API de horários de sessões que retorna os locais de exibição e as sessões de um filme em um país, ou o resumo por país. Junte aos detalhes ou ao now_playing. - [Limites de requisições](https://amodb.dev/pt/rate-limits/): O amodb limita cada chave por requisições por minuto em uma janela de 60 segundos: 20, 40 ou 120 por plano. Leia os cabeçalhos e trate o 429 com Retry-After. Atualizado: 2026-10-18. Source: https://amodb.dev/pt/trending-lists/