بيانات خرائط Google / خادم MCP

بيانات خرائط Google، داخل سير عمل الذكاء الاصطناعي لديك.

اعثر على الأنشطة التجارية واقرأ المراجعات العامة واستكشف معارض الأماكن مع Claude Code أو Cursor أو VS Code أو Codex. ثلاث أدوات عن بُعد. مفتاح API نفسه.

يعمل مع عميل MCP الخاص بك

Streamable HTTP عن بُعد · مفتاح API خاص · خطط API مجانية ومدفوعة

ثلاث أدوات / اتصال واحد

من اكتشاف الأنشطة التجارية إلى تفاصيل المكان.

تُرجع كل أداة نتيجتها مباشرة. اختر العملية التي تحتاجها مهمتك واجعل الصفحات المطلوبة صريحة.

اعثر على الأنشطة التجارية

search_google_maps

ابحث في فئة وموقع. استقبل حتى 20 نشاطًا تجاريًا مع حقول بطاقة البيانات والاتصال والتقييم وعدد المراجعات المتاحة.

q · page · extra

استكشف Search API

اقرأ المراجعات العامة

get_google_maps_reviews

استخدم معرّف ميزة مكان لطلب حتى 10 مراجعات. اختر الصلة أو الأحدث أو أعلى تقييم أو أدنى تقييم.

fid · page · sort_by

استكشف Reviews API

تصفّح وسائط المعرض

get_google_maps_photos

استرجع حتى 20 سجل بيانات وصفية للصور والفيديو لمكان واحد. اقرأ عناوين URL للوسائط وعلامة ترقيم الصفحات المُرجعة.

fid · page

استكشف Photos API

تقبل المراجعات والصور معرّف ميزة خرائط Google من place.dataId لنتيجة بحث. يستخدم البحث الصفحات 1–10؛ وتُرجع أدوات الوسائط next حتى يقرر وكيلك ما إذا كانت صفحة أخرى مطلوبة.

اتصال MCP

نقطة نهاية واحدة. مساحة عمل API الخاصة بك.

يتعامل عميلك مع التهيئة واكتشاف الأدوات، ثم يرسل مفتاح API الخاص بك مع كل طلب.

اتصال MCP عن بُعد
POST https://gmapscrawl.com/api/mcp
Authorization: Bearer <YOUR_API_KEY>
Content-Type: application/json
Accept: application/json, text/event-stream

إعداد العميل

اختر العميل الذي تعمل فيه.

أنشئ مفتاح API، ثم انسخ التهيئة لعميلك. احتفظ بالمفتاح في بيئته أو إعداد الإدخال المحمي.

أضف هذا الخادم إلى .mcp.json. اجعل GMSCRAPER_API_KEY متاحًا في البيئة التي تشغّل Claude Code.

{
  "mcpServers": {
    "google-maps-data": {
      "type": "http",
      "url": "https://gmapscrawl.com/api/mcp",
      "headers": {
        "Authorization": "Bearer ${GMSCRAPER_API_KEY}"
      }
    }
  }
}
وثائق Claude Code ↗

بعد حفظ التهيئة، أعد الاتصال وأكّد ظهور الأدوات الثلاث. اتبع دليل الإعداد خطوة بخطوة.

أول سير عمل لك

اتصل. اختبر صفحة واحدة. اقرأ النتيجة.

ابدأ بمفتاح تجريبي وبيانات محاكاة. انتقل إلى مفتاح فعلي عندما تكون مستعدًا لاستخدام حصة API الخاصة بك.

01

جهّز مساحة عملك

حدّد منتج API وأنشئ مفتاحًا تجريبيًا بـ scrapes:write. يجب أن تسمح خطة API الخاصة بك بـ MCP؛ Online والإضافة لهما حصص منفصلة.

أنشئ مفتاحًا
02

اكتشف أداة واستدعها

اتصل بعميلك، وافحص search_google_maps، واطلب صفحة واحدة. أنشئ معرّف طلب جديدًا للعمل الجديد واحتفظ به عند إعادة محاولة الطلب نفسه.

عرض إعداد العميل
03

استخدم الأنشطة التجارية المُرجعة

اقرأ structuredContent.businesses وtotal. ضع علامة على نتائج الاختبار كمحاكاة، وحافظ على القيم المفقودة، وتوقف بعد الصفحة المطلوبة.

افهم الحقول
استدعِ search_google_maps

استبدل معرّف الطلب لكل بحث جديد. هذا المثال لا ينفّذ طلبًا من الصفحة.

{
  "q": "coffee shops in Seattle",
  "page": 1,
  "hl": "en",
  "extra": false,
  "client_request_id": "replace-with-a-fresh-uuid"
}

ما الذي يعود

سجلات منظمة، في استجابة الأداة نفسها.

businesses
حتى 20 نشاطًا تجاريًا مُرجعًا؛ قد تكون الحقول مفقودة.
params + total
الاستعلام المُطبَّع والعدد في هذه الصفحة.
simulated + usage metadata
تحدد استجابات الاختبار بيانات التركيبة وتستخدم صفر وحدة طلب فعلية.
isError
افحص الخطأ قبل الإبلاغ عن نجاح أداة.

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

موجّهات مثال

سؤال مفيد. نقطة توقف واضحة.

استخدم هذه الموجّهات بعد الاتصال. وفّر معرّف ميزة حقيقيًا عند الحاجة، واطلب من وكيلك وضع علامة على نتائج الاختبار كمحاكاة.

ابنِ قائمة أنشطة تجارية مركّزة

“استخدم search_google_maps مرة واحدة لـ coffee shops in Seattle، الصفحة 1، extra false. أرجِع الأسماء والمواقع الإلكترونية وأرقام الهواتف والتقييمات وأعداد المراجعات من الأنشطة التجارية المُرجعة. اترك الحقول المفقودة فارغة واعرض تواريخ الملاحظة. توقف بعد هذه الصفحة.”

النتيجة المتوقعة

جدول بحد أقصى 20 نشاطًا تجاريًا مُرجعًا، مع الحفاظ على طوابع المصدر الزمنية والقيم المفقودة.

لخّص صفحة مراجعات واحدة

“للنشاط التجاري الذي حددته، استخدم place.dataId كـ fid. اطلب الصفحة 1 من get_google_maps_reviews مع sort_by 2. لخّص الموضوعات في هذه المراجعات المُرجعة فقط واستشهد بتواريخها. لا تجلب صفحات إضافية.”

النتيجة المتوقعة

ملخص محدود بحد أقصى 10 مراجعات، دون معاملة صفحة واحدة على أنها تجربة كل عميل.

افحص معرضًا واحدًا

“استخدم get_google_maps_photos لمعرّف الميزة الموفَّر هذا، الصفحة 1 فقط. اسرد حقول photoUrl المُرجعة وvideoUrl الاختيارية وأبلغ عمّا إذا كان next هو true. لا تنزّل ملفات ولا تجلب الصفحة التالية.”

النتيجة المتوقعة

حتى 20 سجل معرض وحالة ترقيم الصفحات المُرجعة، جاهزة لتطبيقك الخاص لفحصها.

REST + MCP

حصة API واحدة عبر الواجهتين.

يتوفر MCP على خطط API المجانية والمدفوعة. تستخدم كل صفحة مصدر فعلية ناجحة وحدة طلب API واحدة، بما في ذلك صفحة فارغة.

01

اختبر دون استخدام فعلي

تُرجع المفاتيح التجريبية تركيبات محاكاة بصفر وحدة طلب. إنها تتحقق من تكاملك بدلًا من إنتاج عملاء محتملين حقيقيين.

إدارة مفاتيح API
02

اجعل الطلبات محدودة

اطلب فقط الصفحات والمواقع التي تحتاجها مهمتك. استخدم معرّف طلب جديدًا للعمل الجديد؛ أعد محاولة الطلبات غير المؤكدة بالإدخال والمعرّف نفسيهما.

اقرأ إرشادات الاستخدام
03

أضف تعليمات قابلة لإعادة الاستخدام

تضيف مهارة الوكيل Google Maps Data إرشادات سير العمل ومراجع العمليات وبديل REST إلى الأدوات نفسها.

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

استكشف مركز API ← خطط Online والإضافة لها حصصها الخاصة.

مساعدة في الاتصال

الوصول إلى الطلب الناجح التالي.

استخدم حالة الاتصال والخطأ المُرجع لاختيار الخطوة التالية.

يتصل العميل لكن لا تظهر أدوات
أكّد أن نقطة النهاية هي /api/mcp وأن عميلك يدعم Streamable HTTP عن بُعد مع ترويسة Authorization خاصة. أعد تحميل الاتصال وتحقق من أن عمليته يمكنها قراءة المفتاح المهيأ.
401 أو 403
تحقق من انتهاء صلاحية المفتاح وعناوين IP المسموح بها ووصول مساحة العمل النشط ونطاق scrapes:write وخطة API تسمح بـ MCP. ملفات تعريف ارتباط تسجيل الدخول للمتصفح لا تُصادق نقطة النهاية.
invalid_request
اقرأ مخطط الأداة المحددة. وفّر client_request_id فريدًا من 16–128 حرفًا؛ تحتاج المراجعات والصور أيضًا إلى FID من place.dataId، وليس اسم نشاط تجاري أو معرّف مكان مختلف.
rate_limited أو quota_exceeded
احترم retry_after لحدود المعدل. توقف عند استنفاد حصة API وتحقق من استخدام API الخاص بك؛ إنشاء مفتاح آخر لا يضيف حصة.
capability_unavailable أو فشل في المصدر
تحقق من حالة الخدمة والخطأ المُرجع. يحدد الخادم التوفر. اجعل البيانات المفقودة أو غير المتاحة صريحة في نتيجتك.
مهلة أو isError: true
افحص خطأ الأداة حتى عند نجاح اتصال HTTP. للأخطاء القابلة لإعادة المحاولة، احتفظ بالإدخال ومعرّف الطلب نفسيهما ضمن موعد مهمتك النهائي. اتبع إرشادات الخطأ النهائي قبل بدء محاولة جديدة.

حالة الخدمة الأخطاء وإرشادات إعادة المحاولة

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

ماذا يمكن لخادم MCP لخرائط Google أن يفعل؟

يعرض search_google_maps وget_google_maps_reviews وget_google_maps_photos. يُرجع البحث حتى 20 نشاطًا تجاريًا؛ وتُرجع المراجعات حتى 10 سجلات والصور حتى 20 سجل معرض في الصفحة. تُرجع الأدوات بيانات منظمة مباشرة.

ما العملاء الذين يمكنني توصيلهم؟

استخدم إصدارًا من Claude Code أو Cursor أو VS Code أو Codex أو عميل MCP آخر يدعم Streamable HTTP عن بُعد وترويسة Authorization خاصة. تستخدم تهيئات العملاء الأربعة أعلاه نقطة النهاية نفسها ومفتاح مساحة عمل API نفسه.

كيف أُصادق؟

أنشئ مفتاح API بـ scrapes:write في مساحة عمل API الخاصة بك وهيّئه بشكل خاص كترويسة Bearer. ملفات تعريف ارتباط المتصفح لا تُصادق MCP. احتفظ بالمفاتيح خارج الموجّهات وعناوين URL والكود المصدري المُرسَل.

كيف تجد المراجعات والصور المكان الصحيح؟

مرّر معرّف ميزة خرائط Google كـ fid. يمكنك استخدام place.dataId من نشاط تجاري مُرجع. تقبل المراجعات أيضًا sort_by: 1 للصلة، و2 للأحدث، و3 لأعلى تقييم، و4 لأدنى تقييم. اقرأ next قبل التفكير في صفحة وسائط أخرى.

هل لدى MCP حصة منفصلة؟

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

هل أحتاج أيضًا إلى مهارة الوكيل؟

يعمل خادم MCP بمفرده. تضيف مهارة الوكيل Google Maps Data الاختيارية تعليمات قابلة لإعادة الاستخدام ومراجع عمليات ومساعد بديل REST عندما يكون اتصال MCP المهيأ غير متاح.

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

أدخل بيانات خرائط Google في محادثتك التالية.

أنشئ مفتاح API، واتصل بعميلك المفضل، واختبر بحثًا مركّزًا عن نشاط تجاري.