POST /api/v1/search

API سكرابر Google Maps

اعثر على الأنشطة التجارية بالكلمة الرئيسية والموقع. استقبل حتى 20 سجل نشاط تجاري منظمًا في استجابة JSON نفسها، جاهزة لتطبيقك أو سير عمل البحث لديك.

أمثلة على الطلبات

للاطلاع على العقد الكامل، راجع وثائق API.

curl https://gmapscrawl.com/api/v1/search \
  -H "Authorization: Bearer $GMSCRAPER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: seattle-coffee-search-001" \
  -d '{"q":"coffee shops in Seattle","page":1,"extra":false}'

استجابة فارغة توضيحية. يُرجع البحث الفعلي الأنشطة التجارية المتاحة. احتفظ بمفتاح API الخاص بك من جانب الخادم؛ استخدم مفتاح عدم تكرار جديدًا للعمل الجديد واحتفظ به لإعادة محاولة غير مُغيَّرة.

الاستجابة

JSON توضيحي
{
  "data": {
    "total": 0,
    "params": {
      "q": "coffee shops in Seattle",
      "page": 1,
      "hl": "en",
      "extra": false
    },
    "businesses": []
  },
  "request_id": "req_example",
  "schema_version": "2026-09-22"
}

تُرجع API صيغة JSON في الاستجابة نفسها. بعد انتهاء المهلة، أعد المحاولة بالنص نفسه دون تغيير مع Idempotency-Key ذاتها. تُرجع بيانات الاعتماد التجريبية بيانات محاكاة دون استخدام حصتك الفعلية.

بيانات أنشطة تجارية منظمة

من بحث في الخرائط إلى سجلات يمكنك استخدامها.

اقرأ data.businesses من الاستجابة. يجمع كل نشاط تجاري حقول بطاقة بياناته ضمن place؛ ويعتمد توفر الحقول على المصدر.

01

هوية النشاط التجاري وموقعه

استخدم اسم النشاط التجاري والفئات والعنوان المنسّق والإحداثيات وعنوان URL للخرائط لتنظيم مجموعة بيانات الأنشطة التجارية المحلية.

02

الاتصال والسمعة

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

03

المعرّفات وتواريخ الملاحظة

احتفظ بـ place.dataId لعمليات البحث عن المراجعات والصور. افحص place.observedAt وcontactsCheckedAt لفهم متى تمت ملاحظة البيانات.

اجعل البيانات المفقودة والأقدم مرئية

يمكن أن تكون الحقول غير المتاحة null أو فارغة، وقد يبلّغ الإثراء عن not_found أو failed. لا يضمن السجل وجود عنوان بريد إلكتروني أو موقع إلكتروني. يمكن إعادة استخدام تفاصيل الخرائط لمدة تصل إلى 730 يومًا مع طوابع الملاحظة الزمنية الأصلية؛ قيّم الحداثة قبل استخدام سجل.

اقرأ عن حداثة البيانات ←

طلب مركّز

اختر الاستعلام والصفحة والإثراء.

أرسل نص JSON مع مفتاح API من جانب الخادم في ترويسة authorization. المطلوب هو q فقط.

معلمات Google Maps Search API
المعلمةالمتطلبالغرض
qمطلوبكلمة رئيسية لنشاط تجاري وموقع، مثل coffee shops in Seattle. استخدم من 2 إلى 200 حرف.
pageالافتراضي: 1صفحة بحث مرقّمة من 1 إلى 10. يُرجع كل طلب 20 نشاطًا تجاريًا كحد أقصى.
llاختياريإطار عرض للخرائط بالشكل @47.6062,-122.3321,12z لتوجيه موقع البحث.
hlالافتراضي: enرمز اللغة المستخدم في البحث.
glاختياريرمز بلد من حرفين يؤهّل الاستعلام. ليس مرشحًا جغرافيًا صارمًا.
extraالافتراضي: falseاضبطه على true لطلب إثراء جهات اتصال البريد الإلكتروني والتواصل الاجتماعي المتاحة. قد يستغرق ذلك وقتًا أطول.

تردد الاستجابة المعلمات المُطبَّعة في data.params. تحسب قيمة data.total الأنشطة التجارية في هذه الاستجابة، وليس العدد الإجمالي للأنشطة التجارية على خرائط Google. اختر صفحة أخرى صراحةً عندما يحتاج سير عملك إلى مزيد من النتائج.

ابنِ أول تكامل لك

طلب واحد. خطوة تالية مفيدة.

Search API متزامنة: اقرأ النتيجة مباشرة من استجابة HTTP.

01

أنشئ مفتاح API الخاص بك

استخدم مساحة عمل API لإنشاء مفتاح بإذن scrapes:write. خزّن المفتاح في بيئة الخادم وأرسل Authorization: Bearer مع الطلب.

افتح مفاتيح API
02

ابحث في منطقة محدودة

اختر فئة وموقعًا، واطلب الصفحة 1، وافحص حقول بطاقات البيانات المُرجعة. للمقارنة بين الأسواق، أصدر عمليات بحث منفصلة للمناطق التي تريد مقارنتها.

03

اتبع معرّف مكان

استخدم place.dataId من نشاط تجاري مطابق كـ fid لاسترجاع صفحة مراجعات أو صفحة معرض. هذه طلبات منفصلة بسجلات مُرجعة خاصة بها.

استكشف Reviews API

خطط لطلبات فعلية

صفحات قابلة للتنبؤ، حدود صريحة.

الاستخدام والتوفر

تستخدم كل صفحة بحث فعلية ناجحة وحدة طلب API واحدة، بما في ذلك نتيجة فارغة. يتشارك REST وMCP حصة API. اشتراكات أداة الكشط عبر الإنترنت والإضافة لها حصص منفصلة. لا تزال حدود المعدل وبيانات الاعتماد وسعة الخدمة وتوفر المصدر سارية.

قارن خطط API ←

المهلات وإعادة المحاولة

اسمح بما يصل إلى 180 ثانية في عميل HTTP الخاص بك. قد تترك المهلة عملًا قيد المعالجة مع وحدة طلب محجوزة. أعد استخدام النص المطابق وIdempotency-Key لإعادة محاولة ذلك الطلب. تحقق من تفاصيل الخطأ وقابلية إعادة المحاولة قبل بدء محاولة جديدة.

افهم عمليات إعادة المحاولة ←

واصل سير عملك

طرق أخرى لاستخدام بيانات الأنشطة التجارية نفسها.

01

بيانات المراجعات والمعرض

استرجع المراجعات العامة أو بيانات الصور والفيديو الوصفية لمكان باستخدام معرّف الميزة الخاص به.

استكشف بيانات المعرض
02

اتصل بعميل MCP

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

إعداد MCP
03

ثبّت مهارة الوكيل

امنح وكيلك تعليمات سير العمل ومراجع العمليات وبديل REST لأبحاث خرائط Google.

استكشف المهارة

الأسئلة الشائعة

ماذا تُرجع API سكرابر Google Maps؟

تُرجع غلاف JSON يحتوي على data.businesses وdata.total وdata.params المُطبَّعة وrequest_id وschema_version. تتضمن الأنشطة التجارية حقول بطاقات البيانات المتاحة مثل الأسماء والعناوين والفئات ومعلومات الاتصال والتقييمات ومعرّفات الخرائط.

هل يمكنني استخدام API من Python أو JavaScript؟

نعم. تقبل نقطة النهاية طلبات HTTP POST قياسية مع JSON ومصادقة Bearer. تستخدم الأمثلة أعلاه مكتبة Python القياسية وfetch من جانب الخادم في JavaScript. يمكن لأي عميل HTTP قادر على إرسال تلك الترويسات والنص أن يتكامل.

كم عدد الأنشطة التجارية التي يمكن لطلب واحد إرجاعها؟

تُرجع صفحة البحث ما بين صفر و20 نشاطًا تجاريًا. تقبل معلمة page القيم من 1 إلى 10. تستخدم كل صفحة فعلية ناجحة، بما في ذلك صفحة فارغة، وحدة طلب API واحدة؛ ولا يضمن البحث أن تحتوي كل صفحة على 20 نشاطًا تجاريًا.

هل يمكنني استرجاع مراجعات وصور فردية؟

نعم. انسخ place.dataId من نشاط تجاري ومرّره كـ fid إلى Reviews API أو Photos API المنفصلة. تُرجع تلك النقاط النهائية صفحة محدودة واحدة لكل طلب. ترتبط نظرة API العامة بحقول كل نقطة نهاية وأمثلتها وقواعد ترقيم الصفحات.

هل عناوين البريد الإلكتروني مضمّنة لكل نشاط تجاري؟

لا. اضبط extra على true لطلب إثراء جهات الاتصال المتاح. قد تكون المواقع الإلكترونية وعناوين البريد الإلكتروني والملفات الاجتماعية مفقودة. افحص enrichmentState وfieldStates واجعل البيانات غير المتاحة صريحة في تطبيقك.

كيف أختبر تكاملًا؟

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

انتقل إلى الخطوة التالية

ابنِ أول عملية بحث في خرائط Google.

أنشئ مفتاح API، واختر استعلامًا وموقعًا واحدًا، واقرأ بيانات الأنشطة التجارية المنظمة في الاستجابة نفسها.