API de series de TV para temporadas y episodios

Una API de series de TV con estado, temporadas y próximo episodio

GET /3/tv/{series_id} devuelve una serie con su status, networks, la lista seasons, last_episode_to_air y next_episode_to_air. Los endpoints de temporada y episodio añaden fechas de emisión, duraciones y fotogramas. amodb es una API independiente que habla el protocolo TMDB v3, así que un cliente escrito para TMDB funciona después de cambiar la URL base a https://api.amodb.dev/3.

Qué obtienes:

• Registros de series con el número de temporadas y episodios, además de las fechas de la primera y la última emisión.
• Un campo status de texto y un indicador in_production.
• Cadenas de TV con ids, logotipos y país de origen.
• Una llamada por temporada, que devuelve todos los episodios de esa temporada.
• Listas de series que se emiten hoy o en los próximos 7 días.

Qué datos obtienes

Las listas completas de campos están en series de TV y temporadas y episodios.

Empieza en 3 pasos

1. Abre precios y elige el plan con la velocidad de solicitudes que necesitas: 20, 40 o 120 por minuto.
2. Crea una clave de API en el panel de tu cuenta.
3. Envía GET /3/tv/{series_id} con Authorization: Bearer YOUR_API_KEY, o añade api_key como parámetro de consulta.

Ejemplo de solicitud

El script lee Breaking Bad (id de serie 1396), imprime su estado y el siguiente episodio, y luego lista la temporada 1. Guárdalo como check.mjs y ejecútalo con Node 18 o superior.

curl -s "https://api.amodb.dev/3/tv/1396?language=en-US&append_to_response=ratings" \
  -H "Authorization: Bearer $AMODB_KEY"

curl -s "https://api.amodb.dev/3/tv/1396/season/1?language=en-US" \
  -H "Authorization: Bearer $AMODB_KEY"

const base = 'https://api.amodb.dev/3';
const headers = { Authorization: `Bearer ${process.env.AMODB_KEY}` };

async function get(path) {
  const res = await fetch(`${base}${path}`, { headers });
  if (!res.ok) throw new Error(`amodb returned ${res.status} for ${path}`);
  return res.json();
}

const show = await get('/tv/1396?language=en-US');
const next = show.next_episode_to_air;
console.log(`${show.name}: ${show.status}, ${show.number_of_seasons} seasons`);
console.log(next
  ? `Next: S${next.season_number}E${next.episode_number} on ${next.air_date}`
  : 'No upcoming episode is scheduled');

const season = await get('/tv/1396/season/1?language=en-US');
for (const ep of season.episodes) {
  console.log(`E${ep.episode_number} ${ep.air_date} ${ep.name}`);
}

Una respuesta de serie recortada para language=en-US. Solo se conservan algunos campos, y seasons muestra sus primeras 2 de 6 entradas. Algunos nombres no siguen a language en estos datos: el nombre de la temporada 0 está en chino y el name dentro de last_episode_to_air está en hebreo.

{
  "first_air_date": "2008-01-20",
  "id": 1396,
  "in_production": false,
  "last_air_date": "2013-09-29",
  "last_episode_to_air": {
    "air_date": "2013-09-29",
    "episode_number": 16,
    "episode_type": "standard",
    "id": 62161,
    "name": "פלינה",
    "overview": "הסדרה זוכת הפרסים מגיעה לסיום דרמתי בפרק החותם אותה.",
    "production_code": "",
    "runtime": 56,
    "season_number": 5,
    "show_id": 1396,
    "still_path": "/pA0YwyhvdDXP3BEGL2grrIhq8aM.jpg",
    "vote_average": 0,
    "vote_count": 0
  },
  "name": "Breaking Bad",
  "next_episode_to_air": null,
  "number_of_episodes": 62,
  "number_of_seasons": 5,
  "original_name": "Breaking Bad",
  "seasons": [
    {
      "air_date": "2009-02-17",
      "episode_count": 9,
      "id": 3577,
      "name": "特别篇",
      "overview": "",
      "poster_path": "/ikBSCmgG5Z4jequUUAjKpf1QG3T.jpg",
      "season_number": 0,
      "vote_average": 0
    },
    {
      "air_date": "2008-01-20",
      "episode_count": 7,
      "id": 3572,
      "name": "Season 1",
      "overview": "High school chemistry teacher Walter White's life is suddenly transformed by a dire medical diagn...",
      "poster_path": "/91EIXdWxmp2mHNRsSuDW3WyDJLj.jpg",
      "season_number": 1,
      "vote_average": 0
    }
  ],
  "status": "Ended"
}

Cómo leer el estado y el siguiente episodio

El texto de status te dice cómo etiquetar una serie. next_episode_to_air es un objeto solo mientras hay un episodio programado, así que es null entre temporadas y también después del final. Comprueba status antes de mostrar «finalizada».

Campos dentro de next_episode_to_air y last_episode_to_air: air_date, season_number, episode_number, episode_type, id, show_id, name, overview, runtime y still_path. El texto de status también puede venir vacío en algunos títulos, así que ten lista una etiqueta neutral.

Los detalles se guardan en la caché perimetral durante 6 horas, así que pedir la misma serie más de cuatro veces al día devuelve el mismo cuerpo. Consulta una o dos veces al día las series que sigues y actualiza la que abre un usuario.

Temporadas, episodios y lo que se emite

La temporada 0, cuando una serie la tiene, contiene los especiales. Las temporadas regulares empiezan en 1.

Las listas y los resultados de discover se guardan en caché 30 minutos, así que una solicitud cada media hora basta para una insignia de «se emite pronto». Compara los ids devueltos con las series que siguen tus usuarios. Los detalles de temporadas y episodios están en la página de la guía de episodios.

Crea una lista de seguimiento con cuentas regresivas

Una pantalla de «series que sigo» necesita un id guardado por serie y una pequeña tarea diaria.

1. Guarda el id de la serie cuando un usuario la sigue.
2. Una vez al día, llama a /3/tv/{series_id} por cada id seguido y guarda status, next_episode_to_air y last_air_date.
3. Cuando next_episode_to_air es un objeto, muestra air_date como fecha. No incluye hora del día ni zona horaria, así que no cuentes hacia atrás hasta el minuto.
4. Cuando es null y status es Returning Series, muestra «temporada nueva sin programar».
5. Pide la llamada de temporada solo cuando un usuario abre la serie, porque es la respuesta más grande.

Un 404 con status_code 34 significa que el id no existe, y un 429 significa que superaste tus solicitudes por minuto: espera Retry-After segundos. Con 200 series seguidas, una pasada diaria son 200 solicitudes, unos diez minutos a 20 solicitudes por minuto. Consulta límites de solicitudes y errores.

Cómo se compara

Precios

Paga una vez por 1, 3, 6, 12 o 24 meses. Los periodos más largos tienen un descuento del 10, 20, 30 o 40 por ciento y nada se renueva automáticamente. Todos los planes dan acceso a todos los datos de TV, con 20, 40 o 120 solicitudes por minuto como única diferencia. Consulta precios, crea una clave y tu primera llamada de serie cuesta una solicitud.