# 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. ## 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](https://amodb.dev/pt/showtimes/) | 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 1. Abra [preços](https://amodb.dev/pt/pricing/) e escolha um plano. Os horários de sessões estão incluídos em todos os planos. 2. Crie uma chave no painel da sua conta. 3. 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. ```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}`); } } ``` 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](https://amodb.dev/pt/errors/) 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](https://amodb.dev/pt/rate-limits/) para a janela e os cabeçalhos, e [em alta e listas](https://amodb.dev/pt/trending-lists/) 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](https://amodb.dev/pt/pricing/). ## 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. ## Páginas relacionadas - [Horários de sessões de cinema](https://amodb.dev/pt/showtimes/): API de horários de sessões que retorna os locais de exibição e as sessões de um filme em um país, ou o resumo por país. Junte aos detalhes ou ao now_playing. - [Endpoints de em alta e de listas](https://amodb.dev/pt/trending-lists/): API de filmes em alta com caminhos do TMDB v3: rankings do dia e da semana, listas em cartaz, populares, mais bem avaliados e em breve. Cache de 30 minutos. - [API de detalhes de filmes](https://amodb.dev/pt/movies/): API de detalhes de filmes com caminhos e JSON do TMDB v3. Busque um filme por id e junte créditos, avaliações e moods com append_to_response, em 14 idiomas. - [Limites de requisições](https://amodb.dev/pt/rate-limits/): O amodb limita cada chave por requisições por minuto em uma janela de 60 segundos: 20, 40 ou 120 por plano. Leia os cabeçalhos e trate o 429 com Retry-After. - [Início rápido](https://amodb.dev/pt/quickstart/): Faça sua primeira chamada ao amodb: obtenha uma chave, peça um filme em curl, JavaScript, Python, PHP ou Go e carregue o pôster. Menos de 2 minutos. Atualizado: 2026-10-18. Source: https://amodb.dev/pt/cinema-showtimes-api/