MCP Tools Reference: mapstools.googleapis.com

الأداة: search_places

يمكنك استدعاء هذه الأداة عندما يكون طلب المستخدم هو العثور على أماكن أو مؤسسات أو عناوين أو مواقع جغرافية أو معالم أو أي بحث آخر ذي صلة بـ "خرائط Google".

متطلبات الإدخال (مهمة):

  1. text_query (سلسلة - إلزامية): طلب البحث الأساسي. يجب أن يحدّد هذا بوضوح ما يبحث عنه المستخدم.

    • أمثلة: 'restaurants in New York' و'coffee shops near Golden Gate Park' و'SF MoMA' و'1600 Amphitheatre Pkwy, Mountain View, CA, USA' و'pets friendly parks in Manhattan, New York' و'date night restaurants in Chicago' و'accessible public libraries in Los Angeles'.
    • للحصول على تفاصيل مكان محدّد: أدرِج السمة المطلوبة (مثل 'Google Store Mountain View opening hours' أو 'SF MoMa phone number' أو 'Shoreline Park Mountain View address').

  2. ‫location_bias (عنصر - اختياري): استخدِم هذه المَعلمة لتحديد أولوية النتائج القريبة من منطقة جغرافية معيّنة.

    • التنسيق: {"location_bias": {"circle": {"center": {"latitude": [value], "longitude": [value]}, "radius_meters": [value (optional)]}}}
    • الاستخدام:
      • للانحياز إلى نطاق جغرافي يبلغ 5 كيلومتر: {"location_bias": {"circle": {"center": {"latitude": 34.052235, "longitude": -118.243683}, "radius_meters": 5000}}}
      • للانحياز بشدة إلى النقطة المركزية: {"location_bias": {"circle": {"center": {"latitude": 34.052235, "longitude": -118.243683}}}} (مع حذف radius_meters).

  3. language_code (سلسلة - اختيارية): اللغة التي سيظهر بها ملخّص نتائج البحث.

    • التنسيق: رمز لغة مكوّن من حرفَين (ISO 639-1)، متبوعًا اختياريًا بشرطة سفلية ورمز بلد مكوّن من حرفَين (ISO 3166-1 alpha-2)، مثل en أو ja أو en_US أو zh_CN أو es_MX. إذا لم يتم تقديم رمز اللغة، ستكون النتائج باللغة الإنجليزية.

  4. ‫region_code (سلسلة - اختياري): رمز CLDR للمنطقة بتنسيق Unicode الخاص بالمستخدم تُستخدَم هذه المَعلمة لعرض تفاصيل المكان، مثل اسم المكان الخاص بالمنطقة، إذا كان متاحًا. يمكن أن تؤثر المَعلمة في النتائج استنادًا إلى القانون الساري.

    • التنسيق: رمز بلد مكوّن من حرفَين (ISO 3166-1 alpha-2)، مثل US وCA.

  5. page_size (عدد صحيح - اختياري): الحد الأقصى لعدد الأماكن المطلوب عرضها، من 1 إلى 10. القيمة التلقائية هي 5. يجب ضبط القيمة على أكثر من 5 فقط عندما يريد المستخدم مقارنة أكثر من 5 أماكن. تؤدي القيم من 6 إلى 10 إلى زيادة التكلفة وزيادة وقت الاستجابة.

  6. include_extended_details (قيمة منطقية - اختياري): اضبط هذا الحقل على true عندما يتطلّب طلب المستخدم إحصاءات نوعية غنية أو ديناميكيات في الوقت الفعلي أو سمات كيانات متخصّصة. القيمة التلقائية هي false. يؤدي ضبط هذه القيمة على true إلى زيادة التكلفة وزمن الاستجابة.

تعليمات طلب استخدام الأداة:

  • معلومات عن الموقع الجغرافي للجهاز (مهمة): يجب أن يحتوي البحث على معلومات كافية عن الموقع الجغرافي للجهاز. إذا كان الموقع الجغرافي غامضًا (مثل "مطاعم بيتزا" فقط)، يجب تحديده في text_query (مثل "مطاعم بيتزا في نيويورك") أو استخدام المَعلمة location_bias. أدرِج اسم المدينة والولاية/المقاطعة والمنطقة/البلد إذا لزم الأمر لإزالة الغموض.

  • يجب دائمًا تقديم text_query الأكثر تحديدًا وثراءً بالسياق قدر الإمكان.

  • يجب استخدام location_bias فقط إذا تم توفير الإحداثيات بشكل صريح أو إذا كان استنتاج الموقع الجغرافي من سياق المستخدم المعروف مناسبًا وضروريًا للحصول على نتائج أفضل.

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

يوضّح نموذج الرمز البرمجي التالي كيفية استخدام curl لاستدعاء أداة MCP‏ search_places.

طلب Curl 
curl --location 'https://mapstools.googleapis.com/mcp' \
--header 'content-type: application/json' \
--header 'accept: application/json, text/event-stream' \
--data '{
  "method": "tools/call",
  "params": {
    "name": "search_places",
    "arguments": {
      // Provide these details according to the MCP tool specification.
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

مخطط الإدخال

رسالة طلب لـ SearchText

SearchTextRequest

تمثيل JSON 
{
  "textQuery": string,
  "languageCode": string,
  "regionCode": string,
  "pageSize": integer,
  "includeExtendedDetails": boolean,

  // Union field _location_bias can be only one of the following:
  "locationBias": {
    object (LocationBias)
  }
  // End of list of possible types for union field _location_bias.
}
الحقول
textQuery

string

الحقل مطلوب. طلب البحث النصي
languageCode

string

اختياريّ. اللغة التي تريد أن يظهر بها الملخّص إذا لم يتم تحديد رمز اللغة أو لم يتم التعرّف عليه، سيتم عرض الملخّص باللغة الإنجليزية.

على سبيل المثال، "ar" للغة العربية.

يمكنك الاطّلاع على القائمة الحالية للّغات المتاحة على الرابط: https://developers.google.com/maps/faq#languagesupport.
regionCode

string

اختياريّ. رمز البلد/المنطقة (CLDR) بتنسيق Unicode للموقع الجغرافي الذي يأتي منه الطلب تُستخدَم هذه المَعلمة لعرض تفاصيل المكان، مثل اسم المكان الخاص بالمنطقة، إذا كان متاحًا. يمكن أن تؤثّر المَعلمة في النتائج استنادًا إلى القانون الساري.

على سبيل المثال، "US" للولايات المتحدة.

لمزيد من المعلومات، يُرجى الاطّلاع على https://www.unicode.org/cldr/charts/latest/supplemental/territory_language_information.html.

يُرجى العِلم أنّ رموز المناطق المكوّنة من 3 أرقام غير متاحة حاليًا.
pageSize

integer

اختياريّ. الحد الأقصى لعدد الأماكن التي سيتم عرضها، وهو 10 أماكن. قد تعرض الخدمة عددًا أقل من هذه القيمة. القيمة التلقائية هي 5.

سيؤدي طلب أكثر من 5 أماكن إلى تفعيل فئة Pro وزيادة تكلفة الفوترة وزمن الاستجابة.
includeExtendedDetails

boolean

اختياريّ. يتضمّن تفاصيل المكان الموسّعة في الردّ.

اضبط هذا الحقل على true عندما يتطلّب طلب المستخدم إحصاءات نوعية غنية أو ديناميكيات في الوقت الفعلي أو سمات كيانات متخصّصة: - المراجعات النوعية وآراء العملاء وملاحظاتهم. - عروض معيّنة، مثل أصناف قائمة الطعام أو الأطباق أو الأطعمة الخاصة أو المشروبات أو الميزات البارزة للنشاط التجاري - الأجواء النوعية أو الديكور الداخلي أو الجماليات أو الأجواء أو الحالة المزاجية. - بيانات في الوقت الفعلي ومواصفات المنشآت المتخصّصة وسياسات/نصائح الزوّار وأوقات الانتظار

اترك القيمة false (القيمة التلقائية) لعمليات البحث العادية عن الأماكن (مثل أنواع المأكولات وأنواع المتاجر) وعمليات البحث عن المواقع الجغرافية/العناوين ومعلومات الاتصال وساعات العمل والبيانات الوصفية/وسائل الراحة العادية.

سيؤدي تفعيل هذا الحقل إلى تفعيل المستوى Pro، ما يؤدي إلى زيادة التكلفة الواردة في الفاتورة وزيادة وقت الاستجابة.

حقل الربط _location_bias

يمكن أن يكون التعليق _location_bias إحدى القيم التالية فقط:
locationBias

object (LocationBias)

منطقة اختيارية لتوجيه نتائج البحث إليها إذا كان هناك موقع جغرافي صريح في text_query، سيتم استخدامه لتوجيه نتائج البحث بدلاً من هذا الحقل.

LocationBias

تمثيل JSON 
{
  "circle": {
    object (Circle)
  }
}
الحقول
circle

object (Circle)

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

دائرة

تمثيل JSON 
{
  "center": {
    object (LatLng)
  },

  // Union field _radius_meters can be only one of the following:
  "radiusMeters": number
  // End of list of possible types for union field _radius_meters.
}
الحقول
center

object (LatLng)

الحقل مطلوب. النقطة المركزية للدائرة

حقل الربط _radius_meters

يمكن أن يكون التعليق _radius_meters إحدى القيم التالية فقط:
radiusMeters

number

نصف قطر الدائرة بالأمتار يجب أن يكون نصف القطر ضمن 50,000 متر.

LatLng

تمثيل JSON 
{
  "latitude": number,
  "longitude": number
}
الحقول
latitude

number

خط العرض بالدرجات يجب أن يكون في النطاق [-90.0, +90.0].
longitude

number

خط الطول بالدرجات ويجب أن يكون في النطاق [-180.0, +180.0].

مخطط النتائج

رسالة الردّ لـ SearchText

SearchTextResponse

تمثيل JSON 
{
  "places": [
    {
      object (PlaceView)
    }
  ],
  "summary": string,
  "contentToken": string
}
الحقول
places[]

object (PlaceView)

النتائج فقط. قائمة الأماكن المذكورة في الملخّص
summary

string

النتائج فقط. ملخّص بلغة طبيعية لنتائج البحث قد يحتوي الملخّص على اقتباسات تستند إلى الصفر، مثل "[0]" و"[1]" و"[2]" وما إلى ذلك. يتم ربط هذه الاقتباسات بالأماكن المقابلة في الحقل places.
contentToken

string

النتائج فقط. هو رمز مميّز مشفّر يتضمّن سياق البحث ويمكن تمريره إلى خدمات العرض المرئي في "خرائط Google" أو حِزم تطوير البرامج (SDK) أو "أدوات واجهة المستخدم الموجهة للوكلاء الذكيين في خرائط Google" لعرض مكوّنات واجهة مستخدم تفاعلية لنتائج البحث المعروضة.

PlaceView

تمثيل JSON 
{
  "place": string,
  "id": string,
  "googleMapsLinks": {
    object (GoogleMapsLinks)
  },
  "attribution": {
    object (Attribution)
  },

  // Union field _location can be only one of the following:
  "location": {
    object (LatLng)
  }
  // End of list of possible types for union field _location.
}
الحقول
place

string

اسم المورد للمكان الأساسي، بالتنسيق "places/{id}".
id

string

رقم تعريف المكان الأساسي
googleMapsLinks

object (GoogleMapsLinks)

روابط لتنفيذ إجراءات مختلفة في "خرائط Google"
attribution

object (Attribution)

يجب عرض مصدر الصورة مع المكان.

حقل الربط _location

يمكن أن يكون التعليق _location إحدى القيم التالية فقط:
location

object (LatLng)

موضع هذا المكان

LatLng

تمثيل JSON 
{
  "latitude": number,
  "longitude": number
}
الحقول
latitude

number

خط العرض بالدرجات يجب أن يكون في النطاق [-90.0, +90.0].
longitude

number

خط الطول بالدرجات ويجب أن يكون في النطاق [-180.0, +180.0].
تمثيل JSON 
{
  "directionsUrl": string,
  "placeUrl": string,
  "writeAReviewUrl": string,
  "reviewsUrl": string,
  "photosUrl": string
}
الحقول
directionsUrl

string

رابط لعرض الاتجاهات إلى المكان يملأ الرابط الموقع الجغرافي للوجهة فقط ويستخدم وضع السفر التلقائي DRIVE.
placeUrl

string

رابط لعرض هذا المكان
writeAReviewUrl

string

رابط لكتابة مراجعة عن هذا المكان على "خرائط Google"
reviewsUrl

string

رابط لعرض مراجعات هذا المكان على "خرائط Google"
photosUrl

string

رابط لعرض صور هذا المكان على "خرائط Google"

تحديد المصدر

تمثيل JSON 
{
  "title": string,
  "url": string
}
الحقول
title

string

العنوان الذي سيتم عرضه في المصدر
url

string

عنوان URL الذي سيتم ربطه بمصدر المحتوى

التعليقات التوضيحية للأدوات

يتم إرسال تعليقات توضيحية للأدوات إلى عملاء MCP لوصف المخاطر الأساسية لأداة معيّنة. تتعامل معظم البرامج مع هذه التلميحات على أنّها غير موثوق بها، ولكن يمكن استخدامها لتحديد الحالات التي قد يتم فيها إرسال طلب تأكيد إلى المستخدم.

إلى جانب سلسلة العنوان، يتم تحديد التلميحات المنطقية التالية على النحو التالي:

  • ‫readOnlyHint: إذا كانت القيمة "صحيح"، لا تعدّل الأداة بيئتها. القيمة التلقائية: false
  • ‫destructiveHint: إذا كانت القيمة "صحيح"، يمكن للأداة تنفيذ إجراءات مدمّرة. إذا كانت القيمة "خطأ"، يمكن للأداة تنفيذ إجراءات إضافية فقط. القيمة التلقائية: true
  • ‫idempotentHint: إذا كانت القيمة "صحيح"، لن يؤدي استدعاء الأداة بشكل متكرّر باستخدام الوسيطات نفسها إلى أي تأثير إضافي على بيئتها. القيمة التلقائية: false
  • ‫openWorldHint: إذا كانت القيمة "صحيح"، يمكن للأداة التفاعل مع "عالم مفتوح" من الكيانات الخارجية. إذا كانت القيمة "خطأ"، يمكن للأداة التفاعل مع الكيانات الداخلية فقط. على سبيل المثال، أداة بحث الويب هي أداة عالم مفتوح، بينما أداة الذاكرة ليست كذلك.

Destructive Hint: ❌ | Idempotent Hint: ❌ | Read Only Hint: ✅ | Open World Hint: ❌