API de horários de sessões de cinema

A API de horários de sessões de cinema é GET /3/movie/{movie_id}/showtimes?country=US. Ela retorna cinemas com endereço e fuso horário, e cada sessão com horário de início, formatos e link de reserva, quando conhecidos. Sem country, você recebe só contagens por país. A cobertura varia por título, e um array results vazio significa que nada é conhecido.

Ver planos Ler o guia rápido

Requisição

curl JavaScript

bashjs

curl -s "https://api.amodb.dev/3/movie/550/showtimes?country=RU" \
  -H "Authorization: Bearer $AMODB_KEY"

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

Resposta 200

{
  "id": 550,
  "country": "RU",
  "results": [
    {
      "id": 1114,
      "name": "Мираж Синема НА БОЛЬШОМ",
      "chain": {
        "key": "mirage-ru",
        "name": "Мираж Синема"
      },
      "city": "Санкт-Петербург",
      "region": null,
      "address": "Большой пр. П.С., д. 35А",

Obtenha os horários de sessões de um filme

GET /3/movie/{movie_id}/showtimes?country=US retorna os cinemas que exibem um filme em um país, cada um com uma lista de sessões. country é um código de 2 letras. Sem ele, results fica vazio e você recebe apenas contagens por país. A cobertura varia por país e por título, e um array results vazio significa que nada é conhecido para esse par.

Você recebe o nome do cinema, a rede, o endereço e o fuso horário, e de cada sessão o horário de início, a sala, os formatos, as tags e um link de reserva, quando conhecidos. Só são retornadas as sessões de hoje em diante. A resposta descreve sessões. Não é um serviço de venda de ingressos.

Quais dados você recebe

Endpoint	Retorna
`GET /3/movie/{movie_id}/showtimes`	Cinemas e sessões de um filme em `country`, ou contagens por país sem ele
`GET /3/movie/now_playing`	Filmes atualmente em cartaz, filtrados por `region`
`GET /3/movie/{movie_id}` com `append_to_response=showtimes`	Detalhes mais horários de sessões em uma requisição, veja horários de sessões

Campos da resposta de horários de sessões:

Campo	Tipo	Significado
`id`	inteiro	ID do filme
`country`	string ou null	O código de 2 letras que você pediu, `null` quando nenhum era válido
`results`	array	Um item por cinema, vazio quando nada é conhecido ou quando falta `country`
`countries`	array	Contagens por país: `country`, `name`, `venues`, `cities`, `showtimes`, `first_day`, `last_day`
`results[].id`, `name`, `city`, `address`	inteiro, strings	ID, nome, cidade e endereço do cinema
`results[].chain`	objeto ou null	`key` e `name` da rede de cinemas
`results[].timezone`	string ou null	Zona IANA do cinema, por exemplo `Europe/Moscow`
`results[].latitude`, `longitude`	número ou null	Posição, quando conhecida
`results[].region`, `postal_code`, `phone`, `url`	string ou null	Outros dados do cinema, muitas vezes null
`results[].showtimes`	array	Sessões nesse cinema
`showtimes[].date`	string	Dia local, como `2026-10-18`
`showtimes[].start`	string	Horário local de início, como `2026-10-18T21:40`, sem deslocamento
`showtimes[].auditorium`	string ou null	Nome ou número da sala
`showtimes[].formats`	array	Formatos da sessão, por exemplo `2D`, `IMAX` ou `Dolby Atmos`
`showtimes[].tags`	array	Rótulos extras, como `Reserved Seating`
`showtimes[].booking_url`	string ou null	Link para comprar o ingresso, quando conhecido
`showtimes[].sold_out`	booleano	`true` quando a fonte marca a sessão como esgotada
`showtimes[].end`, `audio`, `subtitles`, `language`, `price`, `currency`, `prices`	vários, muitas vezes null	Preenchidos só quando a fonte do cinema os fornece

Uma resposta traz no máximo 1,500 sessões, ordenadas por cinema e depois por horário de início.

Comece em 3 passos

Abra preços e escolha um plano. Os horários de sessões estão incluídos em todos os planos.
Crie uma chave no painel da sua conta.
Faça a requisição de /3/movie/{movie_id}/showtimes com um código country e passe a chave em api_key ou em um cabeçalho Bearer.

Exemplo de requisição

O exemplo em bash lê os horários de sessões de Fight Club (ID 550) na Rússia, onde o amodb tem sessões dele hoje. O exemplo em JS pega os cinco primeiros filmes da lista now_playing russa e imprime até três sessões por cinema, ou uma nota quando nenhuma é conhecida.

curl JavaScript

bashjs

curl -s "https://api.amodb.dev/3/movie/550/showtimes?country=RU" \
  -H "Authorization: Bearer $AMODB_KEY"

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

Resposta reduzida para country=RU: o primeiro cinema com 2 de suas sessões.

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 e resultados vazios

Os dados de cinema não estão disponíveis para todos os países ou títulos. Planeje sua interface com isso em mente.

Situação	O que você vê	O que fazer
Sessões conhecidas	`results` tem um item por cinema	Mostre a lista
Nada conhecido para este país e título	`results` é um array vazio, `countries` lista onde há dados	Mostre uma nota neutra, não uma tabela vazia
Nenhum `country` enviado	`results` está vazio, `country` é `null`, `countries` traz contagens	Deixe o usuário escolher em `countries`
ID de filme desconhecido	404 com `status_code` 34	Verifique o ID
Acima do seu limite	429 com `status_code` 25	Aguarde os segundos indicados em `Retry-After`

Um array vazio não é um erro nem afirma que o filme está fora dos cinemas. Significa que nenhum dado de sessão é conhecido. Veja erros para o formato completo do corpo.

Monte uma página de programação dos lançamentos atuais

Combine dois endpoints. A lista diz quais filmes estão em cartaz, e os horários de sessões preenchem as sessões.

Passo	Requisição	Observações
1	`GET /3/movie/now_playing?region=US&page=1`	Até 20 filmes por página, com cache de 30 minutos
2	`GET /3/movie/{movie_id}/showtimes?country=US`	Uma chamada por filme, com cache de 30 minutos
3	Filtre no seu código	Por `city`, `formats` ou `tags`

Uma página de 20 filmes custa 21 requisições. A resposta de um grande lançamento pode ter várias centenas de quilobytes, porque traz até 1,500 sessões. No plano de 20 requisições por minuto isso consome um minuto inteiro de orçamento, então busque em uma tarefa em segundo plano e atenda os visitantes a partir da sua cópia armazenada. Os planos de 40 e 120 requisições por minuto comportam a mesma tarefa com folga. Veja limites de requisições para a janela e os cabeçalhos, e em alta e listas para os outros endpoints de lista.

Mantenha sua cópia atualizada

Os horários de sessões mudam de um dia para o outro, ao contrário dos detalhes do filme. Armazene cada resposta com o ID do filme, o país e a hora da busca. Um TTL de 30 minutos até algumas horas serve para a maioria das páginas de programação, e as sessões que já começaram podem ser ocultadas comparando start com a hora atual no timezone do cinema. Como start não tem deslocamento, não o converta para o fuso horário do visitante.

Como se compara

Recurso	Scraping de sites de cinemas	API de metadados sem horários de sessões	amodb
Configuração	Um scraper por site de cinema	Indisponível	Um endpoint, um formato JSON
Associação a um ID de filme	Associar pelo texto do título	Indisponível	ID do filme no caminho
Cobertura	O que você conseguir extrair	Nenhuma	Varia por país e título, array vazio quando desconhecida
Formatos e reservas	Analisar rótulos e links	Indisponível	Campos `formats`, `tags` e `booking_url`
Manutenção	Quebra quando um site muda	Nenhuma	Um formato JSON para todos os países

Preços

Os planos pré-pagos valem por 1, 3, 6, 12 ou 24 meses, com 0, 10, 20, 30 ou 40 por cento de desconto nos períodos mais longos. Nada renova automaticamente. Os planos permitem 20, 40 e 120 requisições por minuto, e cada um inclui os horários de sessões junto com todos os outros dados. Uma página de programação que atualiza a cada 30 minutos para alguns países cabe no menor limite. Não há plano gratuito. Escolha um plano em preços.

Perguntas e respostas

Como obtenho os horários de sessões de um filme?

Envie GET /3/movie/{movie_id}/showtimes?country=US com sua chave. O parâmetro country é um código de 2 letras, e region funciona como alias. A resposta lista os cinemas, e cada cinema traz suas sessões com horário de início, formatos, tags e link de reserva, quando conhecidos.

O que significa um array results vazio?

Significa que o amodb não tem dados de sessões desse filme nesse país. Não é um erro, e não diz que o filme está fora dos cinemas. O array countries na mesma resposta ainda lista onde há dados, então você pode oferecer outro país.

Quais países são cobertos?

A cobertura varia por país e por título. Toda resposta traz um array countries com a contagem de locais de exibição, cidades e sessões, até 60 países, com os de mais sessões primeiro. Leia esse array para cada filme em vez de fixar uma lista no código.

Posso listar os filmes que estão em cartaz agora?

Sim. GET /3/movie/now_playing com o parâmetro region lista os lançamentos atuais, com cache de 30 minutos. Pegue o ID de cada filme dessa lista e peça as sessões dele com o mesmo código de país.

Que fuso horário os valores de start usam?

Um valor de start tem o formato 2026-10-18T21:40 e não traz deslocamento UTC. Trate-o como a hora local no relógio do cinema. Cada local de exibição também tem um timezone como Europe/Moscow. Não converta start para o fuso horário do espectador.

Atualizado em 18 de out. de 2026

Ver em Markdown