Compétence API CheapCharts
Un tracker de prix public gratuit pour les films et séries numériques sur iTunes (Apple TV), Amazon Prime Video, Vudu et Google Play. Pas d'authentification, pas de limites de débit. Les appels parallèles sont sûrs - le script
deals.pyutilise 8 workers DetailData simultanés.
Dépôt : https://github.com/tracerman/cheapcharts-skill
URL de base de l'API : https://buster.cheapcharts.de/v1/gptapi/
Vérification du prix le plus bas historique (ATL) : https://buster.cheapcharts.de/v1/DetailData.php (endpoint interne non officiel - voir Piège #17)
Workflow par défaut (schéma canonique)
Lorsqu'un utilisateur pose une question sur des offres, des baisses, des prix, ou "ce qui est bon marché maintenant", suivez ce flux :
- Décider la boutique. Par défaut, utilisez
itunes(US), ouitunes,amazon,vudu,googlePlaypour plusieurs boutiques. - Décider le type d'article.
buymoviespour les films,seasonspour la TV,allpour la recherche uniquement. - Récupérer les offres avec
sort=latestPricechangepour les questions "dernières offres" / "baisses du jour" / "ce qui vient de changer". Utilisezsort=greatestSavingspour "meilleures offres" ousort=releaseDatepour "nouveautés". - Vérifier les affirmations de baisse "aujourd'hui" en interrogeant DetailData pour chaque candidat et en vérifiant
priceHdLastChangeDate(oupriceSdLastChangeDate). Vérifiez toujours d'abord le champstatusde la réponse -status=errorsignifie que votre appel a échoué silencieusement (voir Piège #15). - Filtrer les fausses baisses (
priceBefore - price <= $1) et les dates de bundle factices lors du tri parreleaseDate. - Enrichir avec le drapeau ATL (
priceHdIsLowest/priceSdIsLowest) de DetailData pour que chaque rapport puisse indiquer si chaque baisse est au plancher historique. CheapCharts effectue un appel supplémentaire par article - voir le modèle de rapport standard dans les Directives de Présentation.
La recette complète des "baisses du jour" avec vérification Python se trouve dans la section Recettes de Workflow.
Quand l'utiliser
- L'utilisateur pose des questions sur les prix de films/séries sur les boutiques numériques
- L'utilisateur veut trouver des offres ou des réductions sur des films numériques
- L'utilisateur veut parcourir les classements (ce qui est populaire/tendance)
- L'utilisateur veut des recommandations dans un genre
- L'utilisateur veut comparer les prix entre boutiques (iTunes, Amazon, Vudu, Google Play)
- L'utilisateur veut vérifier l'historique des prix ou le prix historique le plus bas
- L'utilisateur mentionne directement CheapCharts
Ne pas utiliser pour : Supports physiques (Blu-ray/DVD), catalogues d'abonnement de streaming (Netflix/Disney+), critiques/analyses de films (utiliser plutôt une recherche web).
Guide de décision rapide
| L'utilisateur dit... | Utiliser l'endpoint | Pourquoi |
|---|---|---|
| "Dernières offres" / "baisses du jour" / "ce qui vient de changer" | Offres + DetailData | Workflow par défaut : sort=latestPricechange, puis vérifier que le priceHdLastChangeDate de chaque article correspond à aujourd'hui (voir Recette : "Baisses de prix du jour") |
| "Trouver des offres sous X€" | Offres | Filtrer par maxPrice + sort=greatestSavings |
| "Meilleures offres bien notées" / "acclamées par la critique sous X€" | Offres | Filtrer par imdbRating + maxPrice (filtres côté serveur, voir Recette) |
| "Films 4K / Dolby Vision / Atmos" | Offres + filtre client | Le filtre serveur has4K=1 ne fonctionne pas (Piège #16) - récupérez puis filtrez côté client |
| "Nouveautés en solde" | Offres | sort=releaseDate + filtre des bundles factices (voir Piège #12) |
| "Qu'est-ce qui est populaire maintenant" / "qu'est-ce qui se vend" | Classements ou Topseller | Classements pour une boutique, Topseller pour multi-boutique |
| "Combien coûte [titre]" | Recherche puis Prix | Recherche pour obtenir l'imdbId, puis Prix sur les boutiques (Piège #19 : iTunes = Apple TV) |
| "Meilleures offres de séries complètes" | Offres (saisons) | Filtrer isBundle=1 côté client (Recette) |
| "Recommande-moi un film [genre]" | Recommandations | Passer un genre spécifique + imdbRating (Piège #18 : sans genre, renvoie les données de classement) |
| "Qu'est-ce qui se vend le plus" | Topseller | Meilleures ventes multi-boutiques |
| "Rechercher [titre]" | Recherche | Recherche par titre, renvoie les métadonnées |
| "[Titre] est-il à son prix le plus bas historique ?" / "offres au plus bas historique" / "prix le plus bas jamais vu" | Offres + DetailData | DetailData expose les drapeaux priceHdIsLowest / priceSdIsLowest - pas besoin d'analyser priceHdEvolution (voir Recette : "Offres au plus bas historique (ATL)"). N'utilisez priceHdEvolution que si vous avez besoin du montant réel du plus bas historique ou de la date de changement de l'ATL précédent. |
| "Qu'est-ce qui vient de sortir d'une promotion ?" / "prochaines cibles de baisse" | DetailData sur un ensemble de candidats | priceBefore < price signifie que le changement le plus récent du titre était une augmentation de prix - la promotion vient de se terminer. Ce sont vos baisses à court terme les plus probables et doivent être signalées aux côtés des offres actives, pas filtrées silencieusement. Voir Piège #31. |
Endpoints API
Paramètres communs : Les endpoints Classements, Offres, Prix et Recommandations partagent des paramètres communs (
action,store,country,itemType,imdbRating,rottenTomatoesRating). La Recherche et Topseller ont leurs propres ensembles de paramètres (voir leurs sections ci-dessous).
1. Recherche - Search.php
Trouver des articles par titre. Utilisez-le EN PREMIER lorsque vous n'avez qu'un titre et avez besoin de l'ID IMDb.
Requis : action=search, query=<titre> (ou searchTerm=<titre> - alias, selon le llms.txt du fournisseur)
Optionnel : store=itunes (défaut), country=us (défaut), itemType=all (défaut), limit=20 (défaut 20, max 20), offset=0 (décalage de pagination pour les résultats au-delà de la limite)
(voir RECIPES.md)
Renvoie une liste plate : {"status":"success","results":[...articles...]}. Chaque article inclut imdbId (si disponible), mediaType, itemType, priceFollowUpItemType, store, country, cheapChartsProductPageUrl, title, artist, releaseDate, releaseYear, currency, price, currentPrice, has4K, hdrFormat, imdbRating, rottenTomatoesRating (voir le tableau des Champs Communs des Articles pour les détails complets).
2. Classements - Charts.php
Classements actuels des films ou saisons de séries.
Requis : action=getCharts, store, country, itemType (buymovies ou seasons)
Optionnel : genre=All, quality=hd4k, limit, imdbRating (min), rottenTomatoesRating (min), releaseYear (ex. 2025-2025)
(voir RECIPES.md)
Renvoie : {"status":"success","results":{"buymovies":[...]}}. Les articles incluent le champ rank.
3. Offres - Deals.php
Offres actuelles et baisses de prix. Idéal pour la chasse aux bonnes affaires.
Requis : action=getDeals, store, country, itemType (buymovies ou seasons)
Optionnel : genre=All, quality=hd4k, sort=latestPricechange, maxPrice, releaseYear (format : 2020-2025 - une seule année comme 2026-2026 fonctionne aussi ; défaut : toutes les années), limit, imdbRating (note min 0-10, défaut 0 = pas de filtre, ex. imdbRating=7), rottenTomatoesRating (note min 0-100, défaut 0 = pas de filtre, ex. rottenTomatoesRating=80), has4K=1 (NE FONCTIONNE PAS - ignoré, filtrer côté client à la place)
Options de tri : latestPricechange (défaut), price, greatestSavings, greatestPercentageSavings, popularity, alphabetical, releaseDate (ascendant uniquement - voir Piège #11)
Filtrer par date : releaseYear=AAAA-AAAA accepte à la fois une seule année (2026-2026) et des plages (2024-2026). Fonctionne sur les endpoints Offres et Classements. PAS supporté sur Recommandations, Prix ou Recherche.
(voir RECIPES.md)
Renvoie : {"status":"success","results":{"buymovies":[...]}}. Les articles incluent price, priceBefore, imdbRating, rottenTomatoesRating.
4. Prix - Prices.php
Rechercher les prix actuels pour des titres spécifiques par ID IMDb.
Requis : action=getPrices, store, country, itemType=buymovies, imdbIDs (note : le llms.txt liste seasons comme valide pour les Prix, mais la table de paramètres spécifique aux Prix et les tests empiriques confirment que seul buymovies fonctionne - voir Piège #7) (séparés par des virgules, ex. tt0468569,tt2911666)
(voir RECIPES.md)
Renvoie : {"status":"success","results":{"buymovies":[...]}}. Même forme d'article que les Offres.
5. Recommandations - Recommendations.php
Recommandations personnalisées, filtrées par genre et qualité.
Requis : action=getRecommendations, store, country, itemType (buymovies ou seasons)
Optionnel : genre=All, quality=hd4k, limit, imdbRating, rottenTomatoesRating
Note : llms.txt liste imdbRating/rottenTomatoesRating comme supportés ici, mais les tests empiriques montrent qu'ils sont silencieusement ignorés sur les Recommandations (Piège #23). Utilisez plutôt les Offres avec sort=greatestSavings + filtres de note.
(voir RECIPES.md)
Renvoie : {"status":"success","results":{"buymovies":[...]}}. Les articles peuvent inclure le champ description.
6. Topseller - Topseller.php
Meilleures ventes sur plusieurs boutiques. Ne nécessite PAS itemType, imdbRating ou rottenTomatoesRating (contrairement aux autres endpoints).
Requis : action=getTopsellerForStartpage, country, store (séparé par des virgules, ex. itunes,amazon,vudu,googlePlay)
Optionnel : maxItemCount=5 (défaut 5, par boutique par catégorie)
(voir RECIPES.md)
Renvoie : {"status":"success","results":{"itunes":{"movies":[...],"seasons":[...]},"amazon":{...}}}. Regroupé par boutique, puis par films/saisons. La disponibilité des champs varie selon la boutique - has4K, hasAtmos, hdrFormat, isMovieBundle n'apparaissent que pour les articles iTunes (voir Piège #3).
7. DetailData (Interne) - DetailData.php
Pas dans la documentation officielle gptapi. Découvert en inspectant les appels réseau du site CheapCharts. Renvoie les détails complets de l'article, y compris les prix actuels, l'historique complet des prix et les saisons enfants (pour les bundles). Fonctionne à la fois pour les films et les saisons. C'est le moyen fiable d'obtenir les prix des saisons/bundles sans navigateur.
Requis : store, country, itemType (movies ou seasons - PAS buymovies), idInStore (l'ID de la boutique iTunes provenant des résultats de recherche)
(voir RECIPES.md)
Renvoie : {"results":{"seasons":{...}}} (la clé correspond au itemType que vous avez passé).
Champs clés (saisons) :
| Champ | Description |
|---|---|
priceSd / priceHd | Prix actuel SD/HD |
priceSdBefore / priceHdBefore | Prix précédent avant le dernier changement |
priceSdLastChangeDate / priceHdLastChangeDate | Date du dernier changement de prix |
priceSdEvolution / priceHdEvolution | Historique complet des prix sous forme de chaîne date:+/-prix~date:+/-prix~.... + = prix augmenté, - = prix diminué. Voir "Analyse de priceHdEvolution" ci-dessous - la convention de variation n'est pas fiable pour reconstruire les prix absolus ; préférez le drapeau IsLowest. |
priceSdIsLowest / priceHdIsLowest | 1 si le prix actuel SD/HD est égal au plus bas historique de CheapCharts pour ce titre, sinon 0. C'est la vérification ATL canonique - utilisez-la au lieu d'analyser priceHdEvolution. |
priceSdIsBest / priceHdIsBest | 1 si le prix actuel SD/HD est égal au meilleur (plus bas) prix dans la fenêtre de vente actuelle (c'est-à-dire le plancher de la vente en cours), sinon 0. Distinct de IsLowest - IsBest=1, IsLowest=0 signifie "le plus bas de CETTE vente mais une vente précédente est allée plus bas." |
priceSdDropIndicator / priceHdDropIndicator | 1 si le prix a augmenté lors du dernier changement, -1 s'il a baissé, 0 s'il est inchangé. Utile pour filtrer les "vraies baisses" sans comparer à priceBefore. |
isBundle / isSeasonBundle | Indique s'il s'agit d'un bundle de saison |
isSeasonComplete | Indique si toutes les saisons sont incluses |
childSeasonsCount | Nombre de saisons enfants dans le bundle |
bundleSavings / bundleSavingsHd | Économies par rapport à l'achat des saisons individuellement au prix normal |
saveOpportunity / saveOpportunityHd | Identique à bundleSavings |
episodeCount | Nombre total d'épisodes |
advisoryRating | Classification du contenu (ex. TV-14) |
summary | Synopsis complet |
seasonFamily | Tableau des saisons enfants, chacune avec idInStore, title, priceSd, priceHd, priceSdEvolution, priceHdEvolution, cheapChartsProductPageUrl |
productPageUrl | URL directe Apple TV / iTunes |
iTunesUrl | URL iTunes |
imageSmallUrl / imageMediumUrl / imageLargeUrl | URLs des jaquettes |
appleTvId | ID interne Apple TV |
Analyse de priceHdEvolution (faible priorité - préférez priceHdIsLowest) : Scinder sur ~, chaque segment est AAAA-MM-JJ:[+/-]prix. Le dernier segment (le plus à droite) est le prix historique le plus ancien ; le premier segment est le changement de prix le plus récent. Exemple :
2026-05-20:+89.99~2026-05-12:-69.99~2026-04-01:-49.99~2022-02-09:89.99
Attention : la convention de variation est incohérente selon les titres - pour certains, le dernier segment est un prix de départ absolu (2022-02-09:89.99 sans signe) ; pour d'autres, les variations ne s'accumulent pas correctement jusqu'au prix actuel. Empiriquement, parcourir les variations du segment le plus ancien ne reproduit PAS toujours priceHd/priceSd. Pour la détection ATL, utilisez les drapeaux priceHdIsLowest / priceSdIsLowest à la place - ils sont fiables. Revenez à l'analyse de priceHdEvolution uniquement si vous avez besoin du montant absolu du plus bas historique ou de la date à laquelle il s'est produit, et validez le résultat par rapport à priceHd avant de lui faire confiance.
Valeurs d'énumération
Boutique
| Valeur | Pays supportés |
|---|---|
itunes | us, de, gb, fr, au, ca, at, ch, es, pt, ru, jp, tr, pl, in, cn |
amazon | us, de |
vudu | us |
googlePlay | us |
Par défaut, utilisez itunes si l'utilisateur ne spécifie pas de boutique - c'est celle qui a la plus large couverture de pays.
Type d'article
| Valeur | Signification | Utilisé par |
|---|---|---|
buymovies | Films (prix d'achat) | Classements, Offres, Prix, Recommandations |
rentalmovies | Films (prix de location, ~30 jours pour commencer, 48h pour finir) | Classements, Offres, Prix (selon le llms.txt officiel) |
seasons | Saisons de séries TV | Classements, Offres, Recommandations, DetailData |
movies | Métadonnées de films uniquement | Recherche uniquement |
seasons | Métadonnées de saisons uniquement | Recherche uniquement |
all | Tous les types de médias (films, saisons, ebooks, livres audio, albums) | Recherche uniquement |
Achat vs location (découvert empiriquement, PAS dans le llms.txt actuel) : Le paramètre itemType de l'endpoint Prix accepte buymovies (prix d'achat) ou rentalmovies (prix de location). La location est généralement de 30 jours pour commencer à regarder et 48 heures pour terminer une fois commencé. L'endpoint Recherche peut renvoyer l'un ou l'autre type - le champ priceFollowUpItemType vous indique lequel utiliser dans la demande de suivi.