Habilidade de API CheapCharts
Um rastreador de preços de API pública e gratuita para filmes e séries digitais em iTunes (Apple TV), Amazon Prime Video, Vudu e Google Play. Sem autenticação, sem limites de taxa. Chamadas paralelas são seguras - o script
deals.pyusa 8 workers concorrentes de DetailData.
Repositório: https://github.com/tracerman/cheapcharts-skill
URL Base da API: https://buster.cheapcharts.de/v1/gptapi/
Verificação de preço mínimo histórico (ATL): https://buster.cheapcharts.de/v1/DetailData.php (endpoint interno não oficial - veja a Armadilha nº 17)
Workflow Padrão (padrão canônico)
Quando um usuário perguntar sobre ofertas, quedas de preço, preços ou "o que está barato agora", siga este fluxo:
- Decida a loja. O padrão é
itunes(EUA), ou useitunes,amazon,vudu,googlePlaypara várias lojas. - Decida o tipo de item.
buymoviespara filmes,seasonspara séries,allapenas para Pesquisa. - Obtenha Ofertas com
sort=latestPricechangepara perguntas sobre "últimas" / "quedas de hoje" / "o que mudou agora". Usesort=greatestSavingspara "melhores ofertas" ousort=releaseDatepara "lançamentos mais recentes". - Verifique as afirmações de "hoje" acessando DetailData para cada candidato e verificando
priceHdLastChangeDate(oupriceSdLastChangeDate). Sempre verifique o campostatusda resposta primeiro -status=errorsignifica que sua chamada falhou silenciosamente (veja a Armadilha nº 15). - Filtre quedas falsas (
priceBefore - price <= $1) e datas de placeholder de pacotes ao ordenar porreleaseDate. - Enriqueça com a flag de ATL (
priceHdIsLowest/priceSdIsLowest) do DetailData para que cada relatório possa mostrar se aquela queda está no piso histórico. O CheapCharts faz uma chamada extra por item - veja o modelo de relatório padrão nas Diretrizes de Apresentação.
A receita completa de "quedas de hoje" com verificação em Python está na seção de Workflow Recipes.
Quando Usar
- Usuário pergunta sobre preços de filmes/séries em lojas digitais
- Usuário quer encontrar ofertas ou descontos em filmes digitais
- Usuário quer navegar pelos rankings (o que é popular/está em alta)
- Usuário quer recomendações em um gênero
- Usuário quer comparar preços entre lojas (iTunes, Amazon, Vudu, Google Play)
- Usuário quer verificar histórico de preços ou menor preço histórico
- Usuário menciona CheapCharts diretamente
Não use para: Mídia física (Blu-ray/DVD), catálogos de streaming por assinatura (Netflix/Disney+), críticas/ resenhas de filmes (use pesquisa na web).
Guia de Decisão Rápida
| Usuário diz... | Use endpoint | Por quê |
|---|---|---|
| "Últimas ofertas" / "quedas de hoje" / "o que mudou agora" | Deals + DetailData | Workflow padrão: sort=latestPricechange, então verifique se priceHdLastChangeDate de cada item corresponde a hoje (veja Receita: "Quedas de preço de hoje") |
| "Encontre ofertas abaixo de $X" | Deals | Filtre por maxPrice + sort=greatestSavings |
| "Melhores ofertas bem avaliadas" / "aclamação crítica abaixo de $X" | Deals | Filtre por imdbRating + maxPrice (ambos filtros no servidor, veja Receita) |
| "Filmes 4K / Dolby Vision / Atmos" | Deals + filtro cliente | O filtro has4K=1 no servidor não funciona (Armadilha nº 16) - busque e filtre no lado do cliente |
| "Lançamentos mais recentes em promoção" | Deals | sort=releaseDate + filtro de placeholder de pacotes (veja Armadilha nº 12) |
| "O que está popular agora" / "o que está vendendo" | Charts ou Topseller | Charts para uma loja, Topseller para várias lojas |
| "Quanto custa [título]" | Search então Prices | Pesquise para obter imdbId, depois Prices em várias lojas (Armadilha nº 19: iTunes = Apple TV) |
| "Melhores ofertas de séries completas" | Deals (seasons) | Filtre isBundle=1 no lado do cliente (Receita) |
| "Me recomende um filme de [gênero]" | Recommendations | Passe um gênero específico + imdbRating (Armadilha nº 18: sem gênero, retorna dados dos rankings) |
| "O que está vendendo mais" | Topseller | Mais vendidos em várias lojas |
| "Pesquise por [título]" | Search | Pesquisa por título, retorna metadados |
| "[Título] está no menor preço histórico?" / "ofertas no ATL" / "menor preço de todos os tempos" | Deals + DetailData | DetailData expõe as flags priceHdIsLowest / priceSdIsLowest - não precisa analisar priceHdEvolution (veja Receita: "Ofertas de menor preço histórico (ATL)"). Use priceHdEvolution apenas se precisar do valor histórico baixo real em dólares ou a data de mudança do ATL anterior. |
| "O que acabou de sair de uma promoção?" / "próximos alvos de queda" | DetailData em um conjunto candidato | priceBefore < price significa que a mudança mais recente do título foi um aumento de preço - a promoção acabou de terminar. Estas são as quedas de maior probabilidade a curto prazo e devem ser relatadas junto com ofertas ativas, não filtradas silenciosamente. Veja Armadilha nº 31. |
Endpoints da API
Parâmetros comuns: Charts, Deals, Prices e Recommendations compartilham parâmetros comuns (
action,store,country,itemType,imdbRating,rottenTomatoesRating). Search e Topseller têm seus próprios conjuntos de parâmetros (veja suas seções abaixo).
1. Search - Search.php
Encontre itens por título. Use este PRIMEIRO quando você tiver apenas um título e precisar do ID IMDb.
Obrigatório: action=search, query=<título> (ou searchTerm=<título> - alias, conforme llms.txt do fornecedor)
Opcional: store=itunes (padrão), country=us (padrão), itemType=all (padrão), limit=20 (padrão 20, máximo 20), offset=0 (deslocamento de paginação para resultados além do limite)
(veja RECIPES.md)
Retorna uma lista plana: {"status":"success","results":[...itens...]}. Cada item inclui imdbId (se disponível), mediaType, itemType, priceFollowUpItemType, store, country, cheapChartsProductPageUrl, title, artist, releaseDate, releaseYear, currency, price, currentPrice, has4K, hdrFormat, imdbRating, rottenTomatoesRating (veja a tabela de Campos Comuns de Itens para detalhes completos).
2. Charts - Charts.php
Rankings atuais dos rankings para filmes ou temporadas de séries.
Obrigatório: action=getCharts, store, country, itemType (buymovies ou seasons)
Opcional: genre=All, quality=hd4k, limit, imdbRating (mín.), rottenTomatoesRating (mín.), releaseYear (ex.: 2025-2025)
(veja RECIPES.md)
Retorna: {"status":"success","results":{"buymovies":[...]}}. Itens incluem o campo rank.
3. Deals - Deals.php
Ofertas atuais e quedas de preço. Melhor para caça a pechinchas.
Obrigatório: action=getDeals, store, country, itemType (buymovies ou seasons)
Opcional: genre=All, quality=hd4k, sort=latestPricechange, maxPrice, releaseYear (formato: 2020-2025 - um ano único como 2026-2026 também funciona; padrão: todos os anos), limit, imdbRating (avaliação mín. 0-10, padrão 0 = sem filtro, ex.: imdbRating=7), rottenTomatoesRating (pontuação mín. 0-100, padrão 0 = sem filtro, ex.: rottenTomatoesRating=80), has4K=1 (NÃO FUNCIONA - ignorado, filtre no lado do cliente)
Opções de ordenação: latestPricechange (padrão), price, greatestSavings, greatestPercentageSavings, popularity, alphabetical, releaseDate (apenas ascendente - veja Armadilha nº 11)
Filtro de data: releaseYear=AAAA-AAAA aceita tanto ano único (2026-2026) quanto intervalos (2024-2026). Funciona nos endpoints Deals e Charts. NÃO suportado em Recommendations, Prices, ou Search.
(veja RECIPES.md)
Retorna: {"status":"success","results":{"buymovies":[...]}}. Itens incluem price, priceBefore, imdbRating, rottenTomatoesRating.
4. Prices - Prices.php
Consulte preços atuais para títulos específicos por ID IMDb.
Obrigatório: action=getPrices, store, country, itemType=buymovies, imdbIDs (nota: o llms.txt Parâmetros Comuns lista seasons como válido para Prices, mas a tabela de parâmetros específica de Prices e testes empíricos confirmam que apenas buymovies funciona - veja Armadilha nº 7) (separados por vírgula, ex.: tt0468569,tt2911666)
(veja RECIPES.md)
Retorna: {"status":"success","results":{"buymovies":[...]}}. Mesmo formato de item que Deals.
5. Recommendations - Recommendations.php
Recomendações curadas, filtradas por gênero e qualidade.
Obrigatório: action=getRecommendations, store, country, itemType (buymovies ou seasons)
Opcional: genre=All, quality=hd4k, limit, imdbRating, rottenTomatoesRating
Nota: llms.txt lista imdbRating/rottenTomatoesRating como suportados aqui, mas testes empíricos mostram que eles são silenciosamente ignorados em Recommendations (Armadilha nº 23). Use Deals com sort=greatestSavings + filtros de avaliação.
(veja RECIPES.md)
Retorna: {"status":"success","results":{"buymovies":[...]}}. Itens podem incluir o campo description.
6. Topseller - Topseller.php
Mais vendidos em várias lojas. NÃO requer itemType, imdbRating ou rottenTomatoesRating (ao contrário de outros endpoints).
Obrigatório: action=getTopsellerForStartpage, country, store (separado por vírgula, ex.: itunes,amazon,vudu,googlePlay)
Opcional: maxItemCount=5 (padrão 5, por loja por categoria)
(veja RECIPES.md)
Retorna: {"status":"success","results":{"itunes":{"muviess":[...],"seasons":[...]},"amazon":{...}}}. Agrupado por loja e depois por filmes/temporadas. A disponibilidade de campos varia por loja - has4K, hasAtmos, hdrFormat, isMovieBundle aparecem apenas para itens do iTunes (veja Armadilha nº 3).
7. DetailData (Interno) - DetailData.php
Não está na documentação oficial do gptapi. Descoberto ao inspecionar as chamadas de rede do site CheapCharts. Retorna detalhes completos do item incluindo preços atuais, histórico completo de preços e temporadas filhas (para pacotes). Funciona tanto para filmes quanto para temporadas. Esta é a maneira confiável de obter preços de temporadas/pacotes sem um navegador.
Obrigatório: store, country, itemType (movies ou seasons - NÃO buymovies), idInStore (o ID da loja iTunes dos resultados da Pesquisa)
(veja RECIPES.md)
Retorna: {"results":{"seasons":{...}}} (a chave corresponde ao itemType que você passou).
Campos principais (temporadas):
| Campo | Descrição |
|---|---|
priceSd / priceHd | Preço SD/HD atual |
priceSdBefore / priceHdBefore | Preço anterior antes da última mudança |
priceSdLastChangeDate / priceHdLastChangeDate | Data da última mudança de preço |
priceSdEvolution / priceHdEvolution | Histórico completo de preços como string data:+/-preço~data:+/-preço~.... + = preço subiu, - = preço desceu. Veja "Analisando priceHdEvolution" abaixo - a convenção de delta não é confiável para reconstruir preços absolutos; prefira a flag IsLowest. |
priceSdIsLowest / priceHdIsLowest | 1 se o preço SD/HD atual for igual ao menor preço histórico no rastreamento do CheapCharts para este título, senão 0. Esta é a verificação ATL canônica - use-a em vez de analisar priceHdEvolution. |
priceSdIsBest / priceHdIsBest | 1 se o preço SD/HD atual for igual ao melhor (menor) preço dentro da janela de promoção atual (ou seja,piso da promoção atual), senão 0. Diferente de IsLowest - IsBest=1, IsLowest=0 significa "menor desta promoção, mas houve uma promoção anterior ainda menor." |
priceSdDropIndicator / priceHdDropIndicator | 1 se o preço subiu na última mudança, -1 se caiu, 0 se não mudou. Útil para filtrar "quedas reais" sem comparar com priceBefore. |
isBundle / isSeasonBundle | Se é um pacote de temporadas |
isSeasonComplete | Se todas as temporadas estão incluídas |
childSeasonsCount | Número de temporadas filhas no pacote |
bundleSavings / bundleSavingsHd | Economia em relação a comprar temporadas individualmente a preço normal |
saveOpportunity / saveOpportunityHd | Mesmo que bundleSavings |
episodeCount | Total de episódios |
advisoryRating | Classificação indicativa (ex.: TV-14) |
summary | Sinopse completa |
seasonFamily | Array de temporadas filhas, cada uma com idInStore, title, priceSd, priceHd, priceSdEvolution, priceHdEvolution, cheapChartsProductPageUrl |
productPageUrl | URL direta da loja Apple TV / iTunes |
iTunesUrl | URL do iTunes |
imageSmallUrl / imageMediumUrl / imageLargeUrl | URLs das artes de capa |
appleTvId | ID interno do Apple TV |
Analisando priceHdEvolution (baixa prioridade - prefira priceHdIsLowest): Divida por ~, cada segmento é YYYY-MM-DD:[+/-]preço. O último segmento (mais à direita) é o preço histórico mais antigo; o primeiro segmento é a mudança de preço mais recente. Exemplo:
2026-05-20:+89.99~2026-05-12:-69.99~2026-04-01:-49.99~2022-02-09:89.99
Ressalva: a convenção de delta é inconsistente entre títulos - para alguns, o último segmento é um preço inicial absoluto (2022-02-09:89.99 sem sinal); para outros, os deltas não se acumulam de forma limpa para o preço atual. Empiricamente, percorrer os deltas do segmento mais antigo NÃO reproduz sempre priceHd/priceSd. Para detecção de ATL, use as flags priceHdIsLowest / priceSdIsLowest - elas são autoritativas. Use a análise de priceHdEvolution apenas se precisar do valor absoluto em dólares do mínimo histórico ou da data em que ocorreu, e valide o resultado com priceHd antes de confiar.
Valores de Enumeração
Loja
| Valor | Países Suportados |
|---|---|
itunes | us, de, gb, fr, au, ca, at, ch, es, pt, ru, jp, tr, pl, in, cn |
amazon | us, de |
vudu | us |
googlePlay | us |
Padrão para itunes se o usuário não especificar uma loja - tem o suporte de país mais amplo.
Tipo de Item
| Valor | Significado | Usado por |
|---|---|---|
buymovies | Filmes (preços de compra) | Charts, Deals, Prices, Recommendations |
rentalmovies | Filmes (preços de aluguel, ~30 dias para começar, 48h para terminar) | Charts, Deals, Prices (de acordo com o llms.txt oficial) |
seasons | Temporadas de séries | Charts, Deals, Recommendations, DetailData |
movies | Apenas metadados de filmes | Apenas Search |
seasons | Apenas metadados de temporadas | Apenas Search |
all | Todos os tipos de mídia (filmes, temporadas, ebooks, audiolivros, álbuns) | Apenas Search |
Compra vs aluguel (descoberto empiricamente, NÃO no llms.txt atual): O parâmetro itemType do endpoint Prices aceita buymovies (preço de compra) ou rentalmovies (preço de aluguel). Aluguéis normalmente têm 30 dias para começar a assistir e 48 horas para terminar depois de iniciados. O endpoint Search pode retornar qualquer um dos tipos - o campo priceFollowUpItemType informa qual usar na sequência.