تصفح الوثائق
أمثلة
ابحث في YouTube بالكلمات المفتاحية، وصفِّ الفيديوهات وصدّر ملفات CSV وJSONL ومعرّفات فيديو بلا تكرار باستخدام Python.
في هذه الصفحة
البحث في YouTube باستخدام Python
python -m pip install -U flashdatafrom 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"])
استجابة بحث حقيقية
هذه أول ثلاث نتائج من أصل 20 التُقطت من العرض العام لاستعلام «battery recycling process» في 15 نوفمبر 2026. يحتفظ التسجيل بستة حقول لكل فيديو. شغّل العرض المباشر للحصول على نتائج حديثة.
[
{
"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
}
]جمع عدة عمليات بحث في مجموعة بيانات
تحفظ أدوات Python الاستجابات المكتملة، وتزيل معرّفات الفيديو المكررة، وتحتفظ بكل استعلام مطابق وموضع نتيجته. استأنف بالخيارات نفسها وresume=True لإعادة استخدام عمليات البحث المكتملة.
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"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
بحث قياسي أم موسّع؟
يقبل البحث القياسي 1–20 نتيجة لكل استعلام. ويقبل البحث الموسّع 1–700 بسعر منفصل. القيمة الافتراضية لكليهما 20؛ max_results حد أقصى وليس عدد نتائج مضمونًا.
استخدم مرشحات المدة وتاريخ الرفع والترتيب والترجمة النصية. لا توفّر نقاط النهاية هذه رقم صفحة أو رمز متابعة. استخدم البحث الموسّع للحصول على نتائج أكثر.
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")
نسهم البحث عند الحاجة
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",
},
)
اختر ما تغنيه بعد ذلك
استخدم video-ids.txt مدخلًا لسير عمل البيانات الوصفية أو النصوص المفرغة أو التنزيل الجماعي. راجع الفيديوهات المرشحة قبل اختيار المعرّفات لإثرائها أو تسليمها.
| مهمتك القادمة | استخدمي الرقم المختار من طراز IDs |
|---|---|
| تحقق من تفاصيل الفيديو | اجلب البيانات الوصفية لمعرّف مختار. افحص transcriptLanguages قبل طلب مسار ترجمة نصية محدد. |
| Summarize spoken content | اقرأ نصاً متاحاً أو مساراً للاختفاء وإستشهد بأوقات لا تلخيص الفيديو من وصف البحث الخاص به وحده. |
| إثراء عدة أشرطة فيديو | استخدم selected-video-ids.txt كإدخال لدليل الإثراء. البيانات الوصفية والترجمات النصية طلبات منفصلة بصلاحيات ورسوم مستقلة. |
مثال REST كامل مع حفظ الاستجابات
اختياريًا، استخدم requests أو cURL مباشرة. احفظ request.json بجانب السكربت. ضع مفتاح API في متغير key في Python؛ يقرأ Bash قيمة FLASHDATA_API_KEY أو يطلب المفتاح. يرسل كل مجلد إخراج جديد عملية بحث واحدة.
اجري مع البحث - 001 كمجلد النواتج. ويقدم ملف جديد بحثاً قابلاً للتعديل؛ ويُقرأ الملف الموجود محلياً. ويحتفظ النص بالطلب والرد والاستخدام اللذين قدما على وجه الدقة.
{
"source": "youtube_search",
"query": "battery recycling process explained",
"params": {
"max_results": 5,
"filters": {
"type": "video"
}
}
}python -m pip install requestsimport 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")
python search.py search-001curl --version
jq --version#!/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 search.sh search-001إذا كان البحث بحاجة إلى الاهتمام
| ماذا حدث؟ | الإجراء المطلوب |
|---|---|
| أقل من خمسة أشرطة فيديو، أو لا شيء | هذا يمكن أن يكون بحث ناجح. ارفضي السؤال أو ازيلي مرشح تقييدي totalResults يصف هذا الرد، وليس العدد الإجمالي للتطابق YouTube أشرطة فيديو |
| 401 / 403 / 402 | تحقق من المفتاح، إذن وتوازن youtube_search، على التوالي. اصلح القضية قبل ان تخلق محاولة جديدة |
| 429 | عند HTTP 429، انتظر وفق Retry-After. تعيد الأدوات محاولة استجابات 429 الصريحة فقط، مرتين كحد أقصى افتراضيًا، وتتوقف إذا تجاوز الانتظار 60 ثانية. لا تعيد أمثلة SDK المباشرة وREST المحاولة تلقائيًا. |
| وقت مستقطع، 5x أو ملف غير كامل | احتفظ بالملفات وتحقق من سجل وحدة التحكم قبل الإرسال مجددًا. لا تعيد الأدوات إرسال طلب ذي نتيجة مجهولة تلقائيًا. |