Aller au contenu
FR
Obtenir une clé API
Parcourir la documentation

Exemples

YouTube Search API : guide Python

Recherchez sur YouTube par mot-clé, filtrez les vidéos et exportez des fichiers CSV, JSONL et d’identifiants dédupliqués avec Python.

Sur cette page

Rechercher sur YouTube avec 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"])

Une vraie réponse de recherche

Voici les trois premiers des 20 résultats capturés dans la démo publique pour « battery recycling process » le 15 novembre 2026. L’enregistrement conserve six champs par vidéo. Lancez la démo en direct pour des résultats récents.

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

Réunir plusieurs recherches dans un jeu de données

Le kit Python enregistre les réponses terminées, déduplique les identifiants et conserve chaque requête et position correspondante. Reprenez avec les mêmes options et resume=True pour réutiliser les recherches terminées.

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

Recherche standard ou étendue ?

La recherche standard accepte 1–20 résultats par requête. La recherche étendue en accepte 1–700 à un tarif distinct. Les deux utilisent 20 par défaut ; max_results est une limite, pas un nombre garanti.

Filtrez par durée, date de mise en ligne, ordre et disponibilité des sous-titres. Ces endpoints n’exposent ni numéro de page ni jeton de continuation. Utilisez la recherche étendue pour davantage de résultats.

Obtenir davantage de résultats avec la recherche étendue
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")

Restreindre la recherche si nécessaire

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

Choisir les vidéos à enrichir

Utilisez video-ids.txt comme entrée pour les métadonnées, transcriptions ou téléchargements en masse. Examinez les vidéos candidates avant de sélectionner les identifiants à enrichir ou livrer.

Tâche suivanteUtilisation des identifiants sélectionnés
Vérifier les informations d’une vidéoRécupérez les métadonnées d’un identifiant sélectionné. Consultez transcriptLanguages avant de demander une piste de sous-titres précise.
Résumer le contenu parléLisez une transcription ou une piste de sous-titres disponible et citez les horodatages. Ne résumez pas la vidéo à partir de sa seule description dans les résultats de recherche.
Enrichir plusieurs vidéosUtilisez selected-video-ids.txt comme entrée du guide d’enrichissement. Les métadonnées et les sous-titres font l’objet de requêtes distinctes, avec leurs propres autorisations et coûts.

Exemple REST complet avec réponses enregistrées

Facultatif : utilisez directement requests ou cURL. Enregistrez request.json à côté du script. Placez votre clé API dans la variable key de Python ; Bash lit FLASHDATA_API_KEY ou demande la clé. Chaque nouveau dossier de sortie soumet une recherche.

Utilisez search-001 comme dossier de sortie. Un nouveau dossier déclenche une recherche facturable ; un dossier existant est lu localement. Le script conserve la requête exacte, la réponse et la consommation.

youtube-search/request.json
{
  "source": "youtube_search",
  "query": "battery recycling process explained",
  "params": {
    "max_results": 5,
    "filters": {
      "type": "video"
    }
  }
}
Installer dans votre environnement 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")
Exécuter depuis youtube-search/
python search.py search-001

Résoudre les problèmes de recherche

ProblèmeSolution
Moins de cinq vidéos, ou aucuneLa recherche peut avoir réussi. Affinez la requête ou retirez un filtre restrictif. totalResults décrit cette réponse, pas le nombre total de vidéos YouTube correspondantes.
401 / 403 / 402Vérifiez respectivement la clé, l’autorisation youtube_search et le solde. Corrigez la cause avant de créer une nouvelle tentative.
429Pour HTTP 429, respectez Retry-After. Le kit ne réessaie que les réponses 429 explicites, deux fois au maximum par défaut, et s’arrête si le délai dépasse 60 secondes. Les exemples SDK direct et REST ne réessaient pas automatiquement.
Délai dépassé, erreur 5xx ou dossier incompletConservez les fichiers et consultez l’historique de la console avant de soumettre à nouveau. Le kit ne renvoie pas automatiquement une requête dont le résultat est inconnu.