# FlashData Google Places API

ابحث عن الأنشطة التجارية والأماكن المحلية. استرجع الأسماء والعناوين والإحداثيات والتقييمات وبيانات الاتصال عند توفرها.

مرجع كانوني: https://flashdata.dev/ar/docs/sources/google_places
جرى استعراضها: 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_places

يستعاض عن 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_places",
    "query": "coffee in san francisco",
    "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_places",
  "query": "coffee in san francisco",
  "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_places.  |
| <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 = [
    {name: item.get(name) for name in ("title", "address", "latitude", "longitude", "website")}
    for item in result.get("places", [])
]
print(json.dumps(output, ensure_ascii=False, indent=2))
```

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

مثال مسجل؛ فالميادين والعدوى تعتمد على المصدر وتطلب مدخلات.
```json
{
  "source": "google_places",
  "status": "done",
  "results": [
    {
      "searchParameters": {
        "q": "coffee in san francisco",
        "gl": "us",
        "hl": "en",
        "type": "places",
        "num": 10,
        "page": 1,
        "engine": "google"
      },
      "places": [
        {
          "position": 1,
          "title": "Kopê House",
          "address": "546 Laguna St",
          "latitude": 37.776222,
          "longitude": -122.42606,
          "rating": 4.9,
          "ratingCount": 76,
          "priceLevel": "$1–10",
          "category": "Cafe",
          "cid": "7430826673754830499"
        },
        {
          "position": 2,
          "title": "The Coffee Berry SF",
          "address": "1410 Lombard St",
          "latitude": 37.80141,
          "longitude": -122.424995,
          "rating": 4.9,
          "ratingCount": 642,
          "priceLevel": "$1–10",
          "category": "Coffee shop",
          "cid": "5181132708478222499"
        },
        {
          "position": 3,
          "title": "Sightglass Coffee",
          "address": "270 7th St",
          "latitude": 37.77704,
          "longitude": -122.40844,
          "rating": 4.4,
          "ratingCount": 3400,
          "priceLevel": "$10–20",
          "category": "Coffee shop",
          "cid": "13926460886861596347"
        },
        {
          "position": 4,
          "title": "Origin Lab Coffee & Matcha",
          "address": "211 Sutter St",
          "latitude": 37.789722,
          "longitude": -122.404175,
          "rating": 4.7,
          "ratingCount": 624,
          "priceLevel": "$1–10",
          "category": "Coffee shop",
          "cid": "9114931074474087601"
        },
        {
          "position": 5,
          "title": "The Coffee Movement",
          "address": "1737 Balboa St",
          "latitude": 37.7765,
          "longitude": -122.477806,
          "rating": 4.8,
          "ratingCount": 623,
          "priceLevel": "$1–10",
          "category": "Coffee shop",
          "cid": "2726196137705445702"
        },
        {
          "position": 6,
          "title": "Third Wheel Coffee",
          "address": "991 Oak St",
          "latitude": 37.77323,
          "longitude": -122.43559,
          "rating": 4.9,
          "ratingCount": 266,
          "priceLevel": "$1–10",
          "category": "Coffee shop",
          "cid": "1837357391573517555"
        },
        {
          "position": 7,
          "title": "Better Half Coffee",
          "address": "1448 Pacific Ave",
          "latitude": 37.79555,
          "longitude": -122.41909,
          "rating": 4.9,
          "ratingCount": 123,
          "priceLevel": "$10–20",
          "category": "Coffee shop",
          "cid": "11196405476986641272"
        },
        {
          "position": 8,
          "title": "Sextant Coffee Roasters",
          "address": "1415 Folsom St",
          "latitude": 37.772472,
          "longitude": -122.412964,
          "rating": 4.4,
          "ratingCount": 746,
          "priceLevel": "$1–10",
          "category": "Coffee shop",
          "cid": "16500984014294458956"
        },
        {
          "position": 9,
          "title": "Doppio Coffee & Brunch",
          "address": "1551 Mission St",
          "latitude": 37.773315,
          "longitude": -122.418015,
          "rating": 4.8,
          "ratingCount": 494,
          "priceLevel": "$10–20",
          "category": "Coffee shop",
          "cid": "16475263059648961979"
        },
        {
          "position": 10,
          "title": "Delah Coffee",
          "address": "370 4th St",
          "latitude": 37.781017,
          "longitude": -122.40022,
          "rating": 4.6,
          "ratingCount": 1200,
          "priceLevel": "$10–20",
          "category": "Coffee shop",
          "cid": "10682847123881919373"
        }
      ]
    }
  ],
  "usage": {
    "credits": 0.02
  },
  "created_at": "2026-09-16T07:41:45.679Z"
}
```

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

| الميدان | النوع | الوصف |
| --- | --- | --- |
| source | string | المصدر المطلوب من شركة API. |
| status | string | تم عندما يتكلل الطلب بالنجاح. |
| created_at | string | وقت إنشاء الاستجابة في شكل ISO 8601. |
| usage.credits | number | إئتمانات مُقيدة على الطلب، بناءً على خطتك. |
| results[0].searchParameters | object | (ج) حالات البحث التي أبلغت عنها شركة Google، مع تسجيل الاستفسارات على أنها q. وقد تختلف البيئات العائدة عن القيم المطلوبة. |
| results[0].places | array | نتائج البحث المحلي |
| results[0].places[].title | string | المكان أو اسم العمل |
| results[0].places[].address | string · optional | عنوان الشارع |
| results[0].places[].latitude | number · optional | خط العرض. |
| results[0].places[].longitude | number · optional | خط الطول |
| results[0].places[].rating | number · optional | متوسط التقدير |
| results[0].places[].ratingCount | integer · optional | عدد التقديرات |
| results[0].places[].category | string · optional | فئة الأعمال. |
| results[0].places[].phoneNumber | string · optional | رقم الهاتف المدرج. |
| results[0].places[].website | string · optional | موقع الأعمال. |
| results[0].places[].cid | string · optional | Google تحديد مكان. |
| results[0].places[].position | integer | موقف النتائج. |
| results[0].places[].priceLevel | string · 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 Search API](https://flashdata.dev/ar/docs/sources/google_search/reference.md)
- [Google Images API](https://flashdata.dev/ar/docs/sources/google_images/reference.md)
