Habilidad de la API de CheapCharts
Un rastreador de precios gratuito y de API pública para películas y programas de TV digitales en iTunes (Apple TV), Amazon Prime Video, Vudu y Google Play. Sin autenticación, sin límites de velocidad. Las llamadas en paralelo son seguras: el script
deals.pyutiliza 8 trabajadores concurrentes de DetailData.
Repositorio: https://github.com/tracerman/cheapcharts-skill
URL Base de la API: https://buster.cheapcharts.de/v1/gptapi/
Verificación de precio mínimo histórico (ATL): https://buster.cheapcharts.de/v1/DetailData.php (endpoint interno no oficial - ver Escollo #17)
Flujo de Trabajo Predeterminado (patrón canónico)
Cuando un usuario pregunte sobre ofertas, bajadas de precio, precios o "qué está barato ahora", sigue este flujo:
- Decide la tienda. Por defecto
itunes(EE.UU.), o usaitunes,amazon,vudu,googlePlaypara múltiples tiendas. - Decide el tipo de artículo.
buymoviespara películas,seasonspara TV,allsolo para Búsqueda. - Obtén Ofertas con
sort=latestPricechangepara preguntas sobre "lo último" / "bajadas de hoy" / "qué acaba de cambiar". Usasort=greatestSavingspara "mejores ofertas" osort=releaseDatepara "novedades recién lanzadas". - Verifica las afirmaciones de "hoy" consultando DetailData para cada candidato y comprobando
priceHdLastChangeDate(opriceSdLastChangeDate). Revisa siempre primero el campo destatusde la respuesta -status=errorsignifica que tu llamada falló silenciosamente (ver Escollo #15). - Filtra bajadas falsas (
priceBefore - price <= $1) y fechas de paquete de relleno al ordenar porreleaseDate. - Enriquece con la bandera ATL (
priceHdIsLowest/priceSdIsLowest) de DetailData para que cada informe pueda mostrar si la bajada está en el mínimo histórico. CheapCharts realiza una llamada extra por artículo; consulta la plantilla de informe estándar en Pautas de Presentación.
La receta completa de "bajadas de hoy" con verificación en Python está en la sección Recetas de Flujo de Trabajo.
Cuándo Usar
- El usuario pregunta sobre precios de películas/programas de TV en tiendas digitales
- El usuario quiere encontrar ofertas o descuentos en películas digitales
- El usuario quiere explorar listas (qué es popular/tendencia)
- El usuario quiere recomendaciones en un género
- El usuario quiere comparar precios entre tiendas (iTunes, Amazon, Vudu, Google Play)
- El usuario quiere consultar el historial de precios o el precio mínimo histórico
- El usuario menciona CheapCharts directamente
No usar para: Medios físicos (Blu-ray/DVD), catálogos de suscripción de streaming (Netflix/Disney+), reseñas/críticas de películas (usar búsqueda web en su lugar).
Guía Rápida de Decisión
| El usuario dice... | Usa el endpoint | Por qué |
|---|---|---|
| "Últimas ofertas" / "bajadas de hoy" / "qué acaba de cambiar" | Deals + DetailData | Flujo predeterminado: sort=latestPricechange, luego verifica que cada artículo priceHdLastChangeDate coincida con hoy (ver Receta: "Bajadas de precio de hoy") |
| "Encuentra ofertas por menos de $X" | Deals | Filtra por maxPrice + sort=greatestSavings |
| "Mejores ofertas con buenas calificaciones" / "aclamadas por la crítica por menos de $X" | Deals | Filtra por imdbRating + maxPrice (ambos filtros del lado del servidor, ver Receta) |
| "Películas 4K / Dolby Vision / Atmos" | Deals + filtro del cliente | El filtro del servidor has4K=1 no funciona (Escollo #16) - obtener y filtrar del lado del cliente |
| "Novedades en oferta" | Deals | sort=releaseDate + filtro de fechas de paquete de relleno (ver Escollo #12) |
| "Qué es popular ahora mismo" / "qué se vende más" | Charts o Topseller | Charts para una tienda, Topseller para múltiples tiendas |
| "Cuánto cuesta [título]" | Search luego Prices | Search para obtener imdbId, luego Prices en todas las tiendas (Escollo #19: iTunes = Apple TV) |
| "Mejores ofertas de series completas" | Deals (seasons) | Filtra isBundle=1 del lado del cliente (Receta) |
| "Recomiéndame una película de [género]" | Recommendations | Pasa un género específico + imdbRating (Escollo #18: sin género, devuelve datos de lista) |
| "Qué se vende más" | Topseller | Más vendidos en múltiples tiendas |
| "Busca [título]" | Search | Búsqueda por título, devuelve metadatos |
| "Está [título] en su precio mínimo histórico?" / "ofertas en ATL" / "precio más bajo de la historia" | Deals + DetailData | DetailData expone las banderas priceHdIsLowest / priceSdIsLowest - no necesita analizar priceHdEvolution (ver Receta: "Ofertas de precio mínimo histórico (ATL)"). Usa priceHdEvolution solo si necesitas el monto en dólares del mínimo histórico real o la fecha de cambio del ATL anterior. |
| "Qué acaba de salir de oferta?" / "próximos objetivos de bajada" | DetailData en un conjunto candidato | priceBefore < price significa que el cambio más reciente del título fue un aumento de precio - la oferta acaba de terminar. Estos son tus objetivos de bajada a corto plazo de mayor probabilidad y deben informarse junto con las ofertas activas, no filtrarse silenciosamente. Ver Escollo #31. |
Endpoints de la API
Parámetros comunes: Charts, Deals, Prices y Recommendations comparten parámetros comunes (
action,store,country,itemType,imdbRating,rottenTomatoesRating). Search y Topseller tienen sus propios conjuntos de parámetros (ver sus secciones a continuación).
1. Search - Search.php
Busca artículos por título. USA ESTE PRIMERO cuando solo tengas un título y necesites el ID de IMDb.
Requerido: action=search, query=<título> (o searchTerm=<título> - alias, según llms.txt del proveedor)
Opcional: store=itunes (por defecto), country=us (por defecto), itemType=all (por defecto), limit=20 (por defecto 20, máximo 20), offset=0 (desplazamiento de paginación para resultados más allá del límite)
(ver RECIPES.md)
Devuelve una lista plana: {"status":"success","results":[...items...]}. Cada artículo incluye imdbId (si está disponible), mediaType, itemType, priceFollowUpItemType, store, country, cheapChartsProductPageUrl, title, artist, releaseDate, releaseYear, currency, price, currentPrice, has4K, hdrFormat, imdbRating, rottenTomatoesRating (ver tabla de Campos Comunes de Artículos para todos los detalles).
2. Charts - Charts.php
Clasificaciones actuales de listas para películas o temporadas de TV.
Requerido: action=getCharts, store, country, itemType (buymovies o seasons)
Opcional: genre=All, quality=hd4k, limit, imdbRating (mín.), rottenTomatoesRating (mín.), releaseYear (ej. 2025-2025)
(ver RECIPES.md)
Devuelve: {"status":"success","results":{"buymovies":[...]}}. Los artículos incluyen el campo rank.
3. Deals - Deals.php
Ofertas actuales y bajadas de precio. Ideal para buscar gangas.
Requerido: action=getDeals, store, country, itemType (buymovies o seasons)
Opcional: genre=All, quality=hd4k, sort=latestPricechange, maxPrice, releaseYear (formato: 2020-2025 - un año individual como 2026-2026 también funciona; por defecto: todos los años), limit, imdbRating (calificación mín. 0-10, por defecto 0 = sin filtro, ej. imdbRating=7), rottenTomatoesRating (puntuación mín. 0-100, por defecto 0 = sin filtro, ej. rottenTomatoesRating=80), has4K=1 (NO FUNCIONA - ignorado, filtrar del lado del cliente en su lugar)
Opciones de ordenación: latestPricechange (por defecto), price, greatestSavings, greatestPercentageSavings, popularity, alphabetical, releaseDate (solo ascendente - ver Escollo #11)
Filtro de fecha: releaseYear=YYYY-YYYY acepta tanto año individual (2026-2026) como rangos (2024-2026). Funciona en los endpoints Deals y Charts. NO es compatible con Recommendations, Prices ni Search.
(ver RECIPES.md)
Devuelve: {"status":"success","results":{"buymovies":[...]}}. Los artículos incluyen price, priceBefore, imdbRating, rottenTomatoesRating.
4. Prices - Prices.php
Consulta los precios actuales de títulos específicos por ID de IMDb.
Requerido: action=getPrices, store, country, itemType=buymovies, imdbIDs (nota: la tabla de Parámetros Comunes de llms.txt enumera seasons como válido para Prices, pero la tabla de parámetros específica de Prices y las pruebas empíricas confirman que solo funciona buymovies - ver Escollo #7) (separados por comas, ej. tt0468569,tt2911666)
(ver RECIPES.md)
Devuelve: {"status":"success","results":{"buymovies":[...]}}. Misma forma de artículo que Deals.
5. Recommendations - Recommendations.php
Recomendaciones curadas, filtradas por género y calidad.
Requerido: action=getRecommendations, store, country, itemType (buymovies o seasons)
Opcional: genre=All, quality=hd4k, limit, imdbRating, rottenTomatoesRating
Nota: llms.txt enumera imdbRating/rottenTomatoesRating como compatibles aquí, pero las pruebas empíricas muestran que se ignoran silenciosamente en Recommendations (Escollo #23). Usa Deals con sort=greatestSavings + filtros de calificación en su lugar.
(ver RECIPES.md)
Devuelve: {"status":"success","results":{"buymovies":[...]}}. Los artículos pueden incluir el campo description.
6. Topseller - Topseller.php
Artículos más vendidos en múltiples tiendas. NO requiere itemType, imdbRating ni rottenTomatoesRating (a diferencia de otros endpoints).
Requerido: action=getTopsellerForStartpage, country, store (separados por comas, ej. itunes,amazon,vudu,googlePlay)
Opcional: maxItemCount=5 (por defecto 5, por tienda por categoría)
(ver RECIPES.md)
Devuelve: {"status":"success","results":{"itunes":{"movies":[...],"seasons":[...]},"amazon":{...}}}. Agrupado por tienda, luego por películas/temporadas. La disponibilidad de campos varía según la tienda - has4K, hasAtmos, hdrFormat, isMovieBundle solo aparecen para artículos de iTunes (ver Escollo #3).
7. DetailData (Interno) - DetailData.php
No está en los documentos oficiales de gptapi. Descubierto al inspeccionar las llamadas de red del sitio web de CheapCharts. Devuelve detalles completos del artículo, incluidos precios actuales, historial completo de precios y temporadas secundarias (para paquetes). Funciona tanto para películas como para temporadas. Esta es la forma confiable de obtener precios de temporada/paquete sin un navegador.
Requerido: store, country, itemType (movies o seasons - NO buymovies), idInStore (el ID de la tienda iTunes de los resultados de Search)
(ver RECIPES.md)
Devuelve: {"results":{"seasons":{...}}} (la clave coincide con el itemType que pasaste).
Campos clave (temporadas):
| Campo | Descripción |
|---|---|
priceSd / priceHd | Precio actual SD/HD |
priceSdBefore / priceHdBefore | Precio anterior antes del último cambio |
priceSdLastChangeDate / priceHdLastChangeDate | Fecha del último cambio de precio |
priceSdEvolution / priceHdEvolution | Historial completo de precios como cadena fecha:+/-precio~fecha:+/-precio~.... + = el precio subió, - = el precio bajó. Ver "Analizando priceHdEvolution" a continuación: la convención delta no es confiable para reconstruir precios absolutos; prefiere la bandera IsLowest. |
priceSdIsLowest / priceHdIsLowest | 1 si el precio actual SD/HD es igual al mínimo histórico en todo el historial rastreado por CheapCharts para este título, de lo contrario 0. Esta es la comprobación ATL canónica - úsala en lugar de analizar priceHdEvolution. |
priceSdIsBest / priceHdIsBest | 1 si el precio actual SD/HD es igual al mejor (más bajo) precio dentro de la ventana de oferta actual (es decir, el piso de la oferta en curso), de lo contrario 0. Distinto de IsLowest - IsBest=1, IsLowest=0 significa "el más bajo de ESTA oferta pero una oferta anterior fue más baja." |
priceSdDropIndicator / priceHdDropIndicator | 1 si el precio subió en el último cambio, -1 si bajó, 0 si no cambió. Útil para filtrar "bajadas reales" sin comparar con priceBefore. |
isBundle / isSeasonBundle | Si es un paquete de temporada |
isSeasonComplete | Si todas las temporadas están incluidas |
childSeasonsCount | Número de temporadas secundarias en el paquete |
bundleSavings / bundleSavingsHd | Ahorro vs comprar temporadas individualmente a precio regular |
saveOpportunity / saveOpportunityHd | Igual que bundleSavings |
episodeCount | Total de episodios |
advisoryRating | Clasificación de contenido (ej. TV-14) |
summary | Sinopsis completa |
seasonFamily | Matriz de temporadas secundarias, cada una con idInStore, title, priceSd, priceHd, priceSdEvolution, priceHdEvolution, cheapChartsProductPageUrl |
productPageUrl | URL directa de Apple TV / iTunes |
iTunesUrl | URL de iTunes |
imageSmallUrl / imageMediumUrl / imageLargeUrl | URL de carátulas |
appleTvId | ID interno de Apple TV |
Analizando priceHdEvolution (baja prioridad - prefiere priceHdIsLowest): Dividir por ~, cada segmento es YYYY-MM-DD:[+/-]precio. El último segmento (más a la derecha) es el precio histórico más antiguo; el primer segmento es el cambio de precio más reciente. Ejemplo:
2026-05-20:+89.99~2026-05-12:-69.99~2026-04-01:-49.99~2022-02-09:89.99
Advertencia: la convención delta es inconsistente entre títulos - para algunos, el último segmento es un precio inicial absoluto (2022-02-09:89.99 sin signo); para otros, los deltas no se acumulan limpiamente al precio actual. Empíricamente, recorrer los deltas desde el segmento más antiguo NO siempre reproduce priceHd/priceSd. Para la detección de ATL, usa las banderas priceHdIsLowest / priceSdIsLowest en su lugar: son autoritativas. Recurre a analizar priceHdEvolution solo si necesitas el monto absoluto en dólares del mínimo histórico o la fecha en que ocurrió, y valida el resultado contra priceHd antes de confiar en él.
Valores de Enumeración
Tienda
| Valor | Países compatibles |
|---|---|
itunes | us, de, gb, fr, au, ca, at, ch, es, pt, ru, jp, tr, pl, in, cn |
amazon | us, de |
vudu | us |
googlePlay | us |
Por defecto itunes si el usuario no especifica una tienda: tiene el soporte de país más amplio.
ItemType
| Valor | Significado | Usado por |
|---|---|---|
buymovies | Películas (precios de compra) | Charts, Deals, Prices, Recommendations |
rentalmovies | Películas (precios de alquiler, ~30 días para comenzar, 48h para terminar) | Charts, Deals, Prices (según llms.txt oficial) |
seasons | Temporadas de programas de TV | Charts, Deals, Recommendations, DetailData |
movies | Solo metadatos de películas | Solo Search |
seasons | Solo metadatos de temporadas | Solo Search |
all | Todos los tipos de contenido (películas, temporadas, libros electrónicos, audiolibros, álbumes) | Solo Search |
Compra vs alquiler (descubierto empíricamente, NO en llms.txt actual): El parámetro itemType del endpoint Prices acepta buymovies (precio de compra) o rentalmovies (precio de alquiler). Los alquileres suelen tener 30 días para comenzar a ver y 48 horas para terminar una vez comenzados. El endpoint Search puede devolver cualquiera de los dos tipos: el campo priceFollowUpItemType te indica cuál usar en la consulta de seguimiento de Prices. Para fines de ofertas, concéntrate en buymovies a menos que se solicite explícitamente lo contrario.