# YouTube Search API: Python-Anleitung

Durchsuche YouTube nach Stichwörtern, filtere Videos und exportiere deduplizierte CSV-, JSONL- und Video-ID-Dateien mit Python.

Kanonische Referenz: https://flashdata.dev/de/docs/guides/youtube-search-recipe
Test: 2026-11-16 von FlashData

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

## YouTube mit Python durchsuchen

### 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-Schlüssel erstellen](https://flashdata.dev/signup)
- [Live-Suche ausprobieren](https://flashdata.dev/de/products/youtube-data#playground)

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

## Eine echte Suchantwort

Dies sind die ersten drei von 20 Ergebnissen aus der öffentlichen Demo für „battery recycling process“ vom 15. November 2026. Die Aufzeichnung enthält sechs Felder pro Video. Aktuelle Ergebnisse erhältst du über die Live-Demo.

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

- [Eine echte Suchantwort](https://github.com/flashdatadev/youtube-search-api/blob/main/src/flashdata_search/recorded/search.json)

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

## Mehrere Suchen zu einem Datensatz zusammenführen

Das Python-Toolkit speichert abgeschlossene Antworten, entfernt doppelte Video-IDs und erhält jede passende Suchanfrage samt Position. Nutze dieselben Optionen und resume=True, um abgeschlossene Suchen wiederzuverwenden.

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

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

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

## Standard- oder erweiterte Suche?

Die Standardsuche erlaubt 1–20 Ergebnisse pro Anfrage. Die erweiterte Suche erlaubt 1–700 zu einem eigenen Tarif. Beide verwenden standardmäßig 20; max_results ist eine Obergrenze, keine garantierte Ergebniszahl.

Grenze die Suche nach Dauer, Upload-Datum, Sortierung und Untertiteln ein. Diese Endpunkte bieten weder Seitennummern noch Fortsetzungstoken. Nutze die erweiterte Suche für mehr Ergebnisse.

### Mehr Ergebnisse mit der erweiterten Suche abrufen

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

- [Wann Sie Extended Search verwenden sollten](https://flashdata.dev/de/docs/sources/youtube_search_extended/reference.md)
- [Suchpreise vergleichen](https://flashdata.dev/de/products/youtube-data#choose-api)

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

## Schränken Sie die Suche ein, wenn nötig

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

- [Alle Suchfilter](https://flashdata.dev/de/docs/sources/youtube_search/reference.md#parameters)

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

## Wählen Sie, was als nächstes zu bereichern

Nutze video-ids.txt für Metadaten-, Transkript- oder Massendownload-Workflows. Prüfe die Kandidaten, bevor du die anzureichernden oder auszuliefernden IDs auswählst.

| Ihre nächste Aufgabe | Verwenden Sie den ausgewählten IDs für |
| --- | --- |
| Überprüfen Sie die Details eines Videos | Abrufen von Metadaten für ein ausgewähltes ID. Überprüfen Sie transcriptLanguages, bevor Sie einen bestimmten Untertitel anfordern. |
| Zusammenfassen von gesprochenem Inhalt | Lesen Sie eine verfügbare Transkript oder Beschriftung Track und zitieren Zeitstempel. Fassen Sie das Video nicht allein aus seiner Suchbeschreibung zusammen. |
| Mehrere Videos anreichern | Verwenden Sie selected-video-ids.txt als Eingabe für das Anreicherungshandbuch. Metadaten und Bildunterschriften sind separate Anfragen mit eigenen Berechtigungen und Gebühren. |

- [Metadaten eines Videos](https://flashdata.dev/de/docs/guides/video-metadata-recipe/reference.md)
- [Fasse ein Video mit Zitaten zusammen](https://flashdata.dev/de/docs/guides/youtube-summary/reference.md)
- [Anreichern ausgewähltes Video IDs](https://flashdata.dev/de/docs/guides/enrich-youtube-videos/reference.md)
- [Bulk API](https://flashdata.dev/de/docs/reference/bulk-processing/reference.md?source=youtube_download#playground)

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

## Vollständiges REST-Beispiel mit gespeicherten Antworten

Optional: requests oder cURL direkt verwenden. Speichere request.json neben dem Skript. Trage den API-Schlüssel in die Python-Variable key ein; Bash liest FLASHDATA_API_KEY oder fragt danach. Jeder neue Ausgabeordner sendet eine Suche.

Führen Sie mit search-001 als Ausgabeordner aus. Ein neuer Ordner sendet eine abrechenbare Suche; ein vorhandener Ordner wird lokal gelesen. Das Skript behält die genaue eingereichte Anfrage, Antwort und Nutzung.

### youtube-search/request.json

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

### Python

#### Installieren Sie in Ihrer Python-Umgebung

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

#### Laufen Sie von youtube-search/

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


### Bash

#### Überprüfen Sie Ihre Tools

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

#### Laufen Sie von youtube-search/

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



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

## Wenn die Suche Aufmerksamkeit braucht

| Was passierte | Lösung |
| --- | --- |
| Weniger als fünf Videos oder keine | Dies kann eine erfolgreiche Suche sein. Verfeinern Sie die Abfrage oder entfernen Sie einen einschränkenden Filter. totalResults beschreibt diese Antwort, nicht die Gesamtzahl der übereinstimmenden YouTube Videos. |
| 401 / 403 / 402 | Überprüfen Sie den Schlüssel, youtube_search Berechtigung und Balance, beziehungsweise. Beheben Sie die Ursache, bevor Sie einen neuen Versuch erstellen. |
| 429 | Warte bei HTTP 429 gemäß Retry-After. Das Toolkit wiederholt nur ausdrückliche 429-Antworten, standardmäßig höchstens zweimal, und stoppt bei Wartezeiten über 60 Sekunden. Die direkten SDK- und REST-Beispiele wiederholen nicht automatisch. |
| Timeout, 5xx oder ein unvollständiger Ordner | Behalte die gespeicherten Dateien und prüfe vor erneutem Senden den Konsolenverlauf. Das Toolkit sendet Anfragen mit unbekanntem Ausgang nicht automatisch erneut. |

- [Anfrageverlauf](https://flashdata.dev/app/jobs)
- [Fehler und Statuscodes](https://flashdata.dev/de/docs/errors/reference.md)
- [Python-Toolkit für YouTube Search API](https://github.com/flashdatadev/youtube-search-api/blob/main/docs/troubleshooting.md)
