MCP Tools Reference: mapstools.googleapis.com

כלי: search_places

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

דרישות קלט (קריטיות):

  1. text_query (string - MANDATORY): The primary search 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. אם צריך להבחין בין כמה מיקומים, צריך לכלול את שם העיר, המדינה/המחוז והאזור/המדינה.

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

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

לדוגמה, '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 ספרות.
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 (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,
  "nextPageToken": string
}
שדות
places[]

object (PlaceView)

פלט בלבד. רשימת המקומות שמוזכרים בסיכום.
summary

string

פלט בלבד. סיכום בשפה טבעית של תוצאות החיפוש. הסיכום עשוי להכיל ציטוטים מבוססי-אפס כמו [0],‏ [1],‏ [2] וכו'. הציטוטים האלה ממופים למקומות המתאימים בשדה places.
nextPageToken

string

אופציונלי. טוקן שאפשר לשלוח כ-page_token כדי לאחזר את הדף הבא.

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 לקישור לצורך שיוך.

הערות על כלי

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