تخطَّ إلى المحتوى
AR
الحصول على مفتاح API
تصفح الوثائق

مرجع API

استرجع نتائج Google Search العضوية والأسئلة ذات الصلة والنتائج الغنية بصيغة JSON منظّمة. رشّح حسب البلد واللغة والموقع.

إنشاء طلب

معلمات متقدمة

تبدأ في 1. كل صفحة هي طلب منفصل

Google filter, such as qdr:d for the past day.

POSThttps://data.flashdata.dev/v1/queries/realtime
Python 3 · requests
python3 -m pip install requests
import json

import requests

api_key = "YOUR_API_KEY"
payload = {
    "source": "google_search",
    "query": "openai",
    "params": {
        "gl": "us",
        "hl": "en",
        "num": 10,
        "page": 1,
    },
}

response = requests.post(
    "https://data.flashdata.dev/v1/queries/realtime",
    headers={"X-API-Key": api_key, "Accept": "application/json"},
    json=payload,
    timeout=120,
)
response.raise_for_status()
print(json.dumps(response.json(), ensure_ascii=False, indent=2))
النتائج في رد HTTPX-API-Key authentication

البارامترات

أرسل source و query على المستوى الأعلى خيارات المصادر تنتمي إلى params. ويمكن إغفال الحقول الاختيارية.

نص الطلب

sourcestring / مطلوب
جاهزون إلى google_search.
querystring / مطلوب
باحث. يدعم مشغلي البحث في موقع Google مثل الموقع: وترجمة:
1 إلى 2,000 الشخصياتالتقصير: غير محدد
paramsobject / اختياري
Settings for this request.
التقصير: {}
callback_urlstring · nullable / اختياري
لـ async وbatch فقط. رابط HTTPS عام للإشعار بالاكتمال على المنفذ 443، بطول يصل إلى 2,048 حرفًا، دون بيانات اعتماد مستخدم أو جزء رابط. احذف القيمة أو استخدم null أو سلسلة فارغة لعدم إرسال إشعار. في batch، ضعه في كل استعلام خارج params.
التقصير: غير محدد

البلد، اللغة، الموقع

params.glstring / اختياري
رمز قطري من حرفين، مثلنا، جب، دي أو غرق. حدد صراحة لاختيار بلد ما.
بالضبط 2 الشخصياتالتقصير: غير محدد
الشكل المقبول^[A-Za-z]{2}$
params.hlstring / اختياري
لغة الوصل بينية من طراز Google. جهزوا صراحة لاختيار لغة.
1 إلى 35 الشخصياتالتقصير: غير محدد
الشكل المقبول^[A-Za-z0-9-]+$
params.locationstring / اختياري
طلب موقع بحث، ويفضل أن تكون مدينة، مثل "London, England, United Kingdom". التوافر يعتمد على نوع البحث
1 إلى 200 الشخصياتالتقصير: غير محدد

الهجرات

params.numinteger / اختياري
عدد النتائج المطلوب. لا تضيف FlashData قيمة افتراضية ثابتة عند حذفه. قد يختلف العدد العائد حسب الاستعلام ونوع البحث.
1 إلى 100, أعداد كاملةالتقصير: غير محدد
params.pageinteger / اختياري
صفحة النتائج المطلوبة جهز بشكل صريح. وكل صفحة هي طلب منفصل من شركة API.
1 إلى 100, أعداد كاملةالتقصير: غير محدد

تصفية البحث

params.tbsstring / اختياري
طلب مرشحات بحث من طراز Google، مثل qdr:d لليوم الماضي أو qdr:w للأسبوع الماضي. التوافر يعتمد على نوع البحث
1 إلى 200 الشخصياتالتقصير: غير محدد
params.autocorrectboolean / اختياري
طلب تصحيح التهجئة مع شركة true أو طلب إعاقتها مع شركة false. ويتوقف السلوك التطبيقي على نوع البحث؛ ويغفل استخدامه Googleسلوك
true أو falseالتقصير: غير محدد

استجابة

Realtime Returns status: done مع ناتج البحث في results[0]. الماشي في results[0].organic. usage.credits سجل التهمة.

وتشمل المباريات العضوية ألقاب ووصلات وقنابل. والمسائل ذات الصلة والنتائج الثرية هي مسائل اختيارية.

اقرأ النتيجة

وفّر ردّ شركة JSON الناجح على أنها response.json. احفظ هذا read-response.py و اركضوا بيثون read-response.py. إنها تستخدم فقط Pythonمكتبة عادية ولا تقدم طلباً جديداً

read-response.py
import json
from pathlib import Path

response = json.loads(Path("response.json").read_text(encoding="utf-8-sig"))
if response.get("status") not in ("done", "completed") or not isinstance(response.get("results"), list):
    raise SystemExit("Expected completed result JSON; inspect the response or job status.")
if not response["results"]:
    print("[]")
    raise SystemExit(0)
result = response["results"][0]

output = [
    {"title": item.get("title"), "url": item.get("link"), "snippet": item.get("snippet")}
    for item in result.get("organic", [])
]
print(json.dumps(output, ensure_ascii=False, indent=2))

وتعتمد المجالات المتاحة على نوع الاستفسار والبحث. وقد تكون الحقول الاختيارية غائبة، ويمكن إعادة حقول إضافية.

ويمكن أن يختلف عدد الأصناف المعادة والزكية الزكية (searchParameters.num) عن params.num. استخدموا المجموعة المعادية لتحديد عدد النتائج الفعلي.

جميع مجالات الاستجابة
الميدانالوصف
sourcestringالمصدر المطلوب من شركة API.
statusstringتم عندما يتكلل الطلب بالنجاح.
created_atstringوقت إنشاء الاستجابة في شكل ISO 8601.
usage.creditsnumberإئتمانات مُقيدة على الطلب، بناءً على خطتك.
results[0].searchParametersobject(ج) حالات البحث التي أبلغت عنها شركة Google، مع تسجيل الاستفسارات على أنها q. وقد تختلف البيئات العائدة عن القيم المطلوبة.
results[0].organicarrayنتائج عضوية ذات عنوان وربط وقنبلة وموقع، بالإضافة إلى ميادين إضافية عند توافرها.
results[0].peopleAlsoAskarray · optionalالأسئلة ذات الصلة، مع الإجابات ووصلات المصادر عند توافرها.
results[0].relatedSearchesarray · optionalشروط البحث ذات الصلة، لكل منها مجال للاستفسار.
results[0].knowledgeGraphobject · optionalInformation from the knowledge panel.
results[0].answerBoxobject · optionalجواب مُميز. وتختلف المجالات مع نوع الإجابة.

وتصف المجالات المذكورة أعلاه رد شركة JSON. JSON, plain text and Markdown formats.

Async ' batch lifecycle

يعيد الإرسال إيصالًا وليس نتائج. ينشئ Async مهمة واحدة؛ ويعيد batch مهمة مستقلة في queries[] لكل سؤال مقبول تتبع كل وظيفة واسترجاعها بشكل مستقل.

Submit to data.flashdata.dev; قراءــة مركز العمل والنتائج api.flashdata.dev مع نفس X-API-Key. وتستخدم الأمثلة الأساسية للزدحام الزكسكسيك ذات الصلة API Python و cURL.

  1. 1. وفّر الوظيفة IDs

    أبقوا حقول طلب هذا المصدر عند التحول إلى Async. وبالنسبة إلى Batch، وضع كل طلب داخل مجموعة الاستفسارات من جسم JSON. انقذوا كل عمل ID.

    Async Request and receipt · Batch

  2. 2. حالة التحقق

    GET https://api.flashdata.dev/v2/jobs/{jobId}

    pending / processing: استطلاع مع التأخير والاحترام Retry-After عندما تكون حاضراً completed: تحقيق النتائج failed: التفتيش job.error.

    اقرأ job.statusليس حالة إيصال المعلومات.

    مركز التحقير: Python و cURL

    المرجعي API
  3. 3. نتائج الرسم

    GET https://api.flashdata.dev/v2/jobs/{jobId}/results

    بعد الإكمال، توثّق النتيجة على النحو التالي، ثمّ تُحضر مخزن 302 URL بدون مفتاحك API. وفّر الرقم JSON في غضون ساعات الإنجاز من تاريخ الـ 24.

    نتائج المشاهدة: Python و cURL · تنسيقات الاستجابة

    Result download API reference

ولا تستهلك السياسات وتحقق النتائج القائمة أي تنازلات للأسئلة. ولا يلغى وقت الاقتراع هذا العمل: فإبقاء مقره ID بدلاً من تقديم عمل مكرر قابل للتعديل. شفرات الرعب وسلوك الاعادة.

إشعارات Webhook عند الاكتمال

Subscribe per query

المجموعة callback_url على أعلى مستوى لطلب الأسينك، أو داخل كل استفسار في دفعة، في الخارج params. ولا يلزم طلب تسجيل منفصل على الشبكة العالمية. ولا تُرسل طلبات شركة Realtime ردوداً.

استخدم عنوان HTTPS عامًا على المنفذ 443. ترسل FlashData إشعار POST لكل مهمة تصل إلى completed أو failed; The event contains links, not the result itself.

الاعتراف والتحقق

العودة 2xx بعد قبول الحدث بشكل مكثف. مُتَوَجَّل delivery_id, كما أُرسلت X-Delivery-Id. لا تتبع إعادة التوجيه.

عمليات التسليم الفاشلة تُعاد مع التراجع المفاجئ، حتى 8 مجموع المحاولات على الأكثر 24 بعد ساعات من الانتهاء. استمر في الاقتراع كتراجع

النداءات غير موقعة. تأكد من معرّف المهمة ومصدرها وحالتها النهائية باستخدام نقطة نهاية الوضع الموثقة قبل تجهيز الإخطار. التسليم ID هو للتحلل، وليس إثبات صحة.

مناسبة وميادين على الشبكة العالمية
الإخطار بالإكمال التوضيحي
{
  "delivery_id": "completion:job_example0001",
  "id": "job_example0001",
  "source": "google_search",
  "status": "completed",
  "links": [
    {
      "rel": "self",
      "href": "https://api.flashdata.dev/v2/jobs/job_example0001",
      "method": "GET"
    },
    {
      "rel": "results",
      "href": "https://api.flashdata.dev/v2/jobs/job_example0001/results",
      "method": "GET"
    }
  ]
}
الميدانالوصف
delivery_idstringمعرّف تسليم ثابت. امنع تكرار الإشعارات باستخدام هذه القيمة؛ وتُرسل أيضًا في ترويسة X-Delivery-Id.
idstringوظيفة(ب) ID.
sourcestringطلب مصدر بيانات.
statusstringاكتملت أو فشلت
linksarrayوصلات الوضع والنتائج. ولا تشمل الإخطارات محتوى النتائج أو مفتاحاً من طراز API.
links[].relstringذاتي أو نتائج.
links[].hrefstringعنوان URL كامل لواجهة الإدارة؛ صادِق باستخدام مفتاح API.
links[].methodstringGET.

عقد كامل على الشبكة العالمية وقيود URL

التعافي من الأخطاء

وقد يحتوي البحث المكتمل على عدد أقل من المباريات عما هو مطلوب. تحقق gl, hl, والمواقع والمرشحات؛ قد لا تكون هناك حقول اختيارية ذات نتائج ثرية.

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

الأخطاء ورموز الحالة · متى يُعيدُ النظر · الحد الأقصى للمعدل

دليل الخطوة خطوة: اختر وتنقيح بحث Google

الأسعار

الخططمعدلات الاستخداملكل 1,000 طلبالاشتراكاتتشمل الأرصدة الدائنة لكل فترة من فترات إعداد الفواتير
الدفع حسب الاستخدام‏1.00 US$بلا رسوم شهريةأضف رصيدًا عند الحاجة
Micro‏0.80 US$‏49.00 US$ / الشهر1,000 credits (‏50.00 US$ of API usage) included
Starter‏0.65 US$‏199.00 US$ / الشهر4,000 credits (‏200.00 US$ of API usage) included
Pro‏0.60 US$‏499.00 US$ / الشهر10,000 credits (‏500.00 US$ of API usage) included
Scale‏0.50 US$‏999.00 US$ / الشهر20,000 credits (‏1,000.00 US$ of API usage) included
Business‏0.40 US$‏1,999.00 US$ / الشهر40,000 credits (‏2,000.00 US$ of API usage) included

خطة واحدة للحساب. رصيد مشترك للمنتجات الثلاثة. لا تُفرض رسوم مرة أخرى على الاستخدام المغطى بالرصيد المضمّن.

الأسعار والحدود الحالية للخطة