# 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:** 4 total users, 2 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 web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — 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 '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_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 '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# 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 <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/hNSkmA6EKekhRP3FK/builds/YfUQeJk00KyK3kL4k/openapi.json