CheapCharts API Skill

A free, public-API price tracker for digital movies and TV shows across iTunes (Apple TV), Amazon Prime Video, Vudu, and Google Play. No authentication. Parallel calls are safe - the bundled deals.py script uses 8 concurrent DetailData workers.

Repo: https://github.com/tracerman/cheapcharts-skill API Base URL: https://buster.cheapcharts.de/v1/gptapi/ ATL check: https://buster.cheapcharts.de/v1/DetailData.php (unofficial internal endpoint - Pitfall #17)

When to Use

• Movie/TV prices, deals, or discounts on digital stores (iTunes/Apple TV, Amazon, Vudu, Google Play)
• Charts (what's popular), recommendations by genre, cross-store price comparison
• Price history / "has it ever been cheaper?" / all-time-low questions
• User mentions CheapCharts directly

Don't use for: physical media (Blu-ray/DVD), streaming subscription catalogs (Netflix/Disney+), movie reviews (web search instead), video games (no public API - see EXTRAS.md).

The Bundled Script (use this first)

scripts/deals.py (stdlib-only, Python 3.9+) pulls Deals, enriches every candidate with the authoritative ATL flag from DetailData in parallel (8 workers, ~12s for 50 items), preserves the API's sort order, and emits a markdown table or JSON. It handles the pitfalls (status checks, DetailData vocabulary, genre validation) so you don't have to.

python scripts/deals.py                        # all current deals (iTunes US), ATL column
python scripts/deals.py --since 1              # only items whose price changed today
python scripts/deals.py --atl-only             # only rows at their all-time low
python scripts/deals.py --title "Fight Club"   # single-title ATL check
python scripts/deals.py --title "Fight Club" --history   # + full price-history timeline (sale windows, floor)
python scripts/deals.py --type seasons         # TV seasons (also: rentalmovies)
python scripts/deals.py --genre horror         # genre filter (case-insensitive, validated)
python scripts/deals.py --max-price 4.99 --min-savings 3 --limit 30
python scripts/deals.py --sort greatestSavings # bundles dominate this sort (Pitfall #35)
python scripts/deals.py --exclude-bundles      # individual movies only (they carry ratings)
python scripts/deals.py --store amazon --title "Heat"   # non-iTunes: prefer --title (Pitfall #30)
python scripts/deals.py --json                 # machine-readable output for pipelines

Exit codes: 0 deals found, 1 no deals matched (legitimate empty result), 2 API or usage error. Failed DetailData lookups are counted and reported in the table header; if all fail, exit is 2.

Default sort is latestPricechange (freshest drops first). Output columns: Title (links to Apple TV) | Fmt | Now | Was | Save | IMDb | RT | Date | ATL | Buy | History.

Default Workflow

1. "Latest deals" / "today's drops" / "what just changed" -> python scripts/deals.py --since 1 (fall back to --since 3 if empty; CheapCharts lags Apple by hours-to-a-day, Pitfall #14).
2. "What's at its all-time low?" -> python scripts/deals.py --atl-only.
3. "Is [title] at its lowest ever?" -> python scripts/deals.py --title "<name>".
4. Anything the script doesn't cover (charts, recommendations, cross-store, search) -> call the API directly per the decision table below; literal curl commands in RECIPES.md.
5. Always check the response status field first - status=error fails silently otherwise (Pitfall #15).

Decision Table

Critical Pitfalls (the ones that silently break workflows)

Full list of 37 with evidence and dates: references/PITFALLS.md.

1. DetailData speaks a different vocabulary: itemType=movies or seasons, NOT buymovies - the wrong value errors, and looks like "no data" if you skip the status check (#13).
2. Always check status before iterating results - errors return {"status":"error"} with an empty result shape that mimics "no deals" (#15).
3. has4K=1 is silently ignored on Deals/Charts - filter client-side (#16).
4. genre is broken for seasons everywhere, and unknown genre values on movies silently return EVERYTHING (#21, #22).
5. priceHdEvolution values are absolute prices, NOT deltas - the sign is only the change direction; summing them produces garbage. For "at ATL now?" use the IsLowest flags; for timelines use --history, which parses it correctly (#26).
6. No batch DetailData - ATL enrichment is N+1 by design; use the parallel script (#28).
7. Never fabricate store URLs - productPageUrl/iTunesUrl/cheapChartsProductPageUrl are in the response; guessed Apple TV slugs 404 (#32).
8. Sort choice = category filter: greatestSavings surfaces bundles, latestPricechange surfaces individual movies (#35).

Presentation Guidelines

1. Always include cheapChartsProductPageUrl (price-history page) and the store buy link (productPageUrl/iTunesUrl from DetailData). Never guess URLs; if a field is missing, show plain text and say "store URL unavailable".

2. Show savings (priceBefore - price, and %) and skip rows where savings <= $0 unless reporting them as "sale ended".

3. Always include an ATL column when data was enriched with DetailData: ATL = at the historical floor, - = ordinary sale. Standard table:

   Title	Genre	Now	Was	Save	IMDb	ATL	Changed
   Title	Genre	$X.XX	$Y.YY	$Z.ZZ (N%)	N.N	ATL	YYYY-MM-DD

4. "Sale ended" rows are reportable signal (Pitfall #31): when priceBefore < price, add a Status column (on sale / sale ended / stable) instead of rendering empty cells - these are the user's "set an alert" candidates.

5. Ratings come from Deals candidates, not DetailData - render IMDb/RT only for individual movies (isMovieBundle == 0); bundles and seasons legitimately have none (#37).

6. Filter noise: Search with itemType=all returns ebooks/audiobooks/albums too - filter by mediaType unless asked otherwise.

7. Mention compounding savings when relevant: gift-card stacking and seasonal sale windows are in EXTRAS.md.

Verification Checklist

• Correct endpoint for the intent (Decision Table above)
• Response status == "success" checked before iterating (Pitfall #15)
• itemType vocabulary correct: buymovies for Deals/Charts/Prices, movies/seasons for DetailData (Pitfall #13)
• Genre values from the enum only; omitted entirely for seasons (Pitfalls #21, #22)
• ATL claims based on priceHdIsLowest/priceSdIsLowest, not parsed evolution strings (Pitfall #26)
• Fake drops filtered (priceBefore > price, savings > $0) and sale-ended rows reported as such (Pitfalls #9, #31)
• Buy/history links taken verbatim from the response (Pitfall #32)
• For non-iTunes stores: single-title lookups preferred over batch (Pitfall #30)
• cheapChartsProductPageUrl included in anything shown to the user

Files in This Skill

• scripts/deals.py - the parallel deal/ATL finder (primary tool; unit-tested, CI-canaried)
• RECIPES.md - literal curl commands for every workflow + cron prompt templates
• references/API.md - full endpoint/parameter/enum/field reference
• references/PITFALLS.md - all 37 empirically-verified API pitfalls
• references/EXTRAS.md - gift-card stacking, Movies Anywhere, seasonal sale calendar, CheapCharts Games
• examples/ - real output screenshots

Source

• API docs: https://www.cheapcharts.com/us/ai (llms.txt) - when llms.txt and this skill disagree, llms.txt wins, then verify empirically
• Website: https://www.cheapcharts.com
• The API is free and public, designed for AI agents. No auth headers needed.