Salta al contenuto
IT
Ottieni la chiave API
Sfoglia la documentazione

Esempi

YouTube Search API: guida Python

Cerca su YouTube per parola chiave, filtra i video ed esporta CSV, JSONL e ID video senza duplicati con Python.

In questa pagina

Cercare su 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 risposta di ricerca reale

Questi sono i primi tre di 20 risultati acquisiti nella demo pubblica per «battery recycling process» il 15 novembre 2026. La registrazione conserva sei campi per video. Usa la demo dal vivo per risultati aggiornati.

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

Unire più ricerche in un dataset

Il toolkit Python salva le risposte completate, elimina gli ID duplicati e conserva ogni query e posizione corrispondente. Riprendi con le stesse opzioni e resume=True per riutilizzare le ricerche completate.

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

Ricerca standard o estesa?

La ricerca standard accetta 1–20 risultati per query. Quella estesa accetta 1–700 con una tariffa separata. Entrambe usano 20 come valore predefinito; max_results è un limite, non un numero garantito.

Filtra per durata, data di caricamento, ordinamento e sottotitoli. Questi endpoint non espongono numeri di pagina o token di continuazione. Usa la ricerca estesa per più risultati.

Ottenere più risultati con la ricerca estesa
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")

Limitare la ricerca quando necessario

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

Scegli cosa arricchire il prossimo

Usa video-ids.txt come input per metadati, trascrizioni o download in blocco. Esamina i video candidati prima di selezionare gli ID da arricchire o consegnare.

Il tuo prossimo compitoUtilizzare il IDs selezionato per
Controllare i dettagli di un videoPrestare metadati per un ID selezionato. Ispezionare transcriptLanguages prima di richiedere una traccia didascalia specifica.
Summarizzare i contenuti parlatiLeggi una trascrizione disponibile o una traccia didascalia e cite timestamp. Non riassumere il video dalla sua descrizione di ricerca da solo.
Arricchire diversi videoUtilizzare selected-video-ids.txt come input per la guida di arricchimento. I metadati e le didascalie sono richieste separate con i propri permessi e oneri.

Esempio REST completo con risposte salvate

Facoltativo: usa direttamente requests o cURL. Salva request.json accanto allo script. Inserisci la chiave API nella variabile key di Python; Bash legge FLASHDATA_API_KEY o richiede la chiave. Ogni nuova cartella di output invia una ricerca.

Eseguire con ricerca-001 come cartella di uscita. Una nuova cartella presenta una ricerca leggibile; una cartella esistente viene letta localmente. Lo script mantiene l'esatta richiesta, risposta e utilizzo.

youtube-search/request.json
{
  "source": "youtube_search",
  "query": "battery recycling process explained",
  "params": {
    "max_results": 5,
    "filters": {
      "type": "video"
    }
  }
}
Installare nel tuo ambiente 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")
Correre da youtube-search/
python search.py search-001

Se la ricerca ha bisogno di attenzione

Che cosa è successo?Cosa fare
Meno di cinque video, o nessunoQuesta può essere una ricerca di successo. Rifinire la query o rimuovere un filtro restrittivo. totalResults descrive questa risposta, non il numero totale di video YouTube.
401 / 403 / 402Controllare la chiave, youtube_search permesso e equilibrio, rispettivamente. Fissare la causa prima di creare un nuovo tentativo.
429Per HTTP 429, rispetta Retry-After. Il toolkit riprova solo risposte 429 esplicite, al massimo due volte per impostazione predefinita, e si ferma se l’attesa supera 60 secondi. Gli esempi SDK diretti e REST non riprovano automaticamente.
Timeout, 5xx o una cartella incompletaConserva i file e controlla la cronologia della console prima di inviare di nuovo. Il toolkit non reinvia automaticamente richieste dall’esito sconosciuto.