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

Riferimento canonico: https://flashdata.dev/it/docs/guides/youtube-search-recipe
Recensito: 2026-11-16 da FlashData

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

## Cercare su YouTube con Python

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

- [Ottieni una chiave API](https://flashdata.dev/signup)
- [Prova la ricerca dal vivo](https://flashdata.dev/it/products/youtube-data#playground)

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

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

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

- [Una risposta di ricerca reale](https://github.com/flashdatadev/youtube-search-api/blob/main/src/flashdata_search/recorded/search.json)

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

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

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

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

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

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

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

- [Quando usare la ricerca estesa](https://flashdata.dev/it/docs/sources/youtube_search_extended/reference.md)
- [Confronta i prezzi di ricerca](https://flashdata.dev/it/products/youtube-data#choose-api)

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

## Limitare la ricerca quando necessario

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

- [Tutti i filtri di ricerca](https://flashdata.dev/it/docs/sources/youtube_search/reference.md#parameters)

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

## 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 compito | Utilizzare il IDs selezionato per |
| --- | --- |
| Controllare i dettagli di un video | Prestare metadati per un ID selezionato. Ispezionare transcriptLanguages prima di richiedere una traccia didascalia specifica. |
| Summarizzare i contenuti parlati | Leggi una trascrizione disponibile o una traccia didascalia e cite timestamp. Non riassumere il video dalla sua descrizione di ricerca da solo. |
| Arricchire diversi video | Utilizzare 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. |

- [I metadati di un video](https://flashdata.dev/it/docs/guides/video-metadata-recipe/reference.md)
- [Summarizzare un video con citazioni](https://flashdata.dev/it/docs/guides/youtube-summary/reference.md)
- [Arricchisce il video selezionato IDs](https://flashdata.dev/it/docs/guides/enrich-youtube-videos/reference.md)
- [Bulk API](https://flashdata.dev/it/docs/reference/bulk-processing/reference.md?source=youtube_download#playground)

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

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

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

### Python

#### Installare nel tuo ambiente Python

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

#### Correre da youtube-search/

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


### Bash

#### Controlla i tuoi strumenti

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

#### Correre da youtube-search/

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



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

## Se la ricerca ha bisogno di attenzione

| Che cosa è successo? | Cosa fare |
| --- | --- |
| Meno di cinque video, o nessuno | Questa 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 / 402 | Controllare la chiave, youtube_search permesso e equilibrio, rispettivamente. Fissare la causa prima di creare un nuovo tentativo. |
| 429 | Per 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 incompleta | Conserva i file e controlla la cronologia della console prima di inviare di nuovo. Il toolkit non reinvia automaticamente richieste dall’esito sconosciuto. |

- [Richiedi la cronologia](https://flashdata.dev/app/jobs)
- [Errori e codici di stato](https://flashdata.dev/it/docs/errors/reference.md)
- [Toolkit Python per YouTube Search API](https://github.com/flashdatadev/youtube-search-api/blob/main/docs/troubleshooting.md)
