# YouTube Search API: دليل Python

ابحث في YouTube بالكلمات المفتاحية، وصفِّ الفيديوهات وصدّر ملفات CSV وJSONL ومعرّفات فيديو بلا تكرار باستخدام Python.

مرجع كانوني: https://flashdata.dev/ar/docs/guides/youtube-search-recipe
Reviewed: 2026-11-16 by FlashData

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

## البحث في YouTube باستخدام 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"])
```

- [احصل على مفتاح API](https://flashdata.dev/signup)
- [جرّب البحث المباشر](https://flashdata.dev/ar/products/youtube-data#playground)

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

## استجابة بحث حقيقية

هذه أول ثلاث نتائج من أصل 20 التُقطت من العرض العام لاستعلام «battery recycling process» في 15 نوفمبر 2026. يحتفظ التسجيل بستة حقول لكل فيديو. شغّل العرض المباشر للحصول على نتائج حديثة.

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

- [استجابة بحث حقيقية](https://github.com/flashdatadev/youtube-search-api/blob/main/src/flashdata_search/recorded/search.json)

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

## جمع عدة عمليات بحث في مجموعة بيانات

تحفظ أدوات Python الاستجابات المكتملة، وتزيل معرّفات الفيديو المكررة، وتحتفظ بكل استعلام مطابق وموضع نتيجته. استأنف بالخيارات نفسها وresume=True لإعادة استخدام عمليات البحث المكتملة.

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

- [أدوات Python لـ YouTube Search API](https://github.com/flashdatadev/youtube-search-api)

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

## بحث قياسي أم موسّع؟

يقبل البحث القياسي 1–20 نتيجة لكل استعلام. ويقبل البحث الموسّع 1–700 بسعر منفصل. القيمة الافتراضية لكليهما 20؛ max_results حد أقصى وليس عدد نتائج مضمونًا.

استخدم مرشحات المدة وتاريخ الرفع والترتيب والترجمة النصية. لا توفّر نقاط النهاية هذه رقم صفحة أو رمز متابعة. استخدم البحث الموسّع للحصول على نتائج أكثر.

### الحصول على نتائج أكثر بالبحث الموسّع

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

- [عند استخدام البحث الموسع](https://flashdata.dev/ar/docs/sources/youtube_search_extended/reference.md)
- [قارن أسعار البحث](https://flashdata.dev/ar/products/youtube-data#choose-api)

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

## نسهم البحث عند الحاجة

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

- [جميع مرشحات البحث](https://flashdata.dev/ar/docs/sources/youtube_search/reference.md#parameters)

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

## اختر ما تغنيه بعد ذلك

استخدم video-ids.txt مدخلًا لسير عمل البيانات الوصفية أو النصوص المفرغة أو التنزيل الجماعي. راجع الفيديوهات المرشحة قبل اختيار المعرّفات لإثرائها أو تسليمها.

| مهمتك القادمة | استخدمي الرقم المختار من طراز IDs |
| --- | --- |
| تحقق من تفاصيل الفيديو | اجلب البيانات الوصفية لمعرّف مختار. افحص transcriptLanguages قبل طلب مسار ترجمة نصية محدد. |
| Summarize spoken content | اقرأ نصاً متاحاً أو مساراً للاختفاء وإستشهد بأوقات لا تلخيص الفيديو من وصف البحث الخاص به وحده. |
| إثراء عدة أشرطة فيديو | استخدم selected-video-ids.txt كإدخال لدليل الإثراء. البيانات الوصفية والترجمات النصية طلبات منفصلة بصلاحيات ورسوم مستقلة. |

- [ميثاداتا فيديو واحد](https://flashdata.dev/ar/docs/guides/video-metadata-recipe/reference.md)
- [تُسجّلُ فيديو مَع إستشهادِ](https://flashdata.dev/ar/docs/guides/youtube-summary/reference.md)
- [Enrich selected video IDs](https://flashdata.dev/ar/docs/guides/enrich-youtube-videos/reference.md)
- [Bulk API](https://flashdata.dev/ar/docs/reference/bulk-processing/reference.md?source=youtube_download#playground)

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

## مثال REST كامل مع حفظ الاستجابات

اختياريًا، استخدم requests أو cURL مباشرة. احفظ request.json بجانب السكربت. ضع مفتاح API في متغير key في Python؛ يقرأ Bash قيمة FLASHDATA_API_KEY أو يطلب المفتاح. يرسل كل مجلد إخراج جديد عملية بحث واحدة.

اجري مع البحث - 001 كمجلد النواتج. ويقدم ملف جديد بحثاً قابلاً للتعديل؛ ويُقرأ الملف الموجود محلياً. ويحتفظ النص بالطلب والرد والاستخدام اللذين قدما على وجه الدقة.

### youtube-search/request.json

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

### Python

#### ضع في رأسك 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")
```

#### اهربوا من اليوتوبي - سيرش/

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


### Bash

#### تحقق من أدواتك

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

#### اهربوا من اليوتوبي - سيرش/

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



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

## إذا كان البحث بحاجة إلى الاهتمام

| ماذا حدث؟ | الإجراء المطلوب |
| --- | --- |
| أقل من خمسة أشرطة فيديو، أو لا شيء | هذا يمكن أن يكون بحث ناجح. ارفضي السؤال أو ازيلي مرشح تقييدي totalResults يصف هذا الرد، وليس العدد الإجمالي للتطابق YouTube أشرطة فيديو |
| 401 / 403 / 402 | تحقق من المفتاح، إذن وتوازن youtube_search، على التوالي. اصلح القضية قبل ان تخلق محاولة جديدة |
| 429 | عند HTTP 429، انتظر وفق Retry-After. تعيد الأدوات محاولة استجابات 429 الصريحة فقط، مرتين كحد أقصى افتراضيًا، وتتوقف إذا تجاوز الانتظار 60 ثانية. لا تعيد أمثلة SDK المباشرة وREST المحاولة تلقائيًا. |
| وقت مستقطع، 5x أو ملف غير كامل | احتفظ بالملفات وتحقق من سجل وحدة التحكم قبل الإرسال مجددًا. لا تعيد الأدوات إرسال طلب ذي نتيجة مجهولة تلقائيًا. |

- [التاريخ](https://flashdata.dev/app/jobs)
- [الأخطاء ورموز الحالة](https://flashdata.dev/ar/docs/errors/reference.md)
- [أدوات Python لـ YouTube Search API](https://github.com/flashdatadev/youtube-search-api/blob/main/docs/troubleshooting.md)
