# FlashData Google Search API

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

مرجع كانوني: https://flashdata.dev/ar/docs/sources/google_search
جرى استعراضها: 2026-10-23

نقطة النهاية: POST https://data.flashdata.dev/v1/queries/realtime
المصادقة: X-API-Key: YOUR_API_KEY
Modes: [Realtime](https://flashdata.dev/ar/docs/reference/realtime-and-async/reference.md#realtime) · [Async](https://flashdata.dev/ar/docs/reference/realtime-and-async/reference.md#async) · [Batch](https://flashdata.dev/ar/docs/reference/batch-and-bulk/reference.md#batch)

إذن المصدر المطلوب: google_search

يستعاض عن YOUR_API_KEY بمفتاح API الذي يملك هذا المصدر من الأذن والائتمانات المتاحة. أجري طلبات على خادمك أو وكيل مضيف.

[إقامة المصادقة](https://flashdata.dev/ar/docs/guides/headers-and-authentication/reference.md)

[اختر وتنقيح بحث Google](https://flashdata.dev/ar/docs/guides/google-search-guide/reference.md)

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

## أرسل طلبًا

### Python

```bash
python3 -m pip install requests
```

```python
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},
    json=payload,
    timeout=120,
)
response.raise_for_status()
print(json.dumps(response.json(), ensure_ascii=False, indent=2))
```

### Bash / cURL

```bash
api_key="YOUR_API_KEY"
curl --fail-with-body --max-time 120 --request POST "https://data.flashdata.dev/v1/queries/realtime" \
  --header "Content-Type: application/json" \
  --header "X-API-Key: $api_key" \
  --data-binary @- <<'FLASHDATA_JSON'
{
  "source": "google_search",
  "query": "openai",
  "params": {
    "gl": "us",
    "hl": "en",
    "num": 10,
    "page": 1
  }
}
FLASHDATA_JSON
```

<a id="parameters"></a>

## البارامترات

<a id="parameters-group-0"></a>

### نص الطلب

| البارامترات | النوع | مطلوب | الافتراضي | الوصف |
| --- | --- | --- | --- | --- |
| <a id="parameter-source"></a> source | string | نعم | — | جاهزون إلى google_search.  |
| <a id="parameter-query"></a> query | string | نعم | غير محدد | باحث. يدعم مشغلي البحث في موقع Google مثل الموقع: وترجمة: صغر المدة: 1. أقصى مدة: 2000. |
| <a id="parameter-params"></a> params | object | لا | {} | Settings for this request.  |
| <a id="parameter-callback_url"></a> callback_url | string · nullable | لا | غير محدد | لـ async وbatch فقط. رابط HTTPS عام للإشعار بالاكتمال على المنفذ 443، بطول يصل إلى 2,048 حرفًا، دون بيانات اعتماد مستخدم أو جزء رابط. احذف القيمة أو استخدم null أو سلسلة فارغة لعدم إرسال إشعار. في batch، ضعه في كل استعلام خارج params.  |

<a id="parameters-group-1"></a>

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

| البارامترات | النوع | مطلوب | الافتراضي | الوصف |
| --- | --- | --- | --- | --- |
| <a id="parameter-params-gl"></a> params.gl | string | لا | غير محدد | رمز قطري من حرفين، مثلنا، جب، دي أو غرق. حدد صراحة لاختيار بلد ما. صغر المدة: 2. أقصى مدة: 2. Pattern: ^[A-Za-z]{2}$ |
| <a id="parameter-params-hl"></a> params.hl | string | لا | غير محدد | لغة الوصل بينية من طراز Google. جهزوا صراحة لاختيار لغة. صغر المدة: 1. أقصى مدة: 35. Pattern: ^[A-Za-z0-9-]+$ |
| <a id="parameter-params-location"></a> params.location | string | لا | غير محدد | طلب موقع بحث، ويفضل أن تكون مدينة، مثل "London, England, United Kingdom". التوافر يعتمد على نوع البحث صغر المدة: 1. أقصى مدة: 200. |

<a id="parameters-group-2"></a>

### الهجرات

| البارامترات | النوع | مطلوب | الافتراضي | الوصف |
| --- | --- | --- | --- | --- |
| <a id="parameter-params-num"></a> params.num | integer | لا | غير محدد | عدد النتائج المطلوب. لا تضيف FlashData قيمة افتراضية ثابتة عند حذفه. قد يختلف العدد العائد حسب الاستعلام ونوع البحث. الحد الأدنى: 1. الحد الأقصى: 100. |
| <a id="parameter-params-page"></a> params.page | integer | لا | غير محدد | صفحة النتائج المطلوبة جهز بشكل صريح. وكل صفحة هي طلب منفصل من شركة API. الحد الأدنى: 1. الحد الأقصى: 100. |

<a id="parameters-group-3"></a>

### تصفية البحث

| البارامترات | النوع | مطلوب | الافتراضي | الوصف |
| --- | --- | --- | --- | --- |
| <a id="parameter-params-tbs"></a> params.tbs | string | لا | غير محدد | طلب مرشحات بحث من طراز Google، مثل qdr:d لليوم الماضي أو qdr:w للأسبوع الماضي. التوافر يعتمد على نوع البحث صغر المدة: 1. أقصى مدة: 200. |
| <a id="parameter-params-autocorrect"></a> params.autocorrect | boolean | لا | غير محدد | طلب تصحيح التهجئة مع شركة true أو طلب إعاقتها مع شركة false. ويتوقف السلوك التطبيقي على نوع البحث؛ ويغفل استخدامه Googleسلوك  |

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

## اقرأ النتيجة

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

### read-response.py

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

## مثال للاستجابة

مثال مسجل؛ فالميادين والعدوى تعتمد على المصدر وتطلب مدخلات.
```json
{
  "source": "google_search",
  "status": "done",
  "results": [
    {
      "searchParameters": {
        "q": "openai",
        "gl": "us",
        "hl": "en",
        "type": "search",
        "num": 10,
        "page": 1,
        "engine": "google"
      },
      "organic": [
        {
          "title": "OpenAI | Research & Deployment",
          "link": "https://openai.com/",
          "snippet": "We believe our research will eventually lead to artificial general intelligence, a system that can solve human-level problems.",
          "position": 1
        },
        {
          "title": "OpenAI",
          "link": "https://en.wikipedia.org/wiki/OpenAI",
          "snippet": "OpenAI is an American artificial intelligence (AI) public benefit corporation (PBC) headquartered in San Francisco. It develops proprietary generative AI models ...",
          "position": 2
        },
        {
          "title": "OpenAI",
          "link": "https://x.com/OpenAI",
          "snippet": "OpenAI's mission is to ensure that artificial general intelligence benefits all of humanity. can develop research, build financial models, and create ...",
          "position": 3
        },
        {
          "title": "OpenAI",
          "link": "https://www.linkedin.com/company/openai",
          "snippet": "OpenAI is an AI research and deployment company dedicated to ensuring that general-purpose artificial intelligence benefits all of humanity.",
          "position": 4
        },
        {
          "title": "r/OpenAI",
          "link": "https://www.reddit.com/r/OpenAI/",
          "snippet": "OpenAI is an AI research and deployment company. OpenAI&#39;s mission is to create safe and powerful AI that benefits all of humanity. OpenAI's ...",
          "position": 5
        }
      ],
      "peopleAlsoAsk": [
        {
          "question": "Is OpenAI created by Elon Musk?"
        },
        {
          "question": "Why are people leaving ChatGPT?"
        },
        {
          "question": "Is OpenAI the same as ChatGPT?"
        },
        {
          "question": "Why is OpenAI in trouble?"
        }
      ],
      "relatedSearches": [
        {
          "query": "OpenAI login"
        },
        {
          "query": "OpenAI chat"
        },
        {
          "query": "OpenAI ChatGPT"
        },
        {
          "query": "OpenAI - wikipedia"
        },
        {
          "query": "OpenAI API"
        },
        {
          "query": "OpenAI app"
        },
        {
          "query": "OpenAI download"
        },
        {
          "query": "OpenAI video"
        }
      ]
    }
  ],
  "usage": {
    "credits": 0.02
  },
  "created_at": "2026-09-16T07:41:40.043Z"
}
```

## حقول الاستجابة

| الميدان | النوع | الوصف |
| --- | --- | --- |
| source | string | المصدر المطلوب من شركة API. |
| status | string | تم عندما يتكلل الطلب بالنجاح. |
| created_at | string | وقت إنشاء الاستجابة في شكل ISO 8601. |
| usage.credits | number | إئتمانات مُقيدة على الطلب، بناءً على خطتك. |
| results[0].searchParameters | object | (ج) حالات البحث التي أبلغت عنها شركة Google، مع تسجيل الاستفسارات على أنها q. وقد تختلف البيئات العائدة عن القيم المطلوبة. |
| results[0].organic | array | نتائج عضوية ذات عنوان وربط وقنبلة وموقع، بالإضافة إلى ميادين إضافية عند توافرها. |
| results[0].peopleAlsoAsk | array · optional | الأسئلة ذات الصلة، مع الإجابات ووصلات المصادر عند توافرها. |
| results[0].relatedSearches | array · optional | شروط البحث ذات الصلة، لكل منها مجال للاستفسار. |
| results[0].knowledgeGraph | object · optional | Information from the knowledge panel. |
| results[0].answerBox | object · optional | جواب مُميز. وتختلف المجالات مع نوع الإجابة. |

- وتعتمد المجالات المتاحة على نوع الاستفسار والبحث. وقد تكون الحقول الاختيارية غائبة، ويمكن إعادة حقول إضافية.
- ويمكن أن يختلف عدد الأصناف المعادة والزكية الزكية (searchParameters.num) عن params.num. استخدموا المجموعة المعادية لتحديد عدد النتائج الفعلي.

## تنسيقات الاستجابة

وتستخدم الردود JSON حسب التقصير. اختر شكلاً آخر مع هؤلاء المرشدين الاختياريين

- Accept: application/json (التقصير) أو text/plain. ويعرض النص الشاذ نفس الحقول في مخطط قابل للقراءة ومستقطب.
- X-Respond-With: markdown. إتركوا الحقول الأصلية وتعمل شركة Markdown بأي من شكلي الاستجابة.

يتوفر Markdown للاستعلامات الفورية والنتائج المكتملة.

وتصف المجالات الواردة أدناه رد شركة JSON.

[أمثلة صيغ الطلب والاستجابة](https://flashdata.dev/ar/docs/guides/response-formats/reference.md#headers)

<a id="job-lifecycle"></a>

<a id="async-batch"></a>

## أساسيات API

يستخدم منشئ الطلبات والأمثلة أعلاه معاملات هذا المصدر. استخدم أمثلة Python وcURL أدناه لخطوات الإرسال والحالة والنتائج المشتركة. جسم Batch هو كائن JSON يحتوي queries؛ ويعيد كل عنصر معرّف مهمة خاصًا به.

- [Async Request and receipt](https://flashdata.dev/ar/docs/reference/realtime-and-async/reference.md#async)

<a id="job-status"></a>

- [التحقق من حالة العمل](https://flashdata.dev/ar/docs/reference/realtime-and-async/reference.md#status)

<a id="job-results"></a>

- [استرجاع النتائج المنجزة](https://flashdata.dev/ar/docs/reference/realtime-and-async/reference.md#results)
- [Batch JSON](https://flashdata.dev/ar/docs/reference/batch-and-bulk/reference.md#batch)
- [العملاء المفتوحون](https://flashdata.dev/docs/openapi.json)

<a id="webhooks"></a>

<a id="callbacks"></a>

## الإخطارات المتعلقة بالإنجاز

- [استلام وثائق الإنجاز على شبكة الإنترنت والتحقق منها](https://flashdata.dev/ar/docs/guides/async-batch/reference.md#webhooks)

<a id="troubleshooting"></a>

## اضطرابات

- [الأخطاء ورموز الحالة](https://flashdata.dev/ar/docs/errors/reference.md#status-codes)
- [متى يُعيدُ النظر](https://flashdata.dev/ar/docs/errors/reference.md#retries)

## APIs ذات الصلة

- [Google Images API](https://flashdata.dev/ar/docs/sources/google_images/reference.md)
- [Google News API](https://flashdata.dev/ar/docs/sources/google_news/reference.md)
