# YouTube Search API: Python rehberi

Python ile YouTube'da anahtar kelimeyle arama yapın, videoları filtreleyin ve yinelenmeyen CSV, JSONL ve video kimliği dosyaları oluşturun.

Canonical referans: https://flashdata.dev/tr/docs/guides/youtube-search-recipe
İnceleme: 2026-11-16 Tarafından FlashData

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

## Python ile YouTube'da arama

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

- [API anahtarı alın](https://flashdata.dev/signup)
- [Canlı aramayı deneyin](https://flashdata.dev/tr/products/youtube-data#playground)

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

## Gerçek bir arama yanıtı

Bunlar, 15 Kasım 2026'da herkese açık demoda “battery recycling process” sorgusu için alınan 20 sonucun ilk üçüdür. Kayıt video başına altı alanı korur. Güncel sonuçlar için canlı demoyu çalıştırın.

### 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
  }
]
```

- [Gerçek bir arama yanıtı](https://github.com/flashdatadev/youtube-search-api/blob/main/src/flashdata_search/recorded/search.json)

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

## Birden fazla aramayı veri kümesinde toplama

Python araç seti tamamlanan yanıtları kaydeder, yinelenen video kimliklerini kaldırır ve eşleşen her sorguyu ve sonuç sırasını korur. Tamamlanan aramaları yeniden kullanmak için aynı seçeneklerle ve resume=True ile devam edin.

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

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

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

## Standart mı, genişletilmiş arama mı?

Standart arama sorgu başına 1–20 sonuç kabul eder. Genişletilmiş arama ayrı bir ücretle 1–700 kabul eder. İkisinin de varsayılanı 20'dir; max_results bir sınırdır, sonuç sayısı garantisi değildir.

Süre, yükleme tarihi, sıralama ve altyazı filtrelerini kullanın. Bu uç noktalar sayfa numarası veya devam belirteci sunmaz. Daha fazla sonuç için genişletilmiş aramayı kullanın.

### Genişletilmiş aramayla daha fazla sonuç alma

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

- [When to use Extended Search](https://flashdata.dev/tr/docs/sources/youtube_search_extended/reference.md)
- [Arama fiyatlarını karşılaştırın](https://flashdata.dev/tr/products/youtube-data#choose-api)

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

## Narrow the search when needed

### 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",
        },
    )
```

- [Tüm arama filtreleri](https://flashdata.dev/tr/docs/sources/youtube_search/reference.md#parameters)

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

## Bir sonraki zenginliğe neyin zenginleştirilmesini seçin

video-ids.txt dosyasını meta veri, transkript veya toplu indirme iş akışlarına girdi olarak kullanın. Zenginleştirilecek veya teslim edilecek kimlikleri seçmeden önce aday videoları inceleyin.

| Bir sonraki göreviniz | Seçilen IDs'u kullanın |
| --- | --- |
| Bir videonun ayrıntılarını kontrol edin | seçilmiş bir ID için Fetch metadata. Inspect transcriptLanguages, belirli bir satır izi talep etmeden önce. |
| Summarize konuşma içeriği | Mevcut bir transkript veya satır izi okuyun ve zamanları ayırın. Videoyu yalnızca arama açıklamasından özetlemeyin. |
| En zengin birkaç video | selected-video-ids.txt'u zenginleştirme kılavuzuna giriş olarak kullanın. Metadata ve kuyruklar kendi izni ve suçlamaları ile ayrı taleplerdir. |

- [One video's metadata](https://flashdata.dev/tr/docs/guides/video-metadata-recipe/reference.md)
- [Summarize a video with alıntıs](https://flashdata.dev/tr/docs/guides/youtube-summary/reference.md)
- [En zengin seçilmiş video IDs](https://flashdata.dev/tr/docs/guides/enrich-youtube-videos/reference.md)
- [Bulk API](https://flashdata.dev/tr/docs/reference/bulk-processing/reference.md?source=youtube_download#playground)

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

## Yanıtları kaydeden tam REST örneği

İsteğe bağlı olarak requests veya cURL'ü doğrudan kullanın. request.json dosyasını betiğin yanına kaydedin. API anahtarını Python'daki key değişkenine yazın; Bash, FLASHDATA_API_KEY değerini okur veya anahtarı sorar. Her yeni çıktı klasörü bir arama gönderir.

Arama-001 ile çıktı klasörü olarak çalıştırın. Yeni bir klasör bir faturalanabilir arama sunar; mevcut bir klasör yerel olarak okunur. Senaryo tam olarak sunulan istek, yanıt ve kullanım tutar.

### youtube-search/request.json

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

### Python

#### Python ortamınıza yükleme

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

#### youtube-search / Run from youtube-search /

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


### Bash

#### Araçlarınızı kontrol edin

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

#### youtube-search / Run from youtube-search /

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



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

## Aramanın dikkatine ihtiyacı varsa

| Ne oldu? | Yapılacak işlem |
| --- | --- |
| Beş videodan daha az, ya da hiçbiri | Bu başarılı bir arama olabilir. Soruyu reddetmek veya kısıtlayıcı bir filtre kaldırmak. totalResults bu cevabı açıklar, YouTube videolarının toplam sayısı değil. |
| 401 / 403 / 402 | Anahtarı kontrol edin, youtube_search izin ve denge, sırasıyla. Yeni bir girişim yaratmadan önce nedeni düzeltin. |
| 429 | HTTP 429 için Retry-After süresini bekleyin. Araç seti yalnızca açık 429 yanıtlarını varsayılan olarak en fazla iki kez yeniden dener ve bekleme 60 saniyeyi aşarsa durur. Doğrudan SDK ve REST örnekleri otomatik yeniden deneme yapmaz. |
| Timeout, 5xx veya eksik bir klasör | Dosyaları koruyun ve yeniden göndermeden önce konsol geçmişini kontrol edin. Araç seti sonucu bilinmeyen istekleri otomatik olarak yeniden göndermez. |

- [Tarih İstek Tarihi](https://flashdata.dev/app/jobs)
- [Hatalar ve durum kodları](https://flashdata.dev/tr/docs/errors/reference.md)
- [YouTube Search API Python araç seti](https://github.com/flashdatadev/youtube-search-api/blob/main/docs/troubleshooting.md)
