CheapCharts API 技能
一个免费、公共 API 的价格追踪器，用于追踪 iTunes (Apple TV)、Amazon Prime Video、Vudu 和 Google Play 上的数字电影和电视节目。无需认证，无速率限制。并行调用是安全的——
deals.py脚本使用了 8 个并发的 DetailData 工作线程。
仓库： https://github.com/tracerman/cheapcharts-skill
API 基础 URL： https://buster.cheapcharts.de/v1/gptapi/
历史最低价 (ATL) 检查： https://buster.cheapcharts.de/v1/DetailData.php（非官方内部端点——参见陷阱 #17）
默认工作流（规范模式）
当用户询问有关交易、降价、价格或“现在什么便宜”的任何问题时，请遵循以下流程：
- 决定商店。 默认为
itunes（美国），或使用itunes,amazon,vudu,googlePlay进行多商店搜索。 - 决定项目类型。 电影使用
buymovies，电视使用seasons，仅搜索使用all。 - 使用
sort=latestPricechange获取交易 用于“最新” / “今日降价” / “刚刚变化的” 问题。使用sort=greatestSavings获取“最佳交易”，或使用sort=releaseDate获取“最新发布”。 - 通过访问 DetailData 验证“今日”声明，针对每个候选项目并检查
priceHdLastChangeDate（或priceSdLastChangeDate）。始终首先检查响应status字段——status=error意味着你的调用静默失败（参见陷阱 #15）。 - 过滤掉虚假降价（
priceBefore - price <= $1）以及在按releaseDate排序时的捆绑包占位日期。 - 使用 DetailData 的 ATL 标志 (
priceHdIsLowest/priceSdIsLowest) 丰富信息，使得每个报告都能显示每次降价是否处于历史最低价。CheapCharts 为每个项目额外调用一次——请参阅呈现指南中的标准报告模板。
完整的“今日降价”配方（含 Python 验证）在工作流配方部分。
何时使用
- 用户询问数字商店中电影/电视节目的价格
- 用户想查找数字电影的优惠或折扣
- 用户想浏览排行榜（什么流行/热门）
- 用户想要某个类型的推荐
- 用户想比较跨商店的价格（iTunes、Amazon、Vudu、Google Play）
- 用户想查看价格历史或最低历史价格
- 用户直接提到 CheapCharts
不要用于： 实体媒体（Blu-ray/DVD）、流媒体订阅目录（Netflix/Disney+）、电影评论/批评（请改用网络搜索）。
快速决策指南
| 用户说... | 使用端点 | 原因 |
|---|---|---|
| “最新优惠” / “今日降价” / “刚刚变化的” | Deals + DetailData | 默认工作流：sort=latestPricechange，然后验证每个项目的 priceHdLastChangeDate 是否匹配今天（参见配方：“今日价格降价”） |
| “查找低于 $X 的优惠” | Deals | 通过 maxPrice 过滤 + sort=greatestSavings |
| “最佳高评分优惠” / “低于 $X 的评论佳作” | Deals | 通过 imdbRating + maxPrice 过滤（两者均为服务端过滤器，参见配方） |
| “4K / Dolby Vision / Atmos 电影” | Deals + 客户端过滤 | has4K=1 服务端过滤器无效（陷阱 #16）——先获取再在客户端过滤 |
| “打折的最新发布” | Deals | sort=releaseDate + 捆绑包占位符过滤（参见陷阱 #12） |
| “现在什么最流行” / “什么正在热卖” | Charts 或 Topseller | Charts 用于单一商店，Topseller 用于跨商店 |
| “[片名] 多少钱” | Search then Prices | Search 获取 imdbId，然后 Prices 跨商店获取（陷阱 #19：iTunes = Apple TV） |
| “最佳完整剧集优惠” | Deals (seasons) | 客户端过滤 isBundle=1（配方） |
| “给我推荐一部 [类型] 电影” | Recommendations | 指定具体类型 + imdbRating（陷阱 #18：没有类型时，返回排行数据） |
| “什么卖得最好” | Topseller | 跨商店畅销榜 |
| “搜索 [片名]” | Search | 基于标题的搜索，返回元数据 |
| “[片名] 是否处于历史最低价？” / “ATL 优惠” / “有史以来最低价” | Deals + DetailData | DetailData 暴露 priceHdIsLowest / priceSdIsLowest 标志——无需解析 priceHdEvolution（参见配方：“历史最低价 (ATL) 优惠”）。仅在你需要实际的历史最低美元金额或之前 ATL 的变更日期时才使用 priceHdEvolution。 |
| “什么刚刚结束促销？” / “下一个降价目标” | 对候选集调用 DetailData | priceBefore < price 意味着该标题最近的变化是价格上涨——促销刚刚结束。这些是概率最高的近期降价目标，应与活跃交易一起报告，而不是静默过滤掉。参见陷阱 #31。 |
API 端点
公共参数： Charts、Deals、Prices 和 Recommendations 共享公共参数（
action、store、country、itemType、imdbRating、rottenTomatoesRating）。Search 和 Topseller 有自己的参数集（参见各自部分）。
1. 搜索 - Search.php
按标题查找项目。当你只有标题且需要 IMDb ID 时，首先使用此端点。
必需： action=search，query=<标题>（或 searchTerm=<标题>——别名，根据供应商的 llms.txt）
可选： store=itunes（默认），country=us（默认），itemType=all（默认），limit=20（默认 20，最大 20），offset=0（超出限制的结果分页偏移量）
（参见 RECIPES.md）
返回扁平列表：{"status":"success","results":[...项目...]}。每个项目包含 imdbId（如可用）、mediaType、itemType、priceFollowUpItemType、store、country、cheapChartsProductPageUrl、title、artist、releaseDate、releaseYear、currency、price、currentPrice、has4K、hdrFormat、imdbRating、rottenTomatoesRating（完整详情请参见公共项目字段表）。
2. 排行榜 - Charts.php
电影或电视季的当前排行榜。
必需： action=getCharts、store、country、itemType（buymovies 或 seasons）
可选： genre=All、quality=hd4k、limit、imdbRating（最小值）、rottenTomatoesRating（最小值）、releaseYear（例如 2025-2025）
（参见 RECIPES.md）
返回：{"status":"success","results":{"buymovies":[...]}}。项目包含 rank 字段。
3. 交易 - Deals.php
当前交易和降价。最适合淘便宜货。
必需： action=getDeals、store、country、itemType（buymovies 或 seasons）
可选： genre=All、quality=hd4k、sort=latestPricechange、maxPrice、releaseYear（格式：2020-2025——单一年份如 2026-2026 也可用；默认：所有年份）、limit、imdbRating（最低评分 0-10，默认 0 = 无过滤，例如 imdbRating=7）、rottenTomatoesRating（最低分数 0-100，默认 0 = 无过滤，例如 rottenTomatoesRating=80）、has4K=1（无效——被忽略，改为在客户端过滤）
排序选项： latestPricechange（默认）、price、greatestSavings、greatestPercentageSavings、popularity、alphabetical、releaseDate（仅升序——参见陷阱 #11）
日期过滤器： releaseYear=YYYY-YYYY 接受单一年份（2026-2026）和范围（2024-2026）。适用于 Deals 和 Charts 端点。在 Recommendations、Prices 或 Search 上不支持。
（参见 RECIPES.md）
返回：{"status":"success","results":{"buymovies":[...]}}。项目包含 price、priceBefore、imdbRating、rottenTomatoesRating。
4. 价格 - Prices.php
按 IMDb ID 查找特定标题的当前价格。
必需： action=getPrices、store、country、itemType=buymovies、imdbIDs（注意：llms.txt 公共参数列表将 seasons 列为 Prices 的有效值，但 Prices 特定的参数表和实证测试确认只有 buymovies 有效——参见陷阱 #7）（逗号分隔，例如 tt0468569,tt2911666）
（参见 RECIPES.md）
返回：{"status":"success","results":{"buymovies":[...]}}。项目形状与 Deals 相同。
5. 推荐 - Recommendations.php
精选推荐，按类型和质量过滤。
必需： action=getRecommendations、store、country、itemType（buymovies 或 seasons）
可选： genre=All、quality=hd4k、limit、imdbRating、rottenTomatoesRating
注意： llms.txt 列出 imdbRating/rottenTomatoesRating 在此处支持，但实证测试显示它们在 Recommendations 上被静默忽略（陷阱 #23）。请改用带 sort=greatestSavings + 评分过滤器的 Deals。
（参见 RECIPES.md）
返回：{"status":"success","results":{"buymovies":[...]}}。项目可能包含 description 字段。
6. 畅销榜 - Topseller.php
跨多个商店的畅销商品。不要求 itemType、imdbRating 或 rottenTomatoesRating（与其他端点不同）。
必需： action=getTopsellerForStartpage、country、store（逗号分隔，例如 itunes,amazon,vudu,googlePlay）
可选： maxItemCount=5（默认 5，每商店每类别）
（参见 RECIPES.md）
返回：{"status":"success","results":{"itunes":{"movies":[...],"seasons":[...]},"amazon":{...}}}。按商店分组，然后按电影/电视季分组。字段可用性因商店而异——has4K、hasAtmos、hdrFormat、isMovieBundle 仅对 iTunes 项目出现（参见陷阱 #3）。
7. DetailData（内部） - DetailData.php
不在官方 gptapi 文档中。 通过检查 CheapCharts 网站的网络调用发现。返回完整的项目详情，包括当前价格、完整价格历史以及子季（适用于捆绑包）。同时适用于电影和电视季。这是无需浏览器即可获取季/捆绑包价格的可靠方法。
必需： store、country、itemType（movies 或 seasons——注意不是 buymovies）、idInStore（搜索结果中的 iTunes 商店 ID）
（参见 RECIPES.md）
返回：{"results":{"seasons":{...}}}（键与你传递的 itemType 匹配）。
关键字段（季）：
| 字段 | 描述 |
|---|---|
priceSd / priceHd | 当前 SD/HD 价格 |
priceSdBefore / priceHdBefore | 上次变更前的价格 |
priceSdLastChangeDate / priceHdLastChangeDate | 上次价格变更的日期 |
priceSdEvolution / priceHdEvolution | 完整价格历史，格式为 日期:+/-价格~日期:+/-价格~... 字符串。+ = 价格上涨，- = 价格下跌。请参阅下方“解析 priceHdEvolution”——delta 约定对于重建绝对价格并不可靠；优先使用 IsLowest 标志。 |
priceSdIsLowest / priceHdIsLowest | 如果当前 SD/HD 价格等于 CheapCharts 跟踪历史中的历史最低价，则为 1，否则为 0。这是规范的 ATL 检查——请使用它而不是解析 priceHdEvolution。 |
priceSdIsBest / priceHdIsBest | 如果当前 SD/HD 价格等于当前促销窗口内的最低（最佳）价格（即当前持续促销的底价），则为 1，否则为 0。与 IsLowest 不同——IsBest=1, IsLowest=0 表示“本次促销的最低点，但之前的促销更低”。 |
priceSdDropIndicator / priceHdDropIndicator | 如果上次变更价格上涨则为 1，下跌则为 -1，无变化则为 0。用于过滤“真实降价”而无需与 priceBefore 比较。 |
isBundle / isSeasonBundle | 是否为季捆绑包 |
isSeasonComplete | 是否包含所有季 |
childSeasonsCount | 捆绑包中的子季数量 |
bundleSavings / bundleSavingsHd | 与单独按常规价格购买每季相比节省的金额 |
saveOpportunity / saveOpportunityHd | 与 bundleSavings 相同 |
episodeCount | 总集数 |
advisoryRating | 内容分级（例如 TV-14） |
summary | 完整剧情简介 |
seasonFamily | 子季数组，每个包含 idInStore、title、priceSd、priceHd、priceSdEvolution、priceHdEvolution、cheapChartsProductPageUrl |
productPageUrl | 直接的 Apple TV / iTunes 商店 URL |
iTunesUrl | iTunes URL |
imageSmallUrl / imageMediumUrl / imageLargeUrl | 封面图 URL |
appleTvId | Apple TV 内部 ID |
解析 priceHdEvolution（低优先级——优先使用 priceHdIsLowest）： 用 ~ 分割，每个片段为 YYYY-MM-DD:[+/-]价格。最后一个片段（最右边）是最早的历史价格；第一个片段是最近一次价格变更。示例：
2026-05-20:+89.99~2026-05-12:-69.99~2026-04-01:-49.99~2022-02-09:89.99
注意： delta 约定在标题之间不一致——对于某些标题，最后一个片段是绝对起始价格（2022-02-09:89.99 无符号）；对于其他标题，delta 无法干净地累加到当前价格。根据经验，从最旧的片段步行 delta 并不总是能复现 priceHd/priceSd。对于 ATL 检测，请改用 priceHdIsLowest / priceSdIsLowest 标志——它们是权威的。 仅在需要历史低价的绝对美元金额或其发生日期时才退而解析 priceHdEvolution，并在信任之前对照 priceHd 验证结果。
枚举值
商店
| 值 | 支持的国家 |
|---|---|
itunes | us, de, gb, fr, au, ca, at, ch, es, pt, ru, jp, tr, pl, in, cn |
amazon | us, de |
vudu | us |
googlePlay | us |
如果用户未指定商店，默认为 itunes——它拥有最广泛的国家支持。
项目类型
| 值 | 含义 | 用于 |
|---|---|---|
buymovies | 电影（购买价格） | Charts, Deals, Prices, Recommendations |
rentalmovies | 电影（租赁价格，约 30 天开始观看，48 小时完成） | Charts, Deals, Prices（根据官方 llms.txt） |
seasons | 电视剧季 | Charts, Deals, Recommendations, DetailData |
movies | 仅电影元数据 | 仅 Search |
seasons | 仅季节元数据 | 仅 Search |
all | 所有媒体类型（电影、季、电子书、有声书、专辑） | 仅 Search |
购买 vs 租赁（经验发现，当前 llms.txt 中未包含）： Prices 端点的 itemType 参数接受 buymovies（购买价格）或 rentalmovies（租赁价格）。租赁通常有 30 天开始观看，48 小时完成。Search 端点可以返回任一类型——priceFollowUpItemType 字段告诉你后续请求中应使用哪一个。
…
[因翻译截断]