Saltar al contenido
ES
Obtener clave API
Explorar documentación

Ejemplos

YouTube Search API: guía de Python

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 SDK
python -m pip install -U flashdata
search.py
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"])

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.

results[0].results · 3 / 20
[
  {
    "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 toolkit
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
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.

Obtener más resultados con la búsqueda ampliada
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

filters
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 tareaUtilice el IDs seleccionado para
Verifique los detalles del vídeoTraiga metadatos para un ID seleccionado. Inspeccione transcriptLanguages antes de solicitar una pista de captura específica.
Summarize Contenido habladoLea 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ídeosUtilice 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.

youtube-search/request.json
{
  "source": "youtube_search",
  "query": "battery recycling process explained",
  "params": {
    "max_results": 5,
    "filters": {
      "type": "video"
    }
  }
}
Instalar en su entorno Python
python -m pip install requests
youtube-search/search.py
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")
Corre desde youtube-search/
python search.py search-001

Si la búsqueda necesita atención

Qué pasó.Qué hacer
Menos de cinco vídeos, o ningunoEsto 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 / 402Compruebe la clave, permiso y equilibrio youtube_search, respectivamente. Arreglar la causa antes de crear un nuevo intento.
429Ante 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 incompletaConserva 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.