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 (object – אופציונלי): משתמשים בפרמטר הזה כדי לתת עדיפות לתוצאות שקרובות לאזור גיאוגרפי ספציפי.

    • פורמט: {"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. אם צריך, מציינים את שם העיר, המדינה (State)/המחוז, האזור או המדינה כדי להבחין בין כמה מקומות עם אותו שם.

  • תמיד צריך לספק את 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

אופציונלי. השפה שבה רוצים לקבל את הסיכום. אם קוד השפה לא מצוין או לא מזוהה, יוחזר הסיכום עם העדפה לאנגלית.

לדוגמה, 'en' לאנגלית.

רשימת השפות הנתמכות הנוכחית: 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.

שיוך (Attribution)

ייצוג ב-JSON 
{
  "title": string,
  "url": string
}
שדות
title

string

השם שיוצג לשיוך.
url

string

כתובת ה-URL לקישור לצורך שיוך.

הערות בכלי

הערות על כלי נשלחות ללקוחות MCP כדי לתאר את הסיכון הבסיסי של כלי מסוים. רוב הלקוחות מתייחסים לרמזים האלה כאל רמזים לא מהימנים, אבל אפשר להשתמש בהם כדי להחליט מתי לשלוח למשתמש הנחיה לאישור.

בנוסף למחרוזת הכותרת, מוגדרים הרמזים הבוליאניים הבאים:

  • ‫readOnlyHint: אם הערך הוא true, הכלי לא משנה את הסביבה שלו. ברירת מחדל: false.
  • ‫destructiveHint: אם הערך הוא True, הכלי יכול לבצע פעולות הרסניות. אם הערך הוא false, הכלי יכול לבצע רק פעולות של הוספה. ברירת מחדל: true.
  • ‫idempotentHint: אם הערך הוא True, קריאה חוזרת לכלי עם אותם ארגומנטים לא תשפיע על הסביבה שלו. ברירת מחדל: false.
  • ‫openWorldHint: אם הערך הוא true, הכלי יכול ליצור אינטראקציה עם 'עולם פתוח' של ישויות חיצוניות. אם הערך הוא false, הכלי יכול ליצור אינטראקציה רק עם ישויות פנימיות. לדוגמה, כלי לחיפוש באינטרנט יהיה עולם פתוח, אבל כלי לזיכרון לא יהיה עולם פתוח.

רמז הרסני: ❌ | רמז אידמפוטנטי: ❌ | רמז לקריאה בלבד: ✅ | רמז לעולם פתוח: ❌