# HKTVmall 爬蟲｜香港電商商品、價格、庫存、評分一鍵匯出（免 API） (`claude_code_reviewer/hktvmall-scraper`) Actor 免登入抓 HKTVmall（香港最大網購）商品：售價、庫存、評分、品牌、分類與商品編號，輸出 JSON／CSV／Excel。香港電商選品、比價、庫存監控必備。 - **URL**: https://apify.com/claude\_code\_reviewer/hktvmall-scraper.md - **Developed by:** [Chad](https://apify.com/claude_code_reviewer) (community) - **Categories:** AI, Automation, E-commerce - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 1 bookmarks - **User rating**: No ratings yet ## Pricing from $2.00 / 1,000 搜尋商品 This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## HKTVmall 香港網購商品爬蟲｜搜尋、價格、庫存、評分一鍵下載（免 API、免登入） 一個 Actor 抓 **HKTVmall**（香港最大網購平台）的關鍵字搜尋商品列表：價格、原價折扣、庫存狀態、評分、評論數、分類。走 HKTVmall 前台搜尋頁背後的 **Algolia 商品搜尋索引**，不需要登入、不需要 API token，批量貼上上百個關鍵字都吃得下。全程走公開 JSON 端點，不開瀏覽器，速度快、成本低。 給誰用的：做香港電商比價/監控的、追蹤特定商品價格與庫存波動的、寫市場調查報告的、跑跨境電商數據分析的、論文需要資料集的、自己寫 side project 的工程師。 --- ### 能抓到什麼 每一筆商品都會拿到下面這些欄位（缺值一律回 `null`，不會少欄位）： | 欄位 | 說明 | 範例 | | ---------------------- | ------------------------------------------ | --------------------------------------------------------- | | `product_code` | HKTVmall 商品代碼（SKU，含款式） | `H6771001_S_K01-C014180FC` | | `base_product` | 商品基礎代碼（不含款式後綴） | `H6771001K01-C014180FC` | | `name` | 商品名稱（繁中，缺才退回英文） | `[原箱] Espresso Barista 拿坡利鋁製咖啡粉囊 - 100粒裝` | | `brand` | 品牌 | `KIMBO` | | `selling_price` | 目前售價（HK$） | `450` | | `selling_price_range` | 售價區間（有款式差異時） | `400-600` | | `saved_price` | 折扣省下金額（HK$，取第一筆折扣紀錄） | `49` | | `average_rating` | 平均評分（0-5） | `5` | | `number_of_reviews` | 評論數 | `1` | | `in_stock` | 是否有庫存 | `true` | | `stock` | 庫存狀態代碼 | `inStock` | | `loyalty_point` | 購買可得的購物點數 | `0` | | `number_of_variants` | 款式（顏色/規格）數量 | `1` | | `main_category` | 主分類 | `超級市場` | | `sub_category` | 子分類（第一層） | `飲品 即沖飲品` | | `category_path` | 完整分類路徑（各層以 `/` 串接） | `超級市場/飲品 即沖飲品/即飲咖啡 奶茶/咖啡` | | `image` | 商品主圖網址 | `https://cdn-media.hktvmall.com/.../xxx_300.jpg` | | `product_url` | 商品網址（見下方「注意事項」的免責說明） | `https://www.hktvmall.com/hktv/zh/main/.../p/H6771001_...` | | `keyword` | 命中這筆的搜尋關鍵字 | `coffee` | | `source_mode` | 來源模式，v1.0 一律 `search` | `search` | | `source_query` | 抓取時用的查詢條件（同 `keyword`） | `coffee` | | `scraped_at` | 抓取當下時間（ISO 8601） | `2026-07-04T05:23:28.617Z` | --- ### 模式（v1.0 只有 search） | 模式 | 幹嘛用的 | 計費事件 | 單價 | | ------------- | -------------------------------------------- | ------------------------ | ------ | | 🔎 **search** | 關鍵字搜尋，拿商品列表（價格、庫存、評分、分類） | `search-listing`（每筆） | $0.002 | 每次 Run 啟動都會額外收一次性的 `actor-start` 費用 **$0.005**。所有計費都在資料成功寫入 dataset **之後**才會收，Run 結束時 log 會印出 `total_items / charged / skipped` 讓你對帳。 `detail`（單一商品完整資料）與 `category`（分類瀏覽）規劃於 v1.1，v1.0 只做已驗證可行的搜尋列表模式。 --- ### 輸入欄位 | 欄位 | 型別 | 必填 | 預設 | 說明 | | ----------- | -------- | :----: | :---------: | ---------------------------------------------------------------------------------------------------------------------- | | `mode` | enum | 選填 | `search` | v1.0 只支援 `search`。 | | `keywords` | string[] | 必填其一（或 `bulkInput`） | — | 搜尋關鍵字，一個概念一個關鍵字最準。單次最多 **50** 個。 | | `bulkInput` | string | 選填 | — | **一行一個**，按 Enter 換行，不要加引號或逗號。執行時自動併入 `keywords`。從 Google Sheet / Excel 複製一整欄貼進來最快。 | | `maxItems` | integer | 選填 | `50` | 每個關鍵字最多抓幾筆（1-500）。 | --- ### 範例 **🔎 基本關鍵字搜尋** ```json { "mode": "search", "keywords": ["coffee"], "maxItems": 20 } ```` **📋 批量關鍵字（一行一個）** ```json { "mode": "search", "bulkInput": "coffee\n洗髮\n尿片", "maxItems": 30 } ``` **🇭🇰 中文關鍵字（港式繁中搜尋）** ```json { "mode": "search", "keywords": ["洗髮"], "maxItems": 50 } ``` *** ### 幾個要注意的地方 - **只抓公開資料**。不需要登入、不需要 HKTVmall 帳號，也不會存取任何需要驗證才看得到的內容。 - **不用登入 / 不用 API token**。填好 input 就能跑，沒有任何金鑰要設定。搜尋用的 Algolia 金鑰是 HKTVmall 前端公開發給每個瀏覽器的 search-only key，每次 Run 都會即時從搜尋頁重新抽取（不寫死），金鑰輪替不影響爬蟲運作。 - **`product_url` 誠實聲明**：絕大多數命中都帶有 HKTVmall 官方商品頁網址（實測樣本 100% 有此欄位），但若少數搜尋結果缺少此欄位，爬蟲會退回組一個「用商品代碼查詢的搜尋頁連結」而非商品詳情頁，這種情況會影響到的是連結的精確度、不影響其他欄位資料的正確性。 - **對電商站友善**。每個 domain 併發請求會自然受限（依關鍵字循序抓取），遇到失敗會用指數退避重試最多 3 次，連續 5 頁拿不到新資料就自動停止，不會空轉燒錢。 - **同一商品若命中多個關鍵字，會以不同 `keyword`/`source_query` 各出一列（依查詢計費）**。 - **逐則評論內容（reviews）規劃於後續版本**，目前版本只有 `search` 模式的彙總 `average_rating` / `number_of_reviews`。 *** ### 常見問題 **Q: 為什麼有些欄位是 `null`？** HKTVmall 的商品資料本身就不是每個商品都完整（例如部分商品沒有折扣紀錄、沒有評論），凡是原始資料缺值，爬蟲一律誠實回 `null`，不會編造資料。 **Q: 費用怎麼算？** 每次 Run 啟動收一次 `actor-start`（$0.005）；每筆商品列表收 `search-listing`（$0.002）。都是資料成功寫入 dataset 後才收費，Run log 會印出實際收費筆數。 **Q: 抓不到資料怎麼辦？** 先確認關鍵字有沒有打錯字、換個更常見的關鍵字試試（中英文都支援）。爬蟲連續 5 頁拿不到新資料就會自己停並在 log 寫原因，不會空轉燒錢。 **Q: `category_path` 是什麼？** 這是 HKTVmall 的分類階層（主分類 → 子分類，最多到第 4 層），各層以 `/` 串接，缺的層級會自動略過。 **Q: 支援商品詳情頁（單一商品完整資料）嗎？** v1.0 只做搜尋列表模式。若後續有明確需求證明，商品詳情模式（`detail`）會規劃在 v1.1 補上。 *** ### 部署 ```bash apify login # 首次:貼上 Apify token(不會寫進 repo) apify push # 建置並上傳到 Apify Store ``` 上架後在 Apify Console 的 Monetization 設定 PPE 事件單價: `actor-start` $0.005、`search-listing` $0.002。 *** ### 免責聲明 本爬蟲只收集 HKTVmall **公開可見**的商品搜尋資料，資料僅供研究與個人用途使用，不用於任何未經授權的商業轉售。使用前請自行確認符合 HKTVmall 服務條款與當地法規。對於資料的正確性、即時性或完整性，本 Actor 不做任何保證，商品價格與庫存請以 HKTVmall 官網當下顯示為準。 *** *HKTVmall 爬蟲、香港網購、電商商品、價格監控、庫存查詢、香港電商數據* # Actor input Schema ## `mode` (type: `string`): v1.0 只支援關鍵字搜尋模式。 ## `keywords` (type: `array`): 搜尋模式的關鍵字。例如:咖啡、洗髮精、尿片。一個概念一個關鍵字最準。 ## `bulkInput` (type: `string`): **一行一個**,按 Enter 換行,不要加引號或逗號。當關鍵字用,執行時自動併入上面的關鍵字欄位。從 Google Sheet / Excel 複製一整欄貼進來最快。 ## `maxItems` (type: `integer`): 每個關鍵字最多抓幾筆。越多費用越高。 ## `proxyConfiguration` (type: `object`): HKTVmall 對 datacenter 請求友善,預設不用 proxy 即可運作。只有大量抓取遇到被擋時才建議開啟。 ## Actor input object example ```json { "mode": "search", "keywords": [ "coffee" ], "maxItems": 50, "proxyConfiguration": { "useApifyProxy": false } } ``` # Actor output Schema ## `dataset` (type: `string`): No description # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "mode": "search", "keywords": [ "coffee" ] }; // Run the Actor and wait for it to finish const run = await client.actor("claude_code_reviewer/hktvmall-scraper").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "mode": "search", "keywords": ["coffee"], } # Run the Actor and wait for it to finish run = client.actor("claude_code_reviewer/hktvmall-scraper").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "mode": "search", "keywords": [ "coffee" ] }' | apify call claude_code_reviewer/hktvmall-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=claude_code_reviewer/hktvmall-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "HKTVmall 爬蟲｜香港電商商品、價格、庫存、評分一鍵匯出（免 API）", "description": "免登入抓 HKTVmall（香港最大網購）商品：售價、庫存、評分、品牌、分類與商品編號，輸出 JSON／CSV／Excel。香港電商選品、比價、庫存監控必備。", "version": "1.0", "x-build-id": "YfUQeJk00KyK3kL4k" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/claude_code_reviewer~hktvmall-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-claude_code_reviewer-hktvmall-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/claude_code_reviewer~hktvmall-scraper/runs": { "post": { "operationId": "runs-sync-claude_code_reviewer-hktvmall-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/claude_code_reviewer~hktvmall-scraper/run-sync": { "post": { "operationId": "run-sync-claude_code_reviewer-hktvmall-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "properties": { "mode": { "title": "🎯 模式", "enum": [ "search" ], "type": "string", "description": "v1.0 只支援關鍵字搜尋模式。", "default": "search" }, "keywords": { "title": "🔎 關鍵字", "maxItems": 50, "uniqueItems": true, "type": "array", "description": "搜尋模式的關鍵字。例如:咖啡、洗髮精、尿片。一個概念一個關鍵字最準。", "items": { "type": "string" } }, "bulkInput": { "title": "📋 批量貼上", "type": "string", "description": "**一行一個**,按 Enter 換行,不要加引號或逗號。當關鍵字用,執行時自動併入上面的關鍵字欄位。從 Google Sheet / Excel 複製一整欄貼進來最快。" }, "maxItems": { "title": "📊 最多抓幾筆", "minimum": 1, "maximum": 500, "type": "integer", "description": "每個關鍵字最多抓幾筆。越多費用越高。", "default": 50 }, "proxyConfiguration": { "title": "🌐 Proxy (進階,通常不用開)", "type": "object", "description": "HKTVmall 對 datacenter 請求友善,預設不用 proxy 即可運作。只有大量抓取遇到被擋時才建議開啟。", "default": { "useApifyProxy": false } } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```