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 (سلسلة - اختيارية): رمز Unicode CLDR الخاص بمنطقة المستخدم. تُستخدَم هذه المَعلمة لعرض تفاصيل المكان، مثل اسم المكان الخاص بالمنطقة، إذا كان متاحًا. يمكن أن تؤثّر المَعلمة في النتائج استنادًا إلى القانون الساري.

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

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

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

  • احرص دائمًا على تقديم text_query الأكثر تحديدًا والأكثر ملاءمة للسياق.

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

  • يجب الإشارة إلى مصدر الناتج المستند إلى بيانات واقعية باستخدام المعلومات من الحقل attribution عند توفّرها.

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

طلب 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,

  // 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

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

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

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

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

حقل الربط _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
}
الحقول
places[]

object (PlaceView)

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

string

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

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: إذا كانت القيمة صحيحة، يمكن للأداة التفاعل مع "عالم مفتوح" من الكيانات الخارجية. إذا كانت القيمة false، يمكن للأداة التفاعل مع الكيانات الداخلية فقط. على سبيل المثال، ستكون أداة البحث على الويب عالمًا مفتوحًا، بينما لن تكون أداة الذاكرة عالمًا مفتوحًا.

تلميح تدميري: ❌ | تلميح متكرّر: ❌ | تلميح للقراءة فقط: ✅ | تلميح للعالم المفتوح: ❌