tracerman/cheapcharts-skill

CheapCharts API Skill

Ein kostenloser, öffentlicher API-Preistracker für digitale Filme und Serien auf iTunes (Apple TV), Amazon Prime Video, Vudu und Google Play. Keine Authentifizierung, keine Ratenbegrenzung. Parallele Aufrufe sind sicher – das Skript deals.py verwendet 8 gleichzeitige DetailData-Worker.

Repository: https://github.com/tracerman/cheapcharts-skill API-Basis-URL: https://buster.cheapcharts.de/v1/gptapi/ Allzeittiefstpreis (ATL)-Prüfung: https://buster.cheapcharts.de/v1/DetailData.php (inoffizieller interner Endpunkt – siehe Fallstrick #17)

Standard-Workflow (kanonisches Muster)

Wenn ein Benutzer nach Angeboten, Preisabfällen, Preisen oder „Was ist gerade günstig“ fragt, folge diesem Ablauf:

1. Lege den Store fest. Standardmäßig itunes (US), oder verwende itunes,amazon,vudu,googlePlay für mehrere Stores.
2. Lege den Artikeltyp fest. buymovies für Filme, seasons für Serien, all nur für die Suche.
3. Rufe Angebote mit sort=latestPricechange ab für „aktuellste“ / „heutige Preisabfälle“ / „was hat sich gerade geändert“-Fragen. Verwende sort=greatestSavings für „beste Angebote“ oder sort=releaseDate für „neueste Veröffentlichungen“.
4. Überprüfe „heute“-Behauptungen, indem du für jeden Kandidaten DetailData aufrufst und priceHdLastChangeDate (oder priceSdLastChangeDate) prüfst. Überprüfe immer zuerst das Antwort-status-Feld – status=error bedeutet, dass dein Aufruf sonst stillschweigend fehlschlägt (siehe Fallstrick #15).
5. Filtere falsche Preisabfälle (priceBefore - price <= $1) und Bundle-Platzhalterdaten heraus, wenn nach releaseDate sortiert wird.
6. Reichere mit dem ATL-Flag (priceHdIsLowest / priceSdIsLowest) aus DetailData an, sodass jeder Bericht zeigen kann, ob der Preisabfall am historischen Tiefpunkt liegt. CheapCharts macht einen zusätzlichen Aufruf pro Artikel – siehe die Standardberichtsvorlage in den Präsentationsrichtlinien.

Das vollständige Rezept „Heutige Preisabfälle“ mit Python-Verifizierung findet sich im Abschnitt Workflow-Rezepte.

Wann verwenden

• Benutzer fragt nach Film-/Serienpreisen in digitalen Stores
• Benutzer möchte Angebote oder Rabatte auf digitale Filme finden
• Benutzer möchte Charts durchstöbern (was ist beliebt/angesagt)
• Benutzer möchte Empfehlungen in einem Genre
• Benutzer möchte Preise über Stores vergleichen (iTunes, Amazon, Vudu, Google Play)
• Benutzer möchte die Preishistorie oder den niedrigsten historischen Preis prüfen
• Benutzer erwähnt CheapCharts direkt

Nicht verwenden für: Physische Medien (Blu-ray/DVD), Streaming-Abonnement-Kataloge (Netflix/Disney+), Filmkritiken/-bewertungen (stattdessen Websuche verwenden).

Schnellentscheidungsleitfaden

Benutzer sagt...	Endpunkt verwenden	Warum
„Aktuelle Angebote“ / „heutige Preisabfälle“ / „was hat sich geändert“	Angebote + DetailData	Standard-Workflow: sort=latestPricechange, dann für jeden Artikel prüfen, ob priceHdLastChangeDate auf heute fällt (siehe Rezept: „Heutige Preisabfälle“)
„Angebote unter $X finden“	Angebote	Filtern nach maxPrice + sort=greatestSavings
„Beste hochbewertete Angebote“ / „Kritikerlob unter $X“	Angebote	Filtern nach imdbRating + maxPrice (beides serverseitige Filter, siehe Rezept)
„4K / Dolby Vision / Atmos Filme“	Angebote + Client-Filter	has4K=1 Serverfilter funktioniert nicht (Fallstrick #16) – abrufen und clientseitig filtern
„Neueste Veröffentlichungen im Angebot“	Angebote	sort=releaseDate + Bundle-Platzhalterfilter (siehe Fallstrick #12)
„Was ist gerade beliebt“ / „was verkauft sich“	Charts oder Topseller	Charts für einen Store, Topseller für storeübergreifend
„Wie viel kostet [Titel]“	Suche dann Preise	Suche, um imdbId zu erhalten, dann Preise storeübergreifend (Fallstrick #19: iTunes = Apple TV)
„Beste Gesamtstaffel-Angebote“	Angebote (seasons)	Clientseitig isBundle=1 filtern (Rezept)
„Empfehle mir einen [Genre]-Film“	Empfehlungen	Bestimmtes Genre + imdbRating übergeben (Fallstrick #18: ohne Genre werden Chartdaten zurückgegeben)
„Was verkauft sich am meisten“	Topseller	Storeübergreifende Top-Verkäufer
„Suche nach [Titel]“	Suche	Titelsuche, gibt Metadaten zurück
„Ist [Titel] auf seinem Allzeittief?“ / „Angebote auf ATL“ / „niedrigster Preis aller Zeiten“	Angebote + DetailData	DetailData zeigt priceHdIsLowest / priceSdIsLowest-Flags – kein Parsen von priceHdEvolution nötig (siehe Rezept: „Allzeittiefpreis (ATL)-Angebote“). Verwende priceHdEvolution nur, wenn du den tatsächlichen historischen Tiefstbetrag oder das Änderungsdatum des vorherigen ATL benötigst.
„Was ist gerade aus dem Angebot gefallen?“ / „nächste Preisabfallziele“	DetailData auf einem Kandidatenset	priceBefore < price bedeutet, dass die letzte Änderung des Titels eine Preiserhöhung war – das Angebot ist gerade zu Ende gegangen. Dies sind deine wahrscheinlichsten kurzfristigen Preisabfälle und sollten zusammen mit aktiven Angeboten gemeldet werden, nicht stillschweigend herausgefiltert. Siehe Fallstrick #31.

API-Endpunkte

Gemeinsame Parameter: Charts, Angebote, Preise und Empfehlungen teilen gemeinsame Parameter (action, store, country, itemType, imdbRating, rottenTomatoesRating). Suche und Topseller haben eigene Parametersätze (siehe deren Abschnitte unten).

1. Suche - Search.php

Finde Artikel nach Titel. Verwende dies ZUERST, wenn du nur einen Titel hast und die IMDb-ID benötigst.

Erforderlich: action=search, query=<titel> (oder searchTerm=<titel> – Alias, laut Hersteller-llms.txt) Optional: store=itunes (Standard), country=us (Standard), itemType=all (Standard), limit=20 (Standard 20, max 20), offset=0 (Seitenversatz für Ergebnisse über limit hinaus)

(siehe RECIPES.md)

Gibt eine flache Liste zurück: {"status":"success","results":[...items...]}. Jeder Artikel enthält imdbId (falls verfügbar), mediaType, itemType, priceFollowUpItemType, store, country, cheapChartsProductPageUrl, title, artist, releaseDate, releaseYear, currency, price, currentPrice, has4K, hdrFormat, imdbRating, rottenTomatoesRating (siehe Tabelle „Gemeinsame Artikelfelder“ für vollständige Details).

2. Charts - Charts.php

Aktuelle Chart-Rankings für Filme oder Serienstaffeln.

Erforderlich: action=getCharts, store, country, itemType (buymovies oder seasons) Optional: genre=All, quality=hd4k, limit, imdbRating (min), rottenTomatoesRating (min), releaseYear (z. B. 2025-2025)

(siehe RECIPES.md)

Gibt zurück: {"status":"success","results":{"buymovies":[...]}}. Artikel enthalten das rank-Feld.

3. Angebote - Deals.php

Aktuelle Angebote und Preisabfälle. Am besten für Schnäppchenjagd.

Erforderlich: action=getDeals, store, country, itemType (buymovies oder seasons) Optional: genre=All, quality=hd4k, sort=latestPricechange, maxPrice, releaseYear (Format: 2020-2025 – einzelnes Jahr wie 2026-2026 funktioniert auch; Standard: alle Jahre), limit, imdbRating (min Bewertung 0-10, Standard 0 = kein Filter, z. B. imdbRating=7), rottenTomatoesRating (min Punktzahl 0-100, Standard 0 = kein Filter, z. B. rottenTomatoesRating=80), has4K=1 (FUNKTIONIERT NICHT – wird ignoriert, stattdessen clientseitig filtern)

Sortieroptionen: latestPricechange (Standard), price, greatestSavings, greatestPercentageSavings, popularity, alphabetical, releaseDate (nur aufsteigend – siehe Fallstrick #11)

Datumsfilter: releaseYear=YYYY-YYYY akzeptiert sowohl einzelne Jahre (2026-2026) als auch Bereiche (2024-2026). Funktioniert bei den Endpunkten Angebote und Charts. NICHT unterstützt bei Empfehlungen, Preisen oder Suche.

(siehe RECIPES.md)

Gibt zurück: {"status":"success","results":{"buymovies":[...]}}. Artikel enthalten price, priceBefore, imdbRating, rottenTomatoesRating.

4. Preise - Prices.php

Aktuelle Preise für bestimmte Titel nach IMDb-ID nachschlagen.

Erforderlich: action=getPrices, store, country, itemType=buymovies, imdbIDs (Hinweis: llms.txt Gemeinsame Parameter listet seasons als gültig für Preise, aber die Preise-spezifische Parametertabelle und empirische Tests bestätigen, dass nur buymovies funktioniert – siehe Fallstrick #7) (kommagetrennt, z. B. tt0468569,tt2911666)

(siehe RECIPES.md)

Gibt zurück: {"status":"success","results":{"buymovies":[...]}}. Gleiche Artikelstruktur wie Angebote.

5. Empfehlungen - Recommendations.php

Kuratierte Empfehlungen, gefiltert nach Genre und Qualität.

Erforderlich: action=getRecommendations, store, country, itemType (buymovies oder seasons) Optional: genre=All, quality=hd4k, limit, imdbRating, rottenTomatoesRating

Hinweis: llms.txt listet imdbRating/rottenTomatoesRating als hier unterstützt, aber empirische Tests zeigen, dass sie bei Empfehlungen stillschweigend ignoriert werden (Fallstrick #23). Verwende stattdessen Angebote mit sort=greatestSavings + Bewertungsfiltern.

(siehe RECIPES.md)

Gibt zurück: {"status":"success","results":{"buymovies":[...]}}. Artikel können das description-Feld enthalten.

6. Topseller - Topseller.php

Top-Verkäufer über mehrere Stores. Benötigt KEIN itemType, imdbRating oder rottenTomatoesRating (anders als andere Endpunkte).

Erforderlich: action=getTopsellerForStartpage, country, store (kommagetrennt, z. B. itunes,amazon,vudu,googlePlay) Optional: maxItemCount=5 (Standard 5, pro Store pro Kategorie)

(siehe RECIPES.md)

Gibt zurück: {"status":"success","results":{"itunes":{"movies":[...],"seasons":[...]},"amazon":{...}}}. Gruppiert nach Store, dann nach Filmen/Staffeln. Feldverfügbarkeit variiert je nach Store – has4K, hasAtmos, hdrFormat, isMovieBundle erscheinen nur für iTunes-Artikel (siehe Fallstrick #3).

7. DetailData (Intern) - DetailData.php

Nicht in den offiziellen gptapi-Dokumenten. Entdeckt durch Überprüfung der Netzwerkaufrufe der CheapCharts-Website. Gibt vollständige Artikeldetails zurück, einschließlich aktueller Preise, vollständiger Preishistorie und unterstaffeln (für Bundles). Funktioniert für Filme und Staffeln. Dies ist der zuverlässige Weg, um Staffel-/Bundle-Preise ohne Browser zu erhalten.

Erforderlich: store, country, itemType (movies oder seasons – NICHT buymovies), idInStore (die iTunes-Store-ID aus Suchergebnissen)

(siehe RECIPES.md)

Gibt zurück: {"results":{"seasons":{...}}} (Schlüssel entspricht dem übergebenen itemType).

Schlüsselfelder (Staffeln):

Feld	Beschreibung
priceSd / priceHd	Aktueller SD/HD-Preis
priceSdBefore / priceHdBefore	Vorheriger Preis vor letzter Änderung
priceSdLastChangeDate / priceHdLastChangeDate	Datum der letzten Preisänderung
priceSdEvolution / priceHdEvolution	Vollständige Preishistorie als Datum:+/-Preis~Datum:+/-Preis~...-String. + = Preis gestiegen, - = Preis gefallen. Siehe „Parsen von priceHdEvolution“ unten – die Delta-Konvention ist unzuverlässig zur Rekonstruktion absoluter Preise; bevorzuge das IsLowest-Flag.
priceSdIsLowest / priceHdIsLowest	1, wenn der aktuelle SD/HD-Preis dem Allzeittief über CheapCharts‘ verfolgte Geschichte für diesen Titel entspricht, sonst 0. Dies ist der kanonische ATL-Check – verwende ihn anstelle des Parsens von priceHdEvolution.
priceSdIsBest / priceHdIsBest	1, wenn der aktuelle SD/HD-Preis dem besten (niedrigsten) Preis im aktuellen Angebotsfenster entspricht (d. h. der Tiefstpreis des aktuellen laufenden Angebots), sonst 0. Unterscheidet sich von IsLowest – IsBest=1, IsLowest=0 bedeutet „Tiefstpreis DIESES Angebots, aber ein vorheriges Angebot war günstiger.“
priceSdDropIndicator / priceHdDropIndicator	1, wenn der Preis bei der letzten Änderung gestiegen ist, -1 wenn gefallen, 0 wenn unverändert. Nützlich zum Herausfiltern „echter Preisabfälle“, ohne mit priceBefore vergleichen zu müssen.
isBundle / isSeasonBundle	Ob dies ein Staffel-Bundle ist
isSeasonComplete	Ob alle Staffeln enthalten sind
childSeasonsCount	Anzahl der unterstaffeln im Bundle
bundleSavings / bundleSavingsHd	Ersparnis gegenüber dem Einzelkauf von Staffeln zum regulären Preis
saveOpportunity / saveOpportunityHd	Gleiches wie bundleSavings
episodeCount	Gesamtzahl der Episoden
advisoryRating	Inhaltsbewertung (z. B. TV-14)
summary	Vollständige Zusammenfassung
seasonFamily	Array von unterstaffeln, jede mit idInStore, title, priceSd, priceHd, priceSdEvolution, priceHdEvolution, cheapChartsProductPageUrl
productPageUrl	Direkte Apple TV / iTunes-Store-URL
iTunesUrl	iTunes-URL
imageSmallUrl / imageMediumUrl / imageLargeUrl	Cover-Art-URLs
appleTvId	Interne Apple TV-ID

Parsen von priceHdEvolution (niedrige Priorität – priceHdIsLowest bevorzugen): Auf ~ aufteilen, jedes Segment ist YYYY-MM-DD:[+/-]Preis. Das letzte Segment (ganz rechts) ist der früheste historische Preis; das erste Segment ist die jüngste Preisänderung. Beispiel:

2026-05-20:+89.99~2026-05-12:-69.99~2026-04-01:-49.99~2022-02-09:89.99

Einschränkung: Die Delta-Konvention ist titelübergreifend inkonsistent – bei manchen ist das letzte Segment ein absoluter Startpreis (2022-02-09:89.99 ohne Vorzeichen); bei anderen akkumulieren sich die Deltas nicht sauber zum aktuellen Preis. Empirisch führt das Wandern der Deltas vom ältesten Segment NICHT immer zu einer korrekten Reproduktion von priceHd/priceSd. Für die ATL-Erkennung verwende stattdessen die Flags priceHdIsLowest / priceSdIsLowest – sie sind autoritativ. Greife nur dann auf das Parsen von priceHdEvolution zurück, wenn du den absoluten Dollarbetrag des historischen Tiefstpreises oder dessen Datum benötigst, und validiere das Ergebnis gegen priceHd, bevor du es vertraust.

Enum-Werte

Store

Wert	Unterstützte Länder
itunes	us, de, gb, fr, au, ca, at, ch, es, pt, ru, jp, tr, pl, in, cn
amazon	us, de
vudu	us
googlePlay	us

Standardmäßig itunes verwenden, wenn der Benutzer keinen Store angibt – es hat die breiteste Länderunterstützung.

ItemType

Wert	Bedeutung	Verwendet von
buymovies	Filme (Kaufpreise)	Charts, Angebote, Preise, Empfehlungen
rentalmovies	Filme (Mietpreise, ~30 Tage Startzeit, 48h zum Anschauen)	Charts, Angebote, Preise (laut offizieller llms.txt)
seasons	Serienstaffeln	Charts, Angebote, Empfehlungen, DetailData
movies	Nur Filmmaterial	Nur Suche
seasons	Nur Staffel-Metadaten	Nur Suche
all	Alle Medientypen (Filme, Staffeln, E-Books, Hörbücher, Alben)	Nur Suche

Kauf vs. Miete (empirisch entdeckt, NICHT in aktueller llms.txt): Der itemType-Parameter des Preise-Endpunkts akzeptiert buymovies (Kaufpreis) oder rentalmovies (Mietpreis). Mieten haben in der Regel 30 Tage Startzeit und 48 Stunden zum Fertiganschauen, nachdem sie gestartet wurden. Der Suche-Endpunkt kann beide Typen zurückgeben – das Feld priceFollowUpItemType sagt dir, welches du im Folgeaufruf verwenden sollst.

Qualität

Wert	Bedeutung
hd	Nur HD
hd4k	HD & 4K (Standard)
sd	Nur SD (wird von den meisten Endpunkten nicht unterstützt)

Genre

Name	API-Wert
Action	Action & Adventure
Animation	Animation
Anime	Anime (nur Suche & Charts – funktioniert NICHT mit Angeboten oder Empfehlungen; siehe Fallstrick #8)
Klassiker	Classics
Komödie	Comedy
Dokumentation	Documentary
Drama	Drama
Familienunterhaltung	Family Entertainment (nicht Kids & Family)
Horror	Horror
Independent	Independent (nicht Indie)
Musik	Music
Musical	Musicals
Romantik	Romance
Science-Fiction & Fantasy	Sci-Fi & Fantasy
Sport	Sports (nicht Sport)
Thriller	Thriller
Western	Western
Alle	All

Häufige Fallstricke

Fallstrick #1: IDs können storeübergreifend mehrdeutig sein

Jeder Store hat seine eigene ID für denselben Film. idInStore ist nur innerhalb eines Stores eindeutig. Verwende immer imdbId, wenn du storeübergreifend referenzieren musst.

Fallstrick #2: Die Verwendung von itemType in Suche verändert die Ergebnisformatierung

Wenn du itemType=all (Standard) an die Suche übergibst, werden die Ergebnisse in Kategorien gruppiert: {"results":{"movies":[...],"seasons":[...],"ebooks":[...]}}. Wenn du einen bestimmten itemType übergibst, werden sie flach in results zurückgegeben. Sei bereit, beide Formate zu handhaben.

Allgemeine Artikelfelder

Feld	Typ	Beschreibung
imdbId	String	IMDb-ID, wenn verfügbar
mediaType	String	„Movie“ oder „Season“
itemType	String	Der zu verwendende ItemType (z. B. „buymovies“)
store	String	Store-Enum-Wert
country	String	Ländercode
cheapChartsProductPageUrl	String	CheapCharts-Produktseiten-URL
title	String	Filmtitel
artist	String	Künstler/Regisseur (wenn verfügbar)
releaseDate	String	Veröffentlichungsdatum
releaseYear	String	Veröffentlichungsjahr
currency	String	Währungscode (z. B. USD)
price	Zahl	Aktueller Preis (für Suchergebnisse)
currentPrice	Zahl	Aktueller Preis (für nicht-Suche)
priceBefore	Zahl	Vorheriger Preis vor Preisänderung
has4K	Bool/String	Ob 4K verfügbar ist
hdrFormat	String	HDR-Format (z. B. „Dolby Vision“, „HDR10“)
imdbRating	Zahl	IMDb-Bewertung (0-10)
rottenTomatoesRating	Zahl	Rotten-Tomatoes-Bewertung (0-100)
description	String	Kurzbeschreibung (nur Empfehlungen)
rank	Zahl	Chart-Rang (nur Charts)
priceDescription	String	Von CheapCharts erstellte Preisbeschreibung (nur Charts)
priceFollowUpItemType	String	Gibt an, ob Kauf oder Miete für Folgeaufrufe verwendet werden soll
priceSd / priceHd	Zahl	SD/HD-Preis (nur DetailData)
priceSdBefore / priceHdBefore	Zahl	Vorheriger SD/HD-Preis (nur DetailData)
priceSdEvolution / priceHdEvolution	String	Preishistorie (nur DetailData)
priceSdIsLowest / priceHdIsLowest	Bool	ATL-Flag (nur DetailData)
priceSdIsBest / priceHdIsBest	Bool	Bestpreis-im-Angebot-Flag (nur DetailData)
priceSdLastChangeDate / priceHdLastChangeDate	String	Datum der letzten SD/HD-Preisänderung (nur DetailData)
priceSdDropIndicator / priceHdDropIndicator	Zahl	Preisänderungsindikator (nur DetailData)
isBundle / isSeasonBundle	Bool	Bundle-Flag (nur DetailData)
childSeasonsCount	Zahl	Anzahl unterstaffeln (nur DetailData)
episodeCount	Zahl	Episodenanzahl (nur DetailData)
seasonFamily	Array	Unterstaffeln-Details (nur DetailData)
summary	String	Vollständige Zusammenfassung (nur DetailData)

Präsentationsrichtlinien

Wenn Preise oder Angebote präsentiert werden:

1. Gib Preise im natürlichen Währungsformat aus (z. B. $4.99, £3.99, €5.99). Verwende das currency-Feld, um zu entscheiden, welches Symbol verwendet werden soll.
2. Zeige den ursprünglichen Preis mit Durchstreichung und den neuen Preis fett an: $14.99 $4.99.
3. Gib die prozentuale Ersparnis an, wenn es eine signifikante Reduzierung gibt (>20%).
4. Füge Bewertungsinformationen hinzu, wenn verfügbar: ⭐ IMDb 8.5 🍅 Rotten Tomatoes 92%.
5. Füge Qualitätsflags hinzu, wenn 4K, Dolby Vision oder Atmos verfügbar sind.
6. Für Staffel-/Bundle-Angebote füge den Bundle-Typ hinzu (z. B. „Bundle mit 3 Staffeln“, „Sparpotential $24.99“).

ATL-Präsentation

Wenn du Allzeittiefstpreise (ATL) präsentierst:

• Zeige 🔥 ALLZEITTIEF oder ALL-TIME LOW für ATL-Angebote an
• Wenn priceHdIsBest=1 aber priceHdIsLowest=0, zeige Angebotstief (Bester Preis dieses Angebots, aber kein Allzeittief) an
• Füge den historischen Tiefstbetrag hinzu, wenn du ihn zur Hand hast: „Niedrigster Preis aller Zeiten: $X.XX (erreicht am JJJJ-MM-TT)“
• Vergleiche den aktuellen Preis mit dem ATL: „$X.XX unter dem vorherigen ATL von $Y.YY“

Workflow-Rezepte (Kurzzusammenfassung)

Siehe RECIPES.md für vollständige Python-Implementierungen dieser Rezepte.

R1: Heutige Preisabfälle

# Pseudo-Code
angebote = GET("/Deals.php?action=getDeals&store=itunes&itemType=buymovies&sort=latestPricechange&limit=50")
heutige_abfälle = []
for item in angebote.results.buymovies:
    details = GET("/DetailData.php?store=itunes&country=us&itemType=movies&idInStore=" + item.idInStore)
    item_details = details.results.movies[0]  # Hinweis: Der Schlüssel ist "movies", nicht "buymovies"
    if item_details.priceHdLastChangeDate == heute:
        if (item_details.priceHdBefore - item_details.priceHd) > 1.0:  # "Fake-Drop"-Filter
            item.atl_flag = item_details.priceHdIsLowest
            heutige_abfälle.append(item)

Wichtige Hinweise:

• Verwende itemType=movies für DetailData (nicht buymovies)
• Der Ergebnis-Schlüssel von DetailData entspricht dem übergebenen itemType (also results.movies, nicht results.buymovies)
• Verwende idInStore aus den Suchergebnissen, nicht die IMDb-ID

R2: Allzeittiefpreis (ATL)-Angebote

# Pseudo-Code
angebote = GET("/Deals.php?...&sort=greatestSavings&limit=30")
atl_angebote = []
for item in angebote.results.buymovies:
    details = GET("/DetailData.php?...&idInStore=" + item.idInStore)
    if details.results.movies[0].priceHdIsLowest:
        atl_angebote.append(item)

# ATL zuerst präsentieren!

R3: Storeübergreifender Preisvergleich

# Suche nach dem Titel, um imdbId zu erhalten
suchergebnisse = GET("/Search.php?action=search&query=Batman+Begins&itemType=all")
imdb_id = suchergebnisse.results.movies[0].imdbId

# Preise in allen Stores abrufen
preise = {}
for store in ["itunes", "amazon", "vudu", "googlePlay"]:
    preise[store] = GET(f"/Prices.php?action=getPrices&store={store}&itemType=buymovies&imdbIDs={imdb_id}")

R4: Hochbewertete Angebote finden

# GET /Deals.php?action=getDeals&store=itunes&itemType=buymovies&sort=greatestSavings&maxPrice=9.99&imdbRating=7
# Serverseitige Filterung - kein clientseitiges Nachfiltern nötig
# Aber verwende immer noch clientseitiges Filtern als Fallback

R5: Bundle-Angebote finden

angebote = GET("/Deals.php?action=getDeals&store=itunes&itemType=seasons&sort=greatestSavings")
# Clientseitiges Herausfiltern von Bundles erfordert DetailData
bundles = []
for item in angebote.results.seasons:
    details = GET("/DetailData.php?store=itunes&country=us&itemType=seasons&idInStore=" + item.idInStore)
    if details.results.seasons[0].isBundle:
        bundles.append(details.results.seasons[0])

Fehlerbehandlung

1. Überprüfe immer status: Alle Endpunkte geben {"status":"success"} bei Erfolg oder {"status":"error","message":"..."} bei Fehler zurück. Wenn status nicht „success“ ist, hat der API-Aufruf fehlgeschlagen – versuche es erneut oder gib eine Fehlermeldung aus.
2. Rate-Limiting: Es gibt keine dokumentierten Ratenbegrenzungen, aber verwende trotzdem höfliche Verzögerungen (200-500ms) zwischen Anfragen. Das Rezept deals.py verwendet 8 gleichzeitige Worker ohne Probleme – parallelisieren ist sicher, aber vermeide 50+ gleichzeitige Aufrufe.
3. Leere Ergebnisse: Wenn ein Endpunkt ein leeres results-Objekt zurückgibt (z. B. {"results":{"buymovies":[]}}), waren entweder keine passenden Daten vorhanden oder die Filter waren zu restriktiv. Versuche, die Filter zu lockern.
4. Store-Fallbacks: Wenn ein bestimmter Store keine Angebote hat (leeres Ergebnis), falle nicht stillschweigend auf einen anderen Store zurück – informiere den Benutzer, dass dieser Store keine passenden Angebote hat, und frage, ob er einen anderen Store ausprobieren möchte.
5. Netzwerkfehler: Wenn ein API-Aufruf fehlschlägt (Zeitüberschreitung, Verbindungsfehler), versuche es bis zu 2 Mal mit exponentiellem Backoff (1s, 2s), bevor du dem Benutzer einen Fehler meldest.

Länderspezifische Überlegungen

• US vs. Nicht-US: iTunes wird für die meisten Länder unterstützt (us, de, gb, fr, au, ca, at, ch, es, pt, ru, jp, tr, pl, in, cn). Amazon wird nur für us und de unterstützt. Vudu und Google Play werden nur für us unterstützt.
• Währungen: Die API gibt den currency-Code für jeden Artikel zurück (USD, EUR, GBP, JPY usw.). Verwende diesen Code, um die Währungssymbol-Anzeige zu bestimmen.
• Inhaltsverfügbarkeit: Preise, Angebote und Chartdaten variieren je nach Land und Store. Ein Film könnte in einem Land, aber nicht in einem anderen verfügbar sein, und die Preise unterscheiden sich.

Support & Entwicklung

• Repository: https://github.com/tracerman/cheapcharts-skill
• API-Dokumentation: Die meisten Endpunkte sind unter https://buster.cheapcharts.de/v1/gptapi/ dokumentiert. DetailData ist undokumentiert – siehe Abschnitt DetailData oben.
• Rezepte: Siehe RECIPES.md für Python-Implementierungen.
• Probleme melden: GitHub-Issues im Repository.