# YouTube 影片關鍵字搜尋 (Beta) (`futurizerush/youtube-video-scraper-zh-tw`) Actor

搜尋 YouTube 並擷取影片資訊，包括標題、描述、觀看次數、頻道資訊等。支援上傳日期、影片長度與排序篩選。適合市場研究、競品分析、內容創作者使用。

- **URL**: https://apify.com/futurizerush/youtube-video-scraper-zh-tw.md
- **Developed by:** [Rush](https://apify.com/futurizerush) (community)
- **Categories:** Videos, AI, Agents
- **Stats:** 5 total users, 0 monthly users, 100.0% runs succeeded, 2 bookmarks
- **User rating**: 5.00 out of 5 stars

## Pricing

from $10.00 / 1,000 results

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## 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.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## YouTube 影片爬蟲

搜尋 YouTube 並擷取影片資訊，包括標題、描述、觀看次數、頻道資訊等。支援上傳日期、影片長度與排序篩選。

### 主要功能

- **進階搜尋篩選** — 依上傳日期（一小時內/今天/本週/本月/今年）、影片長度（短/中/長）及排序方式篩選
- **完整影片描述** — 從每部影片頁面擷取完整描述，而非僅搜尋結果中的片段
- **多關鍵字搜尋** — 一次搜尋多個關鍵字，高效批次處理
- **國家/地區定位** — 支援 30+ 國家的在地化搜尋結果
- **YouTube Shorts 支援** — 可選擇包含或排除 Shorts 短影片
- **自動去重** — 跨關鍵字自動移除重複影片
- **即時進度** — 在 Apify Console 中顯示即時爬取狀態

### 快速開始

1. 前往 [YouTube 影片爬蟲](https://apify.com/futurizerush/youtube-video-scraper-zh-tw) 頁面，點選「免費試用」
2. 輸入搜尋關鍵字
3. 設定篩選條件（選填）
4. 點選「開始」
5. 下載 JSON、CSV、Excel 等格式的結果

### 輸入設定

```json
{
    "searches": ["台灣 美食", "日本 旅遊"],
    "maxResults": 50,
    "maxPerSearch": 20,
    "uploadDate": "week",
    "duration": "medium",
    "sortBy": "viewCount",
    "country": "TW",
    "includeShorts": true
}
```

| 參數 | 類型 | 預設值 | 說明 |
|------|------|--------|------|
| `searches` | string\[] | *必填* | 要在 YouTube 搜尋的關鍵字 |
| `maxResults` | integer | 50 | 所有關鍵字的影片數量上限（1-500） |
| `maxPerSearch` | integer | 20 | 每個關鍵字的影片數量上限（1-100） |
| `uploadDate` | string | "any" | 篩選：any、hour、today、week、month、year |
| `duration` | string | "any" | 篩選：any、short（<4分鐘）、medium（4-20分鐘）、long（>20分鐘） |
| `sortBy` | string | "relevance" | 排序：relevance、date、viewCount、rating |
| `country` | string | "TW" | 兩碼國家代碼，用於在地化搜尋結果 |
| `includeShorts` | boolean | true | 是否包含 YouTube Shorts 短影片 |

### 輸出資料

每部影片包含以下欄位：

```json
{
    "影片ID": "tDGiWn0flK8",
    "標題": "台北必吃 10 家米其林美食",
    "網址": "https://www.youtube.com/watch?v=tDGiWn0flK8",
    "縮圖網址": "https://i.ytimg.com/vi/tDGiWn0flK8/maxresdefault.jpg",
    "時長": "12:34",
    "時長秒數": 754,
    "頻道名稱": "美食頻道",
    "頻道網址": "https://www.youtube.com/@foodchannel",
    "觀看次數": 34000,
    "上傳時間": "3 days ago",
    "描述": "完整影片描述文字...",
    "是否為Short": false,
    "搜尋關鍵字": "台灣 美食",
    "擷取時間": "2026-02-27T10:30:00.000Z"
}
```

| 欄位 | 類型 | 說明 |
|------|------|------|
| `影片ID` | string | YouTube 影片 ID |
| `標題` | string | 影片標題 |
| `網址` | string | 乾淨的影片網址（無追蹤參數） |
| `縮圖網址` | string | 縮圖圖片網址 |
| `時長` | string | 影片長度，格式為 MM:SS 或 HH:MM:SS |
| `時長秒數` | integer | 影片長度（秒） |
| `頻道名稱` | string | 頻道名稱 |
| `頻道網址` | string | 頻道頁面網址 |
| `觀看次數` | integer | 約略觀看次數 |
| `上傳時間` | string | 相對上傳時間（例如 "3 days ago"） |
| `描述` | string | 完整影片描述 |
| `是否為Short` | boolean | 是否為 YouTube Short 短影片 |
| `搜尋關鍵字` | string | 找到此影片的搜尋關鍵字 |
| `擷取時間` | string | 擷取時間（ISO 8601 格式） |

### 使用情境

- **市場研究** — 分析熱門話題與競爭對手內容
- **內容策略** — 尋找靈感並追蹤相關影片表現
- **學術研究** — 收集社群媒體研究資料
- **品牌監測** — 追蹤品牌相關影片與互動
- **SEO 分析** — 研究關鍵字與影片優化策略

### 運作方式

1. 爬蟲依據您的關鍵字和篩選條件搜尋 YouTube
2. 捲動搜尋結果頁面以收集更多影片
3. 逐一造訪影片頁面以擷取完整描述
4. 自動去重後，逐筆將結果儲存至 Dataset
5. 支援平台遷移恢復，可從中斷處繼續爬取

### 限制說明

- 觀看次數為約略值（例如 "1.2M" → 1200000）
- 上傳時間為相對值（"3 days ago"），非精確日期
- 大量爬取時 YouTube 可能限速
- 每次執行最多 500 部影片，每個關鍵字最多 100 部

### 常見問題

**Q: 為什麼觀看次數是約略值？**
A: YouTube 搜尋結果顯示縮寫的觀看次數（例如 "1.2M views"）。爬蟲將其轉換為數字，可能與精確值略有差異。

**Q: 可以搜尋中文關鍵字嗎？**
A: 可以！您可以輸入任何語言的關鍵字。搜尋結果取決於您的關鍵字語言和所選國家/地區。

**Q: 爬取中斷怎麼辦？**
A: 結果會逐筆儲存。如果爬取中斷，所有已儲存的影片都會保留在您的 Dataset 中。爬蟲也支援遷移恢復功能。

**Q: 如何取得特定國家的搜尋結果？**
A: 使用 `country` 參數搭配兩碼國家代碼（例如 "TW" 台灣、"JP" 日本、"US" 美國）。

***

YouTube 影片爬蟲 — 穩定可靠的 YouTube 影片資料擷取工具。

*關鍵字: youtube scraper, youtube 爬蟲, 影片爬蟲, youtube search, video scraper, video metadata, youtube api alternative, apify actor, 台灣, 繁體中文, zh-tw*

# Actor input Schema

## `searches` (type: `array`):

輸入要在 YouTube 搜尋的關鍵字（每行一個）

## `maxResults` (type: `integer`):

所有關鍵字的影片數量上限

## `maxPerSearch` (type: `integer`):

每個搜尋關鍵字的影片數量上限

## `uploadDate` (type: `string`):

依上傳日期篩選影片

## `duration` (type: `string`):

依影片長度篩選

## `sortBy` (type: `string`):

搜尋結果排序方式

## `country` (type: `string`):

選擇國家以獲得在地化搜尋結果

## `includeShorts` (type: `boolean`):

在結果中包含 YouTube Shorts 短影片

## Actor input object example

```json
{
  "searches": [
    "台灣 美食"
  ],
  "maxResults": 20,
  "maxPerSearch": 10,
  "uploadDate": "any",
  "duration": "any",
  "sortBy": "relevance",
  "country": "TW",
  "includeShorts": true
}
```

# Actor output Schema

## `overview` (type: `string`):

No description

## `details` (type: `string`):

No description

## `allResults` (type: `string`):

No description

## `runSummary` (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 = {
    "searches": [
        "台灣 美食"
    ],
    "maxResults": 20,
    "maxPerSearch": 10,
    "uploadDate": "any",
    "duration": "any",
    "sortBy": "relevance",
    "country": "TW",
    "includeShorts": true
};

// Run the Actor and wait for it to finish
const run = await client.actor("futurizerush/youtube-video-scraper-zh-tw").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 = {
    "searches": ["台灣 美食"],
    "maxResults": 20,
    "maxPerSearch": 10,
    "uploadDate": "any",
    "duration": "any",
    "sortBy": "relevance",
    "country": "TW",
    "includeShorts": True,
}

# Run the Actor and wait for it to finish
run = client.actor("futurizerush/youtube-video-scraper-zh-tw").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "searches": [
    "台灣 美食"
  ],
  "maxResults": 20,
  "maxPerSearch": 10,
  "uploadDate": "any",
  "duration": "any",
  "sortBy": "relevance",
  "country": "TW",
  "includeShorts": true
}' |
apify call futurizerush/youtube-video-scraper-zh-tw --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,futurizerush/youtube-video-scraper-zh-tw"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

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