# YouTube Search API: panduan Python

Cari YouTube mengikut kata kunci, tapis video dan eksport CSV, JSONL serta ID video tanpa pendua menggunakan Python.

Referensi boonical: https://flashdata.dev/ms/docs/guides/youtube-search-recipe
Diulas: 2026-11-16 oleh FlashData

<a id="quickstart"></a>

## Mencari YouTube dengan Python

### Python SDK

```bash
python -m pip install -U flashdata
```

### search.py

```python
from flashdata import FlashData

with FlashData(api_key="your-flashdata-api-key") as client:
    result = client.youtube.search(
        "battery recycling process",
        max_results=5,
        filters={"type": "video"},
    )

for video in result["results"][0]["results"]:
    print(video["title"], video["videoId"])
```

- [Dapatkan kunci API](https://flashdata.dev/signup)
- [Cuba carian langsung](https://flashdata.dev/ms/products/youtube-data#playground)

<a id="recorded-response"></a>

## Respons carian sebenar

Ini ialah tiga hasil pertama daripada 20 hasil demo awam untuk “battery recycling process” pada 15 November 2026. Rakaman mengekalkan enam medan bagi setiap video. Jalankan demo langsung untuk hasil terkini.

### results[0].results · 3 / 20

```json
[
  {
    "videoId": "s2xrarUWVRQ",
    "title": "What *Really* happens to used Electric Car Batteries? - (you might be surprised)",
    "channel": "JerryRigEverything",
    "duration": 424,
    "viewCount": 5679251,
    "uploadDate": null
  },
  {
    "videoId": "RW0itbw_ALI",
    "title": "Recycling Batteries",
    "channel": "mbmmllc",
    "duration": 193,
    "viewCount": 91440,
    "uploadDate": null
  },
  {
    "videoId": "dyDoOcBMAHw",
    "title": "Why It's So Hard To Recycle Electric-Car Batteries | World Wide Waste",
    "channel": "Business Insider India",
    "duration": 376,
    "viewCount": 880172,
    "uploadDate": null
  }
]
```

- [Respons carian sebenar](https://github.com/flashdatadev/youtube-search-api/blob/main/src/flashdata_search/recorded/search.json)

<a id="collection"></a>

## Menggabungkan beberapa carian menjadi set data

Kit Python menyimpan respons yang selesai, membuang ID video pendua dan mengekalkan setiap pertanyaan serta kedudukan hasil yang sepadan. Sambung dengan pilihan yang sama dan resume=True untuk menggunakan semula carian selesai.

### Python toolkit

```bash
python -m pip install "https://github.com/flashdatadev/youtube-search-api/releases/download/v0.1.0/flashdata_youtube_search_api-0.1.0-py3-none-any.whl"
```

### search_to_dataset.py

```python
from flashdata_search import SearchClient, collect

with SearchClient(api_key="your-flashdata-api-key") as client:
    summary = collect(
        client,
        ["battery recycling process", "lithium battery recycling plant"],
        "output/batteries",
        max_results=20,
        filters={"duration": "4-20", "subtitles": True},
    )

print(summary["unique_videos"], "unique videos")
# output/batteries: videos.csv, videos.jsonl, video-ids.txt, summary.json
```

- [Kit Python YouTube Search API](https://github.com/flashdatadev/youtube-search-api)

<a id="extended"></a>

## Carian standard atau lanjutan?

Carian standard menerima 1–20 hasil setiap pertanyaan. Carian lanjutan menerima 1–700 pada kadar berasingan. Kedua-duanya menggunakan 20 secara lalai; max_results ialah had, bukan bilangan hasil yang dijamin.

Gunakan penapis tempoh, tarikh muat naik, susunan dan sari kata. Endpoint ini tidak menyediakan nombor halaman atau token sambungan. Gunakan carian lanjutan untuk lebih banyak hasil.

### Dapatkan lebih banyak hasil dengan carian lanjutan

```python
from flashdata import FlashData

with FlashData(api_key="your-flashdata-api-key") as client:
    result = client.youtube.search_extended(
        "battery recycling process",
        max_results=100,
        filters={"type": "video", "duration": "4-20"},
    )

print(len(result["results"][0]["results"]), "returned results")
```

- [Wourdon Bila Menggunakan Pencarian Tambahan](https://flashdata.dev/ms/docs/sources/youtube_search_extended/reference.md)
- [Bandingkan harga carian](https://flashdata.dev/ms/products/youtube-data#choose-api)

<a id="filters"></a>

## Kecilkan pencarian ketika dibutuhkan

### filters

```python
from flashdata import FlashData

with FlashData(api_key="your-flashdata-api-key") as client:
    result = client.youtube.search(
        "battery recycling process",
        max_results=20,
        filters={
            "type": "video",
            "duration": "4-20",
            "subtitles": True,
            "sort_by": "view_count",
        },
    )
```

- [Semua filter pencarian](https://flashdata.dev/ms/docs/sources/youtube_search/reference.md#parameters)

<a id="select"></a>

## Memikul apa yang akan diperkaya selanjutnya

Gunakan video-ids.txt sebagai input untuk metadata, transkrip atau muat turun pukal. Semak video calon sebelum memilih ID untuk diperkaya atau dihantar.

| Tugasmu berikutnya | ** Gunakan IDs yang dipilih untuk |
| --- | --- |
| Periksa rincian video | Data meta metadata Kutip data meta untuk ID terpilih. Periksa transcriptLanguages sebelum meminta jalur kapsi tertentu. |
| Takwidah Summarize content yang diucapkan | KATAKOD Baca transkrip yang tersedia atau track kapsi dan sesi penanda waktu. Jangan meringkas video dari deskripsi pencariannya saja. |
| Memkaya beberapa video | Use selected-video-ids.txt sebagai input untuk panduan pengayaan. Metadata dan kapsi adalah permintaan terpisah dengan izin dan tuntutan mereka sendiri. |

- [Metadata satu video](https://flashdata.dev/ms/docs/guides/video-metadata-recipe/reference.md)
- [Summarize sebuah video dengan kutipan](https://flashdata.dev/ms/docs/guides/youtube-summary/reference.md)
- [Perkaya ID video yang dipilih](https://flashdata.dev/ms/docs/guides/enrich-youtube-videos/reference.md)
- [Bulk API](https://flashdata.dev/ms/docs/reference/bulk-processing/reference.md?source=youtube_download#playground)

<a id="rest"></a>

## Contoh REST penuh dengan respons tersimpan

Pilihan: gunakan requests atau cURL secara terus. Simpan request.json di sebelah skrip. Masukkan kunci API dalam pemboleh ubah key Python; Bash membaca FLASHDATA_API_KEY atau meminta kunci. Setiap folder output baharu menghantar satu carian.

\"Official Run with search-\"001 Sebagai folder output. Sebuah folder baru mengajukan satu pencarian yang dapat diterima; folder yang ada telah dibaca secara lokal. Naskah menyimpan permintaan, tanggapan dan penggunaan yang diajukan dengan tepat.

### youtube-search/request.json

```json
{
  "source": "youtube_search",
  "query": "battery recycling process explained",
  "params": {
    "max_results": 5,
    "filters": {
      "type": "video"
    }
  }
}
```

### Python

#### Pasang di lingkungan Python anda

```bash
python -m pip install requests
```

#### youtube-search/search.py

```python
import argparse
import json
import re
from datetime import datetime, timezone
from pathlib import Path

import requests

parser = argparse.ArgumentParser()
parser.add_argument("folder", help="New output folder, or an existing saved search")
out = Path(parser.parse_args().folder)

if not out.exists():
    body = Path("request.json").read_bytes()
    request = json.loads(body)
    if (not isinstance(request, dict) or request.get("source") != "youtube_search"
            or not isinstance(request.get("query"), str) or not request["query"].strip()):
        raise SystemExit("request.json must contain youtube_search and a nonempty query")
    key = "your-flashdata-api-key"
    if not key.strip():
        raise SystemExit("An API key is required")
    out.mkdir()
    (out / "request.json").write_bytes(body)
    (out / "requested-at.txt").write_text(
        datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"), encoding="utf-8"
    )
    try:
        response = requests.post(
            "https://data.flashdata.dev/v1/queries/realtime",
            headers={"X-API-Key": key, "Content-Type": "application/json",
                     "Accept": "application/json"},
            data=body, timeout=120, allow_redirects=False,
        )
    except requests.RequestException:
        raise SystemExit(f"Request interrupted. Keep {out} and check History before retrying.")
    (out / "result.json").write_bytes(response.content)
    (out / "response-headers.txt").write_text(
        "\n".join(f"{k}: {v}" for k, v in response.headers.items()), encoding="utf-8"
    )
    (out / "http-status.txt").write_text(str(response.status_code), encoding="utf-8")
else:
    print(f"Reading saved response from {out}; no API call.")

if not (out / "http-status.txt").exists():
    raise SystemExit("Incomplete attempt. Keep the folder and check History before retrying.")
status = (out / "http-status.txt").read_text().strip()
if status != "200":
    raise SystemExit(f"HTTP {status}: inspect {out}/result.json and response-headers.txt")
data = json.loads((out / "result.json").read_bytes())
if not isinstance(data, dict) or data.get("source") != "youtube_search" or data.get("status") != "done":
    raise SystemExit("Search did not finish successfully; inspect result.json")
pages = data.get("results")
if not isinstance(pages, list) or any(
    not isinstance(page, dict) or not isinstance(page.get("results"), list) for page in pages
):
    raise SystemExit("Expected results[].results arrays; inspect result.json")

videos, seen, skipped, duplicates = [], set(), 0, 0
for page in pages:
    for row in page["results"]:
        if not isinstance(row, dict):
            raise SystemExit("Expected video result objects; inspect result.json")
        video_id = row.get("videoId")
        if not isinstance(video_id, str) or not re.fullmatch(r"[A-Za-z0-9_-]{11}", video_id):
            skipped += 1
        elif video_id in seen:
            duplicates += 1
        else:
            seen.add(video_id)
            videos.append({**row, "url": "https://www.youtube.com/watch?v=" + video_id})
record = {
    "request": json.loads((out / "request.json").read_bytes()),
    "requested_at": (out / "requested-at.txt").read_text().strip(),
    "usage": data.get("usage"), "video_count": len(videos),
    "skipped_items": skipped, "duplicates_removed": duplicates, "result_file": "result.json",
}
for filename, value in (("videos.json", videos), ("record.json", record)):
    (out / filename).write_text(json.dumps(value, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
(out / "video-ids.txt").write_text("".join(v["videoId"] + "\n" for v in videos), encoding="utf-8")
print(f"Saved {len(videos)} videos to {out}/videos.json and video-ids.txt")
```

#### Lari dari pencarian-mutube/

```bash
python search.py search-001
```


### Bash

#### Periksa peralatanmu

```bash
curl --version
jq --version
```

#### youtube-search/search.sh

```bash
#!/usr/bin/env bash
set -euo pipefail
out="${1:?Usage: bash search.sh OUTPUT_FOLDER}"

if [[ ! -e "$out" ]]; then
  jq -e '.source == "youtube_search" and
    (.query | if type == "string" then test("\\S") else false end)' request.json > /dev/null
  if [[ -z "${FLASHDATA_API_KEY:-}" ]]; then
    read -r -s -p "FlashData API key: " FLASHDATA_API_KEY
    printf '\n'
  fi
  : "${FLASHDATA_API_KEY:?An API key is required}"
  mkdir -- "$out"
  cp request.json "$out/request.json"
  date -u +'%Y-%m-%dT%H:%M:%SZ' > "$out/requested-at.txt"
  curl --fail-with-body --silent --show-error --max-time 120 \
    --request POST 'https://data.flashdata.dev/v1/queries/realtime' \
    --header "X-API-Key: $FLASHDATA_API_KEY" \
    --header 'Content-Type: application/json' --header 'Accept: application/json' \
    --data-binary "@$out/request.json" \
    --dump-header "$out/response-headers.txt" --output "$out/result.json" \
    --write-out '%{http_code}' > "$out/http-status.txt" || {
      printf 'Request failed. Keep %s and inspect its saved files before retrying.\n' "$out" >&2
      exit 1
    }
else
  printf 'Reading saved response from %s; no API call.\n' "$out"
fi

if [[ ! -f "$out/http-status.txt" ]] || [[ "$(cat "$out/http-status.txt")" != 200 ]]; then
  printf 'Incomplete or failed attempt. Inspect the saved files and History before retrying.\n' >&2
  exit 1
fi
selection=$(jq -e '
  if .source != "youtube_search" or .status != "done" or (.results | type) != "array"
  then error("Expected a successful youtube_search response") else . end
  | [.results[] | if (.results | type) != "array"
      then error("Expected a video list") else .results[] end
      | if type != "object" then error("Expected video result objects") else . end]
  | reduce .[] as $row ({seen: {}, videos: [], skipped: 0, duplicates: 0};
      if ($row.videoId | if type == "string" then length == 11 and test("^[A-Za-z0-9_-]{11}$") else false end) == false
      then .skipped += 1
      elif .seen[$row.videoId] then .duplicates += 1
      else .seen[$row.videoId] = true
        | .videos += [$row + {url: ("https://www.youtube.com/watch?v=" + $row.videoId)}] end)
  | del(.seen)' "$out/result.json")
printf '%s' "$selection" | jq '.videos' > "$out/videos.json"
jq -r '.[].videoId' "$out/videos.json" > "$out/video-ids.txt"
jq --slurpfile request "$out/request.json" --argjson selection "$selection" \
  --arg requested_at "$(tr -d '\r\n' < "$out/requested-at.txt")" \
  '{request: $request[0], requested_at: $requested_at, usage,
    video_count: ($selection.videos | length), skipped_items: $selection.skipped,
    duplicates_removed: $selection.duplicates, result_file: "result.json"}' \
  "$out/result.json" > "$out/record.json"
printf 'Saved %s videos to %s/videos.json and video-ids.txt\n' "$(jq length "$out/videos.json")" "$out"
```

#### Lari dari pencarian-mutube/

```bash
bash search.sh search-001
```



<a id="recover"></a>

## Jika pencarian perlu perhatian

| Apa yang terjadi? | Tindakan |
| --- | --- |
| Lebih sedikit dari lima video, atau tidak ada | Ini bisa menjadi pencarian yang sukses. Diafinief kueri atau buang filter pembatasan. totalResults menggambarkan respon ini, bukan jumlah total video YouTube yang cocok. |
| 401 / 403 / 402 | Periksa kuncinya, izin dan keseimbangan youtube_search. Fix penyebab sebelum menciptakan upaya baru. |
| 429 | Untuk HTTP 429, tunggu mengikut Retry-After. Kit hanya mencuba semula respons 429 yang jelas, paling banyak dua kali secara lalai, dan berhenti jika tempoh menunggu melebihi 60 saat. Contoh SDK terus dan REST tidak mencuba semula secara automatik. |
| Masa habis '%s', 5xx atau folder tidak lengkap | Simpan fail dan semak sejarah konsol sebelum menghantar semula. Kit tidak menghantar semula secara automatik permintaan yang keputusannya tidak diketahui. |

- [Sejarah permintaan](https://flashdata.dev/app/jobs)
- [Ralat dan kod status](https://flashdata.dev/ms/docs/errors/reference.md)
- [Kit Python YouTube Search API](https://github.com/flashdatadev/youtube-search-api/blob/main/docs/troubleshooting.md)
