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 فقط إذا تم تقديم الإحداثيات بشكل صريح أو إذا كان استنتاج الموقع الجغرافي من سياق معروف للمستخدم مناسبًا و ضروريًا للحصول على نتائج أفضل.

يوضّح المثال التالي كيفية استخدام 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 tool's MCP specification
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

مخطط الإدخال

رسالة الطلب الخاصة بـ SearchText

SearchTextRequest

تمثيل JSON 
{
  "textQuery": string,
  "languageCode": string,
  "regionCode": string,
  "pageSize": integer,
  "pageToken": 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 أرقام غير متاحة حاليًا.
pageSize

integer

اختيارية: تمثّل هذه السمة الحد الأقصى لعدد الأماكن المطلوب عرضها. قد تعرض الخدمة عددًا أقل من هذه القيمة.
pageToken

string

اختيارية: رمز مميز للصفحة تم تلقّيه من طلب SearchText سابق. قدِّم هذه السمة لاسترداد الصفحة التالية.

حقل الدمج _location_bias

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

object (LocationBias)

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

LocationBias

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

object (Circle)

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

دائرة

تمثيل JSON 
{
  "center": {
    object (google.type.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 (google.type.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,
  "nextPageToken": string
}
الحقول
places[]

object (PlaceView)

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

string

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

string

اختيارية: رمز مميز يمكن إرساله كـ page_token لاسترداد الصفحة التالية.

PlaceView

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

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

string

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

string

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

object (GoogleMapsLinks)

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

حقل الدمج _location

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

object (google.type.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"

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

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