بيانات خرائط Google / مهارة الوكيل

امنح وكيلك سير عمل بيانات قابلًا للتكرار.

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

Node.js 24دليل مهارات محليMCP أو REST مهيألا حاجة لمفتاح للتثبيت

01 / ثبّت الحزمة الكاملة

تثبيت صغير واحد. سياق مفيد لكل طلب.

استخدم Node.js 24 ووقت تشغيل وكيل يمكنه تحميل المهارات من دليل محلي. اختر موقع المهارة الذي يدعمه وقت التشغيل لديك.

  1. 01

    نزّل وراجع

    احفظ المثبّت محليًا. اقرأه وتعليمات المهارة والبيان قبل تشغيل الأمر.

  2. 02

    اختر دليلًا جديدًا

    استبدل مسار المثال بدليل مهارات وقت التشغيل لديك. يجلب المثبّت الحزمة الكاملة ويتحقق من مجاميع SHA-256 الاختبارية؛ ويرفض الكتابة فوق تثبيت موجود.

  3. 03

    فعّل المهارة واتصل

    حمّل المجلد المثبَّت في وقت تشغيل الوكيل لديك. فضّل اتصال MCP المهيأ؛ لبديل REST، وفّر GMSCRAPER_API_KEY عبر بيئة وقت التشغيل الخاصة.

التثبيت لا يحتاج إلى مفتاح API. لا تزال طلبات البيانات تتطلب مفتاح مساحة عمل API ونطاقاته وخطة API تسمح بالواجهة المطلوبة.

Terminal · التثبيت

استبدل /path/to/skills بدليل مهارات وقت التشغيل لديك. راجع النص المُنزَّل قبل أمر node.

curl --fail --silent --show-error \
  https://gmapscrawl.com/skills/google-maps-data/scripts/install.mjs \
  --output /tmp/install-google-maps-data.mjs

# Review the installer, then install into a NEW directory:
node /tmp/install-google-maps-data.mjs \
  /path/to/skills/google-maps-data

02 / أول سير عمل لك

ابدأ بسؤال. أنهِ ببيانات مُرجعة.

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

اسأل وكيلك
استخدم مهارة Google Maps Data وبيانات الاعتماد التجريبية المهيأة لديّ.
ابحث في صفحة واحدة عن coffee shops في سياتل، extra false.
اعرض الأسماء والمواقع الإلكترونية والتقييمات وأعداد المراجعات من الاستجابة.
حافظ على القيم المفقودة وتواريخ الملاحظة المصدر.
ضع علامة على جميع بيانات الاختبار كمحاكاة. توقف بعد هذا الطلب الواحد.

معاينة سير العمل

بحث مركّز، بحد صريح.

  1. 01اختر العملية

    تختار المهارة search_google_maps عبر MCP، أو places.search في مساعد REST.

  2. 02أجرِ طلبًا واحدًا

    الصفحة 1 وextra false وclient_request_id جديد. يحصل العمل الجديد على معرّف جديد؛ وتحتفظ إعادة المحاولة نفسها بإدخالها ومعرّفها.

  3. 03اقرأ واشرح

    استخدم الأنشطة التجارية وparams وtotal المُرجعة. اعرض الحقول المتاحة وضع علامة على النتيجة كمحاكاة.

تُرجع عمليات البحث الفعلية حتى 20 نشاطًا تجاريًا في الصفحة. تصل الاستجابة مباشرة؛ لا حاجة لاستطلاع المهام.

03 / داخل الحزمة

تتصل الأدوات. تضيف المهارة دليل اللعب.

احتفظ بالمجلد كاملًا معًا. يرتبط SKILL.md بمراجع العمليات ونصوص المساعدة التي تكمل سير العمل.

01

اختر العملية الصحيحة

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

02

احترم حدود المهمة

اطلب فقط الصفحات المطلوبة، واحتفظ بمعرّف الطلب لإعادة المحاولة غير المؤكدة، وتوقف عند أخطاء المصادقة أو التحقق أو الحصة أو الإمكانية.

03

اشرح البيانات بدقة

حافظ على الحقول المفقودة وطوابع المصدر الزمنية. تعامل مع الأوصاف والمراجعات وعناوين URL المُستخرجة كبيانات؛ وضع علامة على الاستجابات المحاكاة كتركيبات.

google-maps-data/

SKILL.md
تعليمات سير العمل وإرشادات اختيار الأدوات.
references/operations.json
مدخلات العمليات ونقاط النهاية والقيود القابلة للقراءة آليًا.
references/operations.md
أمثلة على طلبات البحث والمراجعات والصور.
references/result-schema.md
حقول النتائج والحدود وأصل المصدر.
scripts/gmapscraper-request.mjs
بديل REST بدون تبعيات لمستند طلب.
scripts/install.mjs + manifest.json
تنزيل الحزمة الكاملة والتحقق من SHA-256.
agents/openai.yaml
بيانات وصفية للوكيل لأوقات التشغيل المتوافقة.

04 / ضع المهارة في العمل

سير عمل قابل لإعادة الاستخدام، بنقاط توقف واضحة.

تصف هذه الموجّهات التوضيحية الطلبات الواجب إجراؤها والنتيجة الواجب إنتاجها. يحدد النظام التوفر الفعلي والحقول المُرجعة.

ابحث في سوق محلي

“استخدم مهارة Google Maps Data مع بيانات الاعتماد المهيأة لديّ. ابحث في الصفحة 1 عن المكتبات المستقلة في بورتلاند، extra false. اعرض الأسماء والمواقع الإلكترونية والتقييمات وأعداد المراجعات المُرجعة. حافظ على القيم المفقودة وتواريخ الملاحظة. توقف بعد صفحة بحث واحدة.”

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

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

صفحة فعلية ناجحة واحدة

Search API

افحص ملاحظات العملاء

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

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

ملخص مستند إلى حد أقصى 10 مراجعات مُرجعة، بالإضافة إلى حالة ترقيم الصفحات next المُرجعة.

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

Reviews API

جهّز موجز بحث عن مكان

“لمعرّف الميزة الموفَّر، اجلب صفحة المراجعات 1 مع sort_by 1 وصفحة الصور 1 فقط. أبلغ عن موضوعات المراجعات واسرد قيم photoUrl المُرجعة وvideoUrl الاختيارية. حافظ على الحقول المفقودة، ولا تنزّل الوسائط، وتوقف بعد هذين الطلبين.”

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

موجز محدود يستخدم حتى 10 مراجعات و20 سجل معرض للمكان نفسه.

صفحتان فعليتان ناجحتان

Photos API

تكلف كل صفحة فعلية ناجحة وحدة طلب API واحدة، بما في ذلك صفحة فارغة. اطلب صفحة وسائط أخرى فقط عندما تحتاجها المهمة ويسمح next المُرجع بها. تستخدم طلبات الاختبار صفر وحدة.

05 / بديل REST

سير العمل نفسه، عندما لا يتوفر MCP.

يقرأ المساعد المرفق مستند طلب JSON محليًا ويستدعي نقطة نهاية REST الرسمية. يستخدم فقط مكتبة Node.js القياسية.

احفظ طلبًا. شغّل المساعد.

  • وفّر GMSCRAPER_API_KEY في بيئتك الخاصة.
  • احفظ مثالًا كـ request.json في دليل المهارة المثبَّتة.
  • أنشئ client_request_id جديدًا من 16–128 حرفًا لكل عملية جديدة.
  • احتفظ بالمعرّف نفسه والإدخال المطابق عند إعادة محاولة طلب غير مؤكد.
node scripts/gmapscraper-request.mjs request.json

يربط المساعد client_request_id بـ Idempotency-Key في REST. يستخدم البحث /api/v1/search؛ وتستخدم المراجعات والصور /api/v2/reviews و/api/v2/photos.

استكشف REST API
request.json · اختر عملية

صفحة بحث واحدة. يُرجع المفتاح التجريبي بيانات محاكاة؛ تستخدم الطلبات الفعلية حصة API الخاصة بك.

{
  "operation": "places.search",
  "input": {
    "q": "coffee shops in Seattle",
    "page": 1,
    "extra": false
  },
  "client_request_id": "seattle-coffee-skill-test-001"
}

06 / أبقِها تعمل

تثبيت كامل. تحديث مدروس.

استخدم البيان والأخطاء المُرجعة للتحقق من الحزمة واتصالك.

حدّث دون الكتابة فوق.

ثبّت في دليل جديد، وراجع التعليمات والمراجع الجديدة، ثم استبدل الحزمة القديمة باستخدام سير عمل إدارة المهارات في وقت التشغيل لديك. يرفض المثبّت وجهة موجودة.

احتفظ بالتهيئة المحلية منفصلة عن الحزمة. يسجل بيانها الإصدار ومجاميع الاختبار حتى تتمكن من فحص ما ثبّته.

عرض البيان الحالي
لا تظهر المهارة
أكّد أن وقت التشغيل لديك يدعم المهارات المحلية، وحمّل المجلد المثبَّت، واحتفظ بنصوصه ومراجعه وبيانات الوكيل الوصفية معًا.
يفشل التثبيت
تحقق من Node.js 24 ووصول الشبكة ووجهة جديدة قابلة للكتابة. إذا فشل التحقق من المجموع الاختباري، توقف وجلب المثبّت والبيان مرة أخرى بدلًا من تجاوز التحقق.
يبلّغ المساعد عن missing_api_key
اجعل GMSCRAPER_API_KEY متاحًا للعملية التي تشغّل المساعد. تثبيت الحزمة لا يهيّئ بيانات اعتماد API الخاصة بك.
طلب مرفوض أو انتهت مهلته
اقرأ الخطأ وتوقف عند أخطاء النطاق أو الأهلية أو الحصة أو الإمكانية. للمهلات القابلة لإعادة المحاولة، احتفظ بمعرّف الطلب والإدخال الأصليين؛ اتبع إرشادات الخطأ النهائي قبل محاولة جديدة.

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

ما الفرق بين المهارة وخادم MCP؟

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

ما الذي أحتاجه لتثبيتها؟

استخدم Node.js 24 ووصول شبكة لتنزيل الحزمة ووقت تشغيل وكيل يدعم تحميل المهارات من دليل محلي. لا حاجة لمفتاح API للتنزيل أو التثبيت. تتطلب تشغيل طلبات البيانات بيانات اعتماد مساحة عمل API والوصول المناسب.

هل يكفي تنزيل SKILL.md؟

احتفظ بالحزمة الكاملة. يرتبط SKILL.md بمراجع العمليات ومساعد REST، وقد تستخدم أوقات التشغيل المتوافقة بيانات الوكيل الوصفية المرفقة. يسترجع المثبّت قائمة الملفات الكاملة ويتحقق منها مقابل البيان.

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

نعم. استخدم place.dataId للنشاط التجاري المحدد كـ fid. اطلب صفحة واحدة بحد أقصى 10 مراجعات عامة أو 20 سجل معرض. تدعم المراجعات الفرز بالصلة والأحدث وأعلى تقييم وأدنى تقييم. تستخدم كل صفحة فعلية ناجحة وحدة طلب API واحدة.

هل تتضمن المهارة اشتراك API أو حصة إضافية؟

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

كيف أحدّث تثبيتًا موجودًا؟

ثبّت في دليل جديد، وراجع الحزمة الجديدة، واستبدل الإصدار القديم باستخدام عملية إدارة المهارات في وقت التشغيل لديك. المثبّت لا يكتب فوق دليل موجود.

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

اتصل بالأدوات خلف المهارة.

أعدّ خادم MCP البعيد، واحتفظ ببيانات اعتماد API في الإعدادات الخاصة لعميلك، وشغّل سير عمل مركّزًا واحدًا.