# YouTube Search API: panduan Python

Cari YouTube berdasarkan kata kunci, filter video, dan ekspor CSV, JSONL serta ID video tanpa duplikat dengan Python.

Referensi kanonikal: https://flashdata.dev/id/docs/guides/youtube-search-recipe
Diulang: 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 API key](https://flashdata.dev/signup)
- [Coba pencarian langsung](https://flashdata.dev/id/products/youtube-data#playground)

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

## Respons pencarian nyata

Ini adalah tiga hasil pertama dari 20 hasil demo publik untuk “battery recycling process” pada 15 November 2026. Rekaman menyimpan enam kolom per video. Jalankan demo langsung untuk hasil terbaru.

### 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 pencarian nyata](https://github.com/flashdatadev/youtube-search-api/blob/main/src/flashdata_search/recorded/search.json)

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

## Menggabungkan beberapa pencarian menjadi dataset

Toolkit Python menyimpan respons yang selesai, menghapus ID video duplikat, dan mempertahankan setiap kueri serta posisi hasil yang cocok. Lanjutkan dengan opsi yang sama dan resume=True untuk memakai kembali pencarian yang 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
```

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

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

## Pencarian standar atau diperluas?

Pencarian standar menerima 1–20 hasil per kueri. Pencarian diperluas menerima 1–700 dengan tarif terpisah. Keduanya memakai 20 secara default; max_results adalah batas, bukan jumlah hasil yang dijamin.

Gunakan filter durasi, tanggal unggah, urutan, dan subtitel. Endpoint ini tidak menyediakan nomor halaman atau token kelanjutan. Gunakan pencarian diperluas untuk lebih banyak hasil.

### Mengambil lebih banyak hasil dengan pencarian diperluas

```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")
```

- [Kapan memakai Pencarian Diperluas](https://flashdata.dev/id/docs/sources/youtube_search_extended/reference.md)
- [Bandingkan harga pencarian](https://flashdata.dev/id/products/youtube-data#choose-api)

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

## Persempit 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 penyaring pencarian](https://flashdata.dev/id/docs/sources/youtube_search/reference.md#parameters)

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

## Pilih apa yang akan diperkaya selanjutnya

Gunakan video-ids.txt sebagai masukan untuk metadata, transkrip, atau unduhan massal. Tinjau video kandidat sebelum memilih ID untuk diperkaya atau dikirim.

| Tugas berikutnya | Gunakan IDs terpilih untuk |
| --- | --- |
| Periksa rincian video | Ambil metadata untuk ID terpilih. Inspeksi transcriptLanguages sebelum meminta trek judul tertentu. |
| Rangkuman isi yang diucapkan | Baca transkrip yang tersedia atau judul trek dan penanda waktu mengutip. Jangan merangkum video dari deskripsi pencariannya saja. |
| Kembangkan beberapa video | Gunakan selected-video-ids.txt sebagai masukan ke panduan pengayaan. Metadata dan takarir adalah permintaan terpisah dengan izin dan biaya mereka sendiri. |

- [Satu metadata video](https://flashdata.dev/id/docs/guides/video-metadata-recipe/reference.md)
- [Rangkulkan video dengan kutipan](https://flashdata.dev/id/docs/guides/youtube-summary/reference.md)
- [Enrich video terpilih IDs](https://flashdata.dev/id/docs/guides/enrich-youtube-videos/reference.md)
- [Bulk API](https://flashdata.dev/id/docs/reference/bulk-processing/reference.md?source=youtube_download#playground)

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

## Contoh REST lengkap dengan respons tersimpan

Opsional: gunakan requests atau cURL secara langsung. Simpan request.json di samping skrip. Isi kunci API pada variabel key di Python; Bash membaca FLASHDATA_API_KEY atau meminta kunci. Setiap folder keluaran baru mengirim satu pencarian.

Jalankan dengan search-001 sebagai folder keluaran. Folder baru menyerahkan satu pencarian yang dapat ditagih; folder yang ada dibaca secara lokal. Skrip menyimpan permintaan, respon, dan penggunaan yang 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")
```

#### Jalankan dari youtube-cari /

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


### Bash

#### Periksa alat-alatmu

```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"
```

#### Jalankan dari youtube-cari /

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



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

## Jika pencarian membutuhkan perhatian

| Apa yang terjadi? | Yang perlu dilakukan |
| --- | --- |
| Kurang dari lima video, atau tidak ada | Ini bisa menjadi pencarian yang sukses. Ajukan permintaan atau hapus penyaring pembatasan. totalResults menjelaskan respon ini, bukan jumlah yang cocok dengan video YouTube. |
| 401 / 403 / 402 | Periksa kunci, youtube_search izin dan keseimbangan, secara terhormat. Perbaiki penyebabnya sebelum membuat usaha baru. |
| 429 | Untuk HTTP 429, tunggu sesuai Retry-After. Toolkit hanya mengulang respons 429 yang eksplisit, maksimal dua kali secara default, dan berhenti jika penundaan melebihi 60 detik. Contoh SDK langsung dan REST tidak mengulang otomatis. |
| Waktu habis, 5xx atau folder tidak lengkap | Simpan berkas dan periksa riwayat konsol sebelum mengirim lagi. Toolkit tidak mengirim ulang otomatis permintaan yang hasilnya belum diketahui. |

- [Meminta riwayat](https://flashdata.dev/app/jobs)
- [Kesalahan dan kode status](https://flashdata.dev/id/docs/errors/reference.md)
- [Toolkit Python YouTube Search API](https://github.com/flashdatadev/youtube-search-api/blob/main/docs/troubleshooting.md)
