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/
歷史最低價檢查： 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 然後 Prices | 透過 Search 取得 imdbId，再透過 Prices 跨商店查詢（陷阱 #19：iTunes = Apple TV） |
| 「最佳完整系列優惠」 | Deals（seasons） | 在客戶端過濾 isBundle=1（配方） |
| 「推薦一部 [類型] 電影」 | Recommendations | 傳入特定類型 + imdbRating（陷阱 #18：若無類型，則回傳圖表資料） |
| 「什麼賣最好」 | Topseller | 跨商店暢銷商品 |
| 「搜尋 [片名]」 | Search | 根據片名搜尋，回傳中繼資料 |
| 「[片名] 是歷史最低價嗎？」/「歷史最低價的優惠」/「有史以來最低價」 | Deals + DetailData | DetailData 暴露了 priceHdIsLowest / priceSdIsLowest 旗標 — 無需解析 priceHdEvolution（請參閱配方：「歷史最低價 (ATL) 優惠」）。僅在需要歷史最低價的實際美元金額或前一次歷史最低價的變更日期時，才使用 priceHdEvolution。 |
| 「哪些商品剛結束特價？」/「下一個降價目標」 | 對候選集合使用 DetailData | priceBefore < price 表示該項目最近的變動是漲價 — 特價剛結束。這些是短期內降價機率最高的項目，應與活躍優惠一同回報，而非靜默過濾掉。請參閱陷阱 #31。 |
API 端點
共同參數： Charts、Deals、Prices 和 Recommendations 共用共同參數（
action、store、country、itemType、imdbRating、rottenTomatoesRating）。Search 和 Topseller 有各自的參數集（請參閱其各自的章節）。
1. Search - Search.php
根據片名尋找項目。當你只有片名並需要 IMDb ID 時，請優先使用此端點。
必要參數： action=search、query=<片名>（或 searchTerm=<片名> — 別名，依供應商的 llms.txt）
選用參數： store=itunes（預設）、country=us（預設）、itemType=all（預設）、limit=20（預設 20，最大 20）、offset=0（結果分頁偏移量，用於取得超過 limit 的結果）
（詳情請參閱 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 - 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 - 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 - 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 - Recommendations.php
策劃的推薦，可按類型和品質過濾。
必要參數： action=getRecommendations、store、country、itemType（buymovies 或 seasons）
選用參數： genre=All、quality=hd4k、limit、imdbRating、rottenTomatoesRating
注意： llms.txt 將 imdbRating/rottenTomatoesRating 列為此處支援的參數，但實證測試顯示它們在 Recommendations 上會被靜默忽略（陷阱 #23）。請改用 Deals 搭配 sort=greatestSavings + 評分過濾器。
（詳情請參閱 RECIPES.md）
回傳：{"status":"success","results":{"buymovies":[...]}}。項目可能包含 description 欄位。
6. Topseller - 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（來自 Search 結果的 iTunes 商店 ID）
（詳情請參閱 RECIPES.md）
回傳：{"results":{"seasons":{...}}}（索引鍵與你傳入的 itemType 相符）。
關鍵欄位（季節）：
| 欄位 | 說明 |
|---|---|
priceSd / priceHd | 當前 SD/HD 價格 |
priceSdBefore / priceHdBefore | 上次變更前的價格 |
priceSdLastChangeDate / priceHdLastChangeDate | 上次價格變更的日期 |
priceSdEvolution / priceHdEvolution | 完整價格歷史，以 日期:+/-價格~日期:+/-價格~... 字串表示。+ = 價格上漲，- = 價格下跌。請參閱下方「解析 priceHdEvolution」 — 增減量慣例在重建絕對價格時不可靠；建議優先使用 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
注意： 增減量慣例在不同項目間不一致 — 對某些項目而言，最後一個區段是絕對起始價格（2022-02-09:89.99 無正負號）；對其他項目而言，增減量無法整齊地累積成當前價格。實證顯示，從最舊區段開始走訪增減量並非總是能重現 priceHd/priceSd。對於 ATL 偵測，請改用 priceHdIsLowest / priceSdIsLowest 旗標——它們是具有權威性的。 僅在需要歷史最低價的實際美元金額或發生日期時，才退而使用解析 priceHdEvolution，並在信任結果前以 priceHd 進行驗證。
列舉值
Store
| 值 | 支援的國家 |
|---|---|
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 — 它擁有最廣泛的國家支援。
ItemType
| 值 | 意義 | 用於 |
|---|---|---|
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 欄位會告訴你在後續 Prices 呼叫中應使用哪一個。