Endpoints de tendencias y listas

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.

curl -s "https://api.amodb.dev/3/trending/movie/week?language=en-US&page=1" \
  -H "Authorization: Bearer $AMODB_KEY"

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);
}

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
$url = 'https://api.amodb.dev/3/trending/movie/week?language=en-US&page=1';
$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");
}
$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;
}

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

• media_typerutaobligatorio
  all, movie, tv o person.
• time_windowrutaobligatorio
  day o week.
• api_keyconsultauno de los dos
  Tu clave. Usa esta o el encabezado Authorization: Bearer.
• languageconsulta
  Etiqueta TMDB como en-US o ru-RU. Se sirven 14 idiomas base, cualquier otro recurre al inglés.
• pageconsulta
  Número de página de 1 a 500. Cada página tiene 20 resultados.

Campos de la respuesta

Ejemplo de respuesta

{
  "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.

Un objeto dates real tiene este aspecto:

{ "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.

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.

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.

{
  "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

Errores

La tabla completa está en la página de errores. Los límites por plan están en límites de solicitudes.

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 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 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.