# Endpoints de tendencias y listas > Los endpoints de tendencias y listas devuelven páginas ordenadas de películas, series o personas. Usa GET /3/trending/{media_type}/{time_window} para rankings del día y la semana, y las rutas de listas de movie y tv para populares, mejor valoradas, cartelera, estrenos, series de hoy y en emisión. Cada página tiene 20 resultados y 30 minutos de caché. ## 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" ``` Respuesta: ```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 } ``` ## Obtén los títulos en tendencia `GET /3/trending/{media_type}/{time_window}` devuelve una página ordenada de lo que la gente está viendo o buscando ahora mismo. `media_type` es `all`, `movie`, `tv` o `person`. `time_window` es `day` o `week`. Los rankings del día cambian rápido y encajan en una franja de «esta noche». Los rankings de la semana son más estables y encajan en una página de inicio. El ejemplo pide el ranking semanal de películas e imprime los diez primeros 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 | En | Obligatorio | Descripción | | ------------- | -------- | -------------- | -------------------------------------------------------------------------------------------------- | | `media_type` | ruta | sí | `all`, `movie`, `tv` o `person`. | | `time_window` | ruta | sí | `day` o `week`. | | `api_key` | consulta | uno de los dos | Tu clave. Usa esta o el encabezado `Authorization: Bearer`. | | `language` | consulta | no | Etiqueta TMDB como `en-US` o `ru-RU`. Se sirven 14 idiomas base, cualquier otro recurre al inglés. | | `page` | consulta | no | Número de página de 1 a 500. Cada página tiene 20 resultados. | ### Campos de la respuesta | Campo | Tipo | Notas | | --------------------------------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | `page` | entero | La página que pediste. | | `results` | array | Objetos de película, TV o persona, con el mejor puesto primero. | | `total_pages`, `total_results` | entero | Totales de paginación. Los rankings de tendencias informan como máximo 500 páginas y 10000 resultados. | | `media_type` | texto | `movie`, `tv` o `person` en cada elemento en tendencia. Léelo cuando solicites `all`. | | `id` | entero | Úsalo con [películas](https://amodb.dev/es/movies/), [series de TV](https://amodb.dev/es/tv-series/) o [personas](https://amodb.dev/es/people/). | | `title`, `original_title` | texto | Elementos de película. Los de TV usan `name` y `original_name`. | | `release_date`, `first_air_date` | texto | `YYYY-MM-DD` para elementos de película y de TV. | | `genre_ids` | array | IDs numéricos. Los nombres vienen de [géneros](https://amodb.dev/es/genres/). | | `popularity`, `vote_average`, `vote_count` | número | Datos de ranking y la puntuación agregada de los usuarios. | | `poster_path`, `backdrop_path`, `profile_path` | texto o null | Se añaden a `https://img.amodb.dev/t/p/{size}`. | | `name`, `original_name`, `gender`, `known_for_department` | texto o entero | Elementos de persona. `known_for` es un array vacío en los elementos de persona en tendencia. | ### Ejemplo de respuesta ```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 respuesta se obtuvo de la API real y se recortó a 3 de las 20 entradas de la página 1. Las cadenas `overview` largas están acortadas, y los puestos y los recuentos cambian en cada actualización. ## Listas de películas Los rankings de películas comparten una misma estructura: un array `results` paginado de objetos de película. `now_playing` y `upcoming` añaden un objeto `dates` con `minimum` y `maximum`, la ventana de estrenos que cubre la lista. Los cuatro aceptan `language`, `page` y `region`. | Método y ruta | Devuelve | | ------------------------ | --------------------------------------------------------------------------------- | | `GET /movie/now_playing` | Películas estrenadas dentro de la ventana `dates` alrededor de hoy, más `dates` | | `GET /movie/popular` | Películas ordenadas por popularidad actual | | `GET /movie/top_rated` | Películas ordenadas por puntuación de los usuarios | | `GET /movie/upcoming` | Películas con fecha de estreno futura, más `dates` | | `GET /movie/latest` | Un solo objeto de película: la entrada más reciente del catálogo. No es una lista | Un objeto `dates` real tiene este aspecto: ```json { "dates": { "maximum": "2026-10-21", "minimum": "2026-09-09" } } ``` `region` es un código ISO 3166-1 en mayúsculas, como `DE` o `GB`. En `now_playing` y `upcoming` conserva solo los títulos estrenados en ese país, así que la lista es una parte pequeña de la mundial. Un código desconocido devuelve una lista vacía. En `popular` y `top_rated` solo cambia `release_date` por la fecha local y no modifica el orden. Para ver dónde se proyecta una película, combina `now_playing` con [horarios de cine](https://amodb.dev/es/showtimes/). ## Listas de TV Los rankings de TV devuelven los mismos campos de paginación. Los elementos usan `name`, `original_name`, `first_air_date` y `origin_country` en lugar de los nombres de las películas. Los cuatro aceptan `language` y `page`. | Método y ruta | Devuelve | Parámetros adicionales | | ---------------------- | ------------------------------------------------------------------------------------ | ---------------------- | | `GET /tv/airing_today` | Series con un episodio que se emite hoy | `timezone` | | `GET /tv/on_the_air` | Series con un episodio que se emite en los próximos días | `timezone` | | `GET /tv/popular` | Series ordenadas por popularidad actual | ninguno | | `GET /tv/top_rated` | Series ordenadas por puntuación de los usuarios | ninguno | | `GET /tv/latest` | Un solo objeto de serie de TV: la entrada más reciente del catálogo. No es una lista | ninguno | `timezone` es un nombre IANA, como `Europe/Rome`. Decide qué día del calendario cuenta como «hoy», así que `airing_today` devuelve un conjunto distinto para `Asia/Tokyo` que para `Pacific/Auckland`. Las listas de TV no tienen parámetro `region`. ## Listas de personas `GET /person/popular` devuelve una lista paginada de personas ordenadas por popularidad, con `language` y `page`. Cada entrada tiene `id`, `name`, `original_name`, `known_for_department`, `gender`, `profile_path`, `popularity` y un array `known_for` de hasta 3 fichas de película o TV, cada una con `media_type`. Abre una persona en [personas](https://amodb.dev/es/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 no ofrece `person/latest` ni los feeds de `changes`. ## Elige la lista adecuada para cada pantalla | Pantalla | Llamada | Actualización | | ------------------------------------- | ------------------------------------ | --------------------------- | | Fila principal de la página de inicio | `/trending/all/week` | Como máximo cada 30 minutos | | Pestaña «En cines» | `/movie/now_playing` con tu `region` | Como máximo cada 30 minutos | | Pestaña «Próximamente» | `/movie/upcoming` con tu `region` | Como máximo cada 30 minutos | | Franja «Esta noche en TV» | `/tv/airing_today` con un `timezone` | Como máximo cada 30 minutos | | Favoritas de todos los tiempos | `/movie/top_rated` | Una vez al día basta | | Personas que la gente busca | `/trending/person/day` | Como máximo cada 30 minutos | | Personas más populares en general | `/person/popular` | Como máximo cada 30 minutos | ## Errores | HTTP | status_code | Cuándo | | ---- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------ | | 401 | 7 | Falta la clave o es incorrecta. | | 402 | 36 | El periodo del plan ha terminado. | | 404 | 34 | La ruta no existe, por ejemplo un nombre de lista mal escrito o un `media_type` o `time_window` que no está en las listas de arriba. | | 405 | 37 | Usaste un método de escritura en una ruta de lista. | | 429 | 25 | Superaste tus solicitudes por minuto. Espera los segundos indicados en `Retry-After`. | | 500 | 11 | Un `page` superior a 500. | La tabla completa está en la página de [errores](https://amodb.dev/es/errors/). Los límites por plan están en [límites de solicitudes](https://amodb.dev/es/rate-limits/). ## Notas prácticas - La caché perimetral guarda las listas de tendencias, populares, en cartelera y en emisión durante 30 minutos, y todas las claves comparten la misma entrada. Basta con una tarea de actualización cada 30 minutos. - Las páginas van de 1 a 500. Las listas populares informan un `total_results` de 20001, que es un tope y no un recuento real. Pasada la página 500, usa [discover](https://amodb.dev/es/discover/) con `sort_by` y filtros, que llega a títulos que un ranking nunca muestra. - Los elementos de lista solo traen los campos necesarios para una ficha. Para la duración, el imdb_id o los créditos, llama a los [detalles de película](https://amodb.dev/es/movies/) con `append_to_response`, una vez por cada ficha que abra el usuario. - `language` controla el idioma de los títulos y las sinopsis. Los títulos sin traducción llegan en el texto original, así que comprueba si hay cadenas vacías antes de dibujar una ficha. - Guarda el `id` de una lista, no la posición. Los puestos cambian en cada actualización. ## Preguntas y respuestas ### ¿Cuánto tiempo se guardan en caché las listas de tendencias y populares? La caché perimetral guarda las listas de tendencias, populares, en cartelera y en emisión durante 30 minutos y comparte cada entrada entre todas las claves. Consultar con más frecuencia que cada 30 minutos devuelve la misma página y gasta solicitudes sin motivo. ### ¿Cuántas páginas puedo leer de una lista? Las páginas van de 1 a 500 con 20 resultados cada una, los mismos límites que TMDB. Para navegar más a fondo usa discover, que filtra por género, año, reparto o productora en lugar de seguir un único ranking fijo. ### ¿Qué listas aceptan el parámetro region? now_playing y upcoming toman region como código de país de dos letras en mayúsculas, como GB, y solo conservan los títulos estrenados allí. popular y top_rated lo aceptan, pero solo cambian release_date por la fecha local. Las listas de TV no tienen region. airing_today y on_the_air usan timezone. ### ¿Puedo filtrar un ranking por género? No en estas rutas. Los elementos de las listas traen genre_ids para mostrarlos. Para filtrar por género usa discover con with_genres, y convierte los ids en nombres con los endpoints de listas de géneros. ## Páginas relacionadas - [API de detalles de película](https://amodb.dev/es/movies/): API de detalles de película con rutas y JSON de TMDB v3. Obtén una película por id y añade créditos, puntuaciones y moods con append_to_response, en 14 idiomas. - [API de series de TV](https://amodb.dev/es/tv-series/): API de series de TV con las mismas rutas y JSON que TMDB v3. Obtén una serie con temporadas, cadenas y próximo episodio, más clasificaciones y plataformas. - [API Discover](https://amodb.dev/es/discover/): API Discover con los mismos filtros que TMDB v3. Lista películas y series por género, reparto, productora, palabra clave, año, nota, duración y plataforma. - [Géneros y listas de consulta](https://amodb.dev/es/genres/): API de géneros con rutas TMDB v3: ids de género de películas y TV con nombres traducidos, más listas de países, idiomas, oficios, clasificaciones y proveedores. - [Horarios de cine](https://amodb.dev/es/showtimes/): API de horarios de cine que devuelve los cines y las sesiones de una película en un país, o un resumen por país. Úsala con details o junto a now_playing. - [Límites de solicitudes](https://amodb.dev/es/rate-limits/): amodb limita cada clave por solicitudes por minuto en una ventana deslizante de 60 segundos: 20, 40 o 120 según el plan. Lee los encabezados y gestiona el 429. Actualizado: 2026-10-18. Source: https://amodb.dev/es/trending-lists/