# API de horarios de cine > La API de horarios de cine es GET /3/movie/{movie_id}/showtimes?country=US. Devuelve cines con dirección y zona horaria, y cada sesión con hora de inicio, formatos y enlace de reserva cuando se conocen. Sin country solo obtienes recuentos por país. La cobertura varía según el título, y un array results vacío significa que no se sabe nada. ## Obtén los horarios de una película `GET /3/movie/{movie_id}/showtimes?country=US` devuelve los cines que proyectan una película en un país, cada uno con una lista de sesiones. `country` es un código de 2 letras. Sin él, `results` queda vacío y solo obtienes recuentos por país. La cobertura varía según el país y el título, y un array `results` vacío significa que no se sabe nada para ese par. Obtienes el nombre del cine, la cadena, la dirección y la zona horaria, y para cada sesión la hora de inicio, la sala, los formatos, las etiquetas y un enlace de reserva cuando se conocen. Solo se devuelven las sesiones de hoy en adelante. La respuesta describe sesiones. No es un servicio de venta de entradas. ## Qué datos obtienes | Endpoint | Devuelve | | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------- | | `GET /3/movie/{movie_id}/showtimes` | Cines y sesiones de una película en `country`, o recuentos por país sin él | | `GET /3/movie/now_playing` | Películas que están ahora en cines, acotadas con `region` | | `GET /3/movie/{movie_id}` con `append_to_response=showtimes` | Detalles más horarios en una sola solicitud, consulta [horarios de sesiones](https://amodb.dev/es/showtimes/) | Campos de la respuesta de horarios: | Campo | Tipo | Significado | | ---------------------------------------------------------------------------------- | --------------------- | ----------------------------------------------------------------------------------------------- | | `id` | entero | Id de la película | | `country` | cadena o null | El código de 2 letras que pediste, `null` cuando ninguno era válido | | `results` | array | Un elemento por cine, vacío cuando no se sabe nada o falta `country` | | `countries` | array | Recuentos por país: `country`, `name`, `venues`, `cities`, `showtimes`, `first_day`, `last_day` | | `results[].id`, `name`, `city`, `address` | entero, cadenas | Id del cine, nombre, ciudad y dirección postal | | `results[].chain` | objeto o null | `key` y `name` de la cadena de cines | | `results[].timezone` | cadena o null | Zona IANA del cine, por ejemplo `Europe/Moscow` | | `results[].latitude`, `longitude` | número o null | Posición, cuando se conoce | | `results[].region`, `postal_code`, `phone`, `url` | cadena o null | Más datos del cine, a menudo null | | `results[].showtimes` | array | Sesiones en ese cine | | `showtimes[].date` | cadena | Día local como `2026-10-18` | | `showtimes[].start` | cadena | Hora local de inicio como `2026-10-18T21:40`, sin desfase | | `showtimes[].auditorium` | cadena o null | Nombre o número de la sala | | `showtimes[].formats` | array | Formatos de la sesión, por ejemplo `2D`, `IMAX` o `Dolby Atmos` | | `showtimes[].tags` | array | Etiquetas adicionales como `Reserved Seating` | | `showtimes[].booking_url` | cadena o null | Enlace para comprar una entrada, cuando se conoce | | `showtimes[].sold_out` | booleano | `true` cuando la fuente marca la sesión como agotada | | `showtimes[].end`, `audio`, `subtitles`, `language`, `price`, `currency`, `prices` | varios, a menudo null | Se rellenan solo cuando la fuente del cine los proporciona | Una respuesta contiene como máximo 1,500 sesiones, ordenadas por cine y luego por hora de inicio. ## Empieza en 3 pasos 1. Abre [precios](https://amodb.dev/es/pricing/) y elige un plan. Los horarios de sesiones están incluidos en todos los planes. 2. Crea una clave en el panel de tu cuenta. 3. Solicita `/3/movie/{movie_id}/showtimes` con un código `country` y pasa la clave en `api_key` o como encabezado Bearer. ## Ejemplo de solicitud El ejemplo en bash lee los horarios de Fight Club (id `550`) en Rusia, donde amodb tiene hoy sesiones de esa película. El ejemplo en JS toma las primeras cinco películas de la lista `now_playing` de Rusia e imprime hasta tres sesiones por cine, o una nota cuando no se conoce ninguna. ```bash curl -s "https://api.amodb.dev/3/movie/550/showtimes?country=RU" \ -H "Authorization: Bearer $AMODB_KEY" ``` ```js const BASE = 'https://api.amodb.dev/3'; const headers = { Authorization: `Bearer ${process.env.AMODB_KEY}` }; async function get(path, params = {}) { const res = await fetch(`${BASE}${path}?${new URLSearchParams(params)}`, { headers }); if (!res.ok) throw new Error(`amodb returned ${res.status} for ${path}`); return res.json(); } const country = 'RU'; const playing = await get('/movie/now_playing', { region: country, page: 1 }); for (const movie of playing.results.slice(0, 5)) { const { results } = await get(`/movie/${movie.id}/showtimes`, { country }); if (results.length === 0) { console.log(`${movie.title}: no showtimes known`); continue; } for (const cinema of results) { const times = cinema.showtimes .slice(0, 3) .map((s) => `${s.start.slice(5, 10)} ${s.start.slice(11, 16)} ${s.formats.join('/')}`) .join(', '); console.log(`${movie.title} at ${cinema.name}, ${cinema.city}: ${times}`); } } ``` Respuesta recortada para `country=RU`: el primer cine con 2 de sus sesiones. ```json { "id": 550, "country": "RU", "results": [ { "id": 1114, "name": "Мираж Синема НА БОЛЬШОМ", "chain": { "key": "mirage-ru", "name": "Мираж Синема" }, "city": "Санкт-Петербург", "region": null, "address": "Большой пр. П.С., д. 35А", "postal_code": null, "country": "RU", "timezone": "Europe/Moscow", "latitude": null, "longitude": null, "phone": null, "url": "https://www.mirage.ru/spb/cinema/1/", "showtimes": [ { "date": "2026-10-18", "start": "2026-10-18T21:40", "end": null, "auditorium": null, "formats": [ "2D" ], "tags": [], "audio": null, "subtitles": null, "language": null, "price": null, "currency": null, "prices": null, "booking_url": "https://www.mirage.ru/ticket_new/aca7b114-d587-4fc5-9df6-28568e8fa9b3/", "sold_out": false }, { "date": "2026-10-19", "start": "2026-10-19T22:20", "end": null, "auditorium": "Зал №4", "formats": [ "2D" ], "tags": [], "audio": null, "subtitles": null, "language": null, "price": null, "currency": null, "prices": null, "booking_url": "https://www.mirage.ru/ticket_new/0c32e190-890a-4c81-a754-3300fefc4d5e/", "sold_out": false } ] } ], "countries": [ { "country": "RU", "name": "Russia", "venues": 2, "cities": 1, "showtimes": 7, "first_day": "2026-10-18", "last_day": "2026-10-21" } ] } ``` ## Cobertura y resultados vacíos Los datos de cines no están disponibles para todos los países ni títulos. Diseña tu interfaz con eso en cuenta. | Situación | Qué ves | Qué hacer | | --------------------------------------- | --------------------------------------------------------------------- | ---------------------------------------------- | | Hay sesiones conocidas | `results` tiene un elemento por cine | Muestra la lista | | No se sabe nada para este país y título | `results` es un array vacío, `countries` lista dónde hay datos | Muestra una nota neutral, no una tabla vacía | | No se envió `country` | `results` está vacío, `country` es `null`, `countries` trae recuentos | Deja que el usuario elija entre `countries` | | ID de película desconocido | 404 con `status_code` 34 | Revisa el id | | Límite superado | 429 con `status_code` 25 | Espera los segundos indicados en `Retry-After` | Un array vacío no es un error ni afirma que la película falte en los cines. Significa que no se conocen datos de sesiones. Consulta [errores](https://amodb.dev/es/errors/) para ver el formato completo del cuerpo. ## Crea una página de cartelera con los estrenos actuales Combina dos endpoints. La lista te dice qué películas están en cartelera, y los horarios completan las sesiones. | Paso | Solicitud | Notas | | ---- | ---------------------------------------------- | -------------------------------------------------- | | 1 | `GET /3/movie/now_playing?region=US&page=1` | Hasta 20 películas por página, en caché 30 minutos | | 2 | `GET /3/movie/{movie_id}/showtimes?country=US` | Una llamada por película, en caché 30 minutos | | 3 | Filtra en tu código | Por `city`, `formats` o `tags` | Una página de 20 películas cuesta 21 solicitudes. Una respuesta de un gran estreno puede pesar varios cientos de kilobytes, porque contiene hasta 1,500 sesiones. En el plan de 20 solicitudes por minuto eso consume todo el minuto, así que obtén los datos en una tarea en segundo plano y atiende a los visitantes desde tu copia guardada. Los planes de 40 y 120 solicitudes por minuto cubren la misma tarea con margen. Consulta [límites de solicitudes](https://amodb.dev/es/rate-limits/) para ver la ventana y los encabezados, y [tendencias y listas](https://amodb.dev/es/trending-lists/) para los otros endpoints de listas. ## Mantén tu copia al día Los horarios cambian cada día, a diferencia de los detalles de una película. Guarda cada respuesta con su id de película, su país y la hora de consulta. Un TTL de entre 30 minutos y unas pocas horas sirve para la mayoría de las páginas de cartelera, y las sesiones que ya empezaron se pueden ocultar comparando `start` con la hora actual en el `timezone` del cine. Como `start` no tiene desfase, no lo cambies a la zona horaria del visitante. ## Cómo se compara | Capacidad | Hacer scraping de los sitios de los cines | API de metadatos sin horarios | amodb | | ------------------------------ | ----------------------------------------- | ----------------------------- | -------------------------------------------------------------- | | Configuración | Un scraper por cada sitio de cine | No disponible | Un endpoint, un formato JSON | | Relación con un id de película | Emparejar por el texto del título | No disponible | Id de película en la ruta | | Cobertura | Lo que logres extraer | Ninguna | Varía según el país y el título, array vacío cuando no se sabe | | Formatos y reservas | Analizar etiquetas y enlaces | No disponible | Campos `formats`, `tags` y `booking_url` | | Mantenimiento | Se rompe cuando un sitio cambia | Ninguno | Un formato JSON para todos los países | ## Precios Los planes prepago duran 1, 3, 6, 12 o 24 meses, con 0, 10, 20, 30 o 40 por ciento de descuento en los más largos. Nada se renueva automáticamente. Los planes permiten 20, 40 y 120 solicitudes por minuto y cada uno incluye los horarios de sesiones junto con el resto de los datos. Una página de cartelera que se actualiza cada 30 minutos para unos pocos países cabe en el límite más bajo. No hay nivel gratuito. Elige un plan en [precios](https://amodb.dev/es/pricing/). ## Preguntas y respuestas ### ¿Cómo obtengo los horarios de una película? Envía GET /3/movie/{movie_id}/showtimes?country=US con tu clave. El parámetro country es un código de 2 letras, y region funciona como alias. La respuesta lista los cines, y cada cine trae sus sesiones con hora de inicio, formatos, etiquetas y enlace de reserva cuando se conocen. ### ¿Qué significa un array results vacío? Significa que amodb no tiene datos de sesiones de esa película en ese país. No es un error, y tampoco indica que la película no esté en cartelera. El array countries de la misma respuesta sigue listando dónde hay datos, así que puedes ofrecer otro país. ### ¿Qué países están cubiertos? La cobertura varía según el país y el título. Cada respuesta incluye un array countries con los recuentos de cines, ciudades y sesiones, hasta 60 países y con los que tienen más sesiones primero. Léelo por película en lugar de fijar una lista en tu código. ### ¿Puedo listar las películas que están ahora en cines? Sí. GET /3/movie/now_playing con el parámetro region lista los estrenos actuales, en caché 30 minutos. Toma cada id de película de esa lista y solicita sus horarios con el mismo código de país. ### ¿Qué zona horaria usan los valores start? Un valor start tiene el formato 2026-10-18T21:40 y no lleva desfase UTC. Trátalo como la hora local del cine. Cada cine también tiene un timezone como Europe/Moscow. No conviertas start a la zona horaria del espectador. ## Páginas relacionadas - [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. - [Endpoints de tendencias y listas](https://amodb.dev/es/trending-lists/): API de películas en tendencia con rutas TMDB v3: rankings diarios y semanales, más cartelera, populares, mejor valoradas y estrenos. Caché de 30 minutos. - [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. - [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. - [Inicio rápido](https://amodb.dev/es/quickstart/): Haz tu primera llamada a amodb: consigue una clave, pide los detalles de una película en curl, JavaScript, Python, PHP o Go y carga el póster. En 2 minutos. Actualizado: 2026-10-18. Source: https://amodb.dev/es/cinema-showtimes-api/