Explorar documentación
Ejemplos
Busca en YouTube por palabra clave, filtra vídeos y exporta CSV, JSONL e IDs de vídeo sin duplicados con Python.
En esta página
Buscar en YouTube con Python
python -m pip install -U flashdatafrom 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"])
Una respuesta de búsqueda real
Estos son los primeros tres de 20 resultados capturados en la demo pública para «battery recycling process» el 15 de noviembre de 2026. La grabación conserva seis campos por vídeo. Usa la demo en vivo para obtener resultados actuales.
[
{
"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
}
]Crear un conjunto de datos con varias búsquedas
El kit de Python guarda las respuestas completadas, elimina IDs duplicados y conserva cada consulta y posición coincidente. Reanuda con las mismas opciones y resume=True para reutilizar las búsquedas completadas.
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"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
¿Búsqueda estándar o ampliada?
La búsqueda estándar acepta 1–20 resultados por consulta. La ampliada acepta 1–700 con una tarifa distinta. Ambas usan 20 por defecto; max_results es un límite, no un número garantizado de resultados.
Usa filtros de duración, fecha de subida, orden y subtítulos. Estos endpoints no ofrecen número de página ni token de continuación. Usa la búsqueda ampliada para obtener más resultados.
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")
Reducir la búsqueda cuando sea necesario
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",
},
)
Elija qué enriquecer después
Usa video-ids.txt como entrada para metadatos, transcripciones o descargas masivas. Revisa los vídeos candidatos antes de seleccionar los IDs que vas a enriquecer o entregar.
| Su próxima tarea | Utilice el IDs seleccionado para |
|---|---|
| Verifique los detalles del vídeo | Traiga metadatos para un ID seleccionado. Inspeccione transcriptLanguages antes de solicitar una pista de captura específica. |
| Summarize Contenido hablado | Lea una transcripción disponible o pista de captura y cite timestamps. No resumir el vídeo de su descripción de búsqueda por sí solo. |
| Enriquecer varios vídeos | Utilice selected-video-ids.txt como entrada a la guía de enriquecimiento. Los metadatos y las subtítulos son solicitudes separadas con sus propios permisos y cargos. |
Ejemplo REST completo con respuestas guardadas
Opcional: usa requests o cURL directamente. Guarda request.json junto al script. Introduce la clave API en la variable key de Python; Bash lee FLASHDATA_API_KEY o la solicita. Cada carpeta de salida nueva envía una búsqueda.
Ejecutar con search-001 como la carpeta de salida. Una nueva carpeta presenta una búsqueda facturable; una carpeta existente se lee localmente. El script mantiene la solicitud, respuesta y uso exactamente enviado.
{
"source": "youtube_search",
"query": "battery recycling process explained",
"params": {
"max_results": 5,
"filters": {
"type": "video"
}
}
}python -m pip install requestsimport 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")
python search.py search-001curl --version
jq --version#!/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"
bash search.sh search-001Si la búsqueda necesita atención
| Qué pasó. | Qué hacer |
|---|---|
| Menos de cinco vídeos, o ninguno | Esto puede ser una búsqueda exitosa. Refina la consulta o elimina un filtro restrictivo. totalResults describe esta respuesta, no el número total de videos YouTube que coinciden. |
| 401 / 403 / 402 | Compruebe la clave, permiso y equilibrio youtube_search, respectivamente. Arreglar la causa antes de crear un nuevo intento. |
| 429 | Ante HTTP 429, espera el tiempo de Retry-After. El kit solo reintenta respuestas 429 explícitas, dos veces como máximo por defecto, y se detiene si la espera supera 60 segundos. Los ejemplos directos de SDK y REST no reintentan automáticamente. |
| Timeout, 5xx o una carpeta incompleta | Conserva los archivos y consulta el historial de la consola antes de volver a enviar. El kit no reenvía automáticamente una solicitud cuyo resultado se desconoce. |