MCP Tools Reference: mapstools.googleapis.com

כלי: resolve_names

הפונקציה פותרת רשימה של שאילתות לגבי מיקומים ספציפיים (שמות של ציוני דרך או כתובות מדויקות) למזהים קנוניים של מקומות במפות Google.

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

  1. ‫queries (מערך של אובייקטים – חובה): רשימה של שאילתות למיקום שצריך לפתור. אפשר לציין עד 20 שאילתות.

    • לכל אובייקט שאילתה צריכים להיות המאפיינים הבאים:
      • text (מחרוזת – חובה): שאילתת הטקסט שמייצגת שם של מקום ספציפי או כתובת שרוצים לפתור.
        • דוגמאות: 'Googleplex, Mountain View, CA', ‏ '1600 Amphitheatre Pkwy, Mountain View, CA', ‏ 'Eiffel Tower, Paris'.

  2. ‫location_bias (object – אופציונלי): משתמשים בפרמטר הזה כדי לתת עדיפות לתוצאות שקרובות לאזור גיאוגרפי ספציפי.

    • פורמט: {"viewport": {"low": {"latitude": [value], "longitude": [value]}, "high": {"latitude": [value], "longitude": [value]}}}

  3. ‫region_code (מחרוזת – אופציונלי): קוד האזור של CLDR ב-Unicode (קוד מדינה בן שתי אותיות, למשל US, CA) של המשתמש, כדי להטות את התוצאות.

הוראות לשימוש בכלי:

  • ספציפיות (קריטי): השאילתות צריכות לייצג שם מקום או כתובת ספציפיים. אין תמיכה בחיפושים כלליים כמו 'restaurants' או בשמות של רשתות כמו 'Starbucks'.
  • אל תתקשרו לכלי הזה אם הכלים במורד הזרם שאתם מתכננים להפעיל כבר מקבלים ישירות מחרוזות של כתובות גולמיות או שמות מקומות.

Error Handling (CRITICAL):

  • זהו כלי לעיבוד קבוצתי. יכול להיות שבקשה תחזיר "תוצאות מעורבות" (למשל, חלק מהשאילתות יסתיימו בהצלחה וחלק ייכשלו).
  • מובטח שרשימת הפלט של results תמופה ביחס של 1:1 עם האינדקסים של הקלט queries. שאילתה שנכשלה תניב הודעה ריקה Result (לא מוגדר entity) באינדקס המתאים ברשימה results.
  • חובה לבדוק את שדה המפה failed_requests בתגובה כדי לזהות את האינדקס הספציפי של השאילתה שנכשלה. המפתח של failed_requests מייצג את האינדקס של השאילתה שנכשלה בבקשה, החל מ-0. אל תניחו שהקריאה כולה נכשלה בגלל כשל חלקי.

בדוגמה הבאה אפשר לראות איך משתמשים ב-curl כדי להפעיל את כלי ה-MCP‏ resolve_names.

בקשת 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": "resolve_names",
    "arguments": {
      // provide these details according to the tool's MCP specification
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

סכימת הקלט

הודעת בקשה ל-ResolveNames.

ResolveNamesRequest

ייצוג ב-JSON 
{
  "queries": [
    {
      object (LocationQuery)
    }
  ],
  "locationBias": {
    object (LocationBias)
  },
  "regionCode": string
}
שדות
queries[]

object (LocationQuery)

חובה. רשימה של שאילתות מיקום שצריך לפתור. אפשר לציין עד 20 שאילתות.
locationBias

object (LocationBias)

אופציונלי. אזור אופציונלי להטיית תוצאות ההחלטה. אם מציינים אזור, תוצאות ההפרדה יתמקדו בישויות שקרובות יותר לאזור הזה. לרוב, הוספה של location_bias או region_code משפרת את התוצאות כי היא מצמצמת את מרחב החיפוש.

אם מציינים גם את location_bias וגם את region_code, location_bias מקבל עדיפות על פני region_code.
regionCode

string

אופציונלי. קוד אזור אופציונלי להטיית תוצאות ההמרה. אם מציינים אזור, תוצאות ההחלטה יתמקדו בישויות שנמצאות באזור שצוין או בקרבתו. הקוד צריך להיות קוד אזור בפורמט CLDR. לדוגמה, 'US' או 'CA'. לרוב, הוספה של location_bias או region_code משפרת את התוצאות כי היא מצמצמת את מרחב החיפוש.

אם מציינים גם את location_bias וגם את region_code, location_bias מקבל עדיפות על פני region_code.

LocationQuery

ייצוג ב-JSON 
{
  "text": string
}
שדות
text

string

חובה. שאילתת הטקסט שצריך לפתור כדי להגיע לישות גיאוספציאלית ספציפית במפות Google, כמו מקום או כתובת. ככל שהשאילתה ספציפית יותר, כך הפתרון מדויק יותר. לדוגמה: 'סן פרנסיסקו', 'Googleplex, Mountain View, CA',‏ '1600 Amphitheatre Parkway, Mountain View, CA' או 'מגדל אייפל, פריז'. השאילתות צריכות להיות כתובת ספציפית או שם של מקום. אין תמיכה במיקומים כלליים כמו שם של רשת (למשל, Starbucks) או שאילתת חיפוש כמו 'מסעדות'.

LocationBias

ייצוג ב-JSON 
{

  // Union field type can be only one of the following:
  "viewport": {
    object (Viewport)
  }
  // End of list of possible types for union field type.
}
שדות
שדה איחוד type. סוג הטיית המיקום. הערך type יכול להיות רק אחד מהבאים:
viewport

object (Viewport)

אזור תצוגה שמוגדר על ידי תיבה תוחמת.

אזור התצוגה

ייצוג ב-JSON 
{
  "low": {
    object (LatLng)
  },
  "high": {
    object (LatLng)
  }
}
שדות
low

object (LatLng)

חובה. הנקודה הנמוכה של אזור התצוגה.
high

object (LatLng)

חובה. הנקודה הגבוהה ביותר בחלון התצוגה.

LatLng

ייצוג ב-JSON 
{
  "latitude": number,
  "longitude": number
}
שדות
latitude

number

קו הרוחב במעלות. הערך חייב להיות בטווח [‎-90.0, ‎+90.0].
longitude

number

קו האורך במעלות. הערך חייב להיות בטווח [‎-180.0, ‎+180.0].

סכימת הפלט

הודעת התגובה ל-ResolveNames.

ResolveNamesResponse

ייצוג ב-JSON 
{
  "results": [
    {
      object (Result)
    }
  ],
  "failedRequests": {
    integer: {
      object (Status)
    },
    ...
  }
}
שדות
results[]

object (Result)

פלט בלבד. רשימת הישויות שנפתרו משאילתות המיקום. מובטח שהמיפוי יהיה 1:1 עם האינדקסים של הבקשה queries. מחרוזת ריקה באינדקס i מציינת שהפענוח נכשל עבור השאילתה הזו. אם הפענוח נכשל, צריך לבדוק את השדה failed_requests כדי לראות את סטטוס השגיאה.
failedRequests

map (key: integer, value: object (Status))

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

אובייקט שמכיל רשימה של "key": value זוגות. לדוגמה: { "name": "wrench", "mass": "1.3kg", "count": "3" }.

תוצאה

ייצוג ב-JSON 
{
  "entity": {
    object (Entity)
  },
  "confidence": enum (Confidence)
}
שדות
entity

object (Entity)

פלט בלבד. הישות שנפתרה משאילת המיקום.
confidence

enum (Confidence)

פלט בלבד. רמת המהימנות של הפתרון.

ישות

ייצוג ב-JSON 
{

  // Union field entity can be only one of the following:
  "place": string
  // End of list of possible types for union field entity.
}
שדות
שדה איחוד entity. סוג הישות שזוהה. הערך entity יכול להיות רק אחד מהבאים:
place

string

שם המשאב של המקום שנמצא.

FailedRequestsEntry

ייצוג ב-JSON 
{
  "key": integer,
  "value": {
    object (Status)
  }
}
שדות
key

integer
value

object (Status)

סטטוס

ייצוג ב-JSON 
{
  "code": integer,
  "message": string,
  "details": [
    {
      "@type": string,
      field1: ...,
      ...
    }
  ]
}
שדות
code

integer

קוד הסטטוס, שצריך להיות ערך enum של google.rpc.Code.
message

string

הודעת שגיאה שמוצגת למפתח, שצריכה להיות באנגלית. כל הודעת שגיאה שמוצגת למשתמש צריכה להיות מותאמת לשפה המקומית ולהישלח בשדה google.rpc.Status.details, או להיות מותאמת לשפה המקומית על ידי הלקוח.
details[]

object

רשימה של הודעות שכוללות את פרטי השגיאה. יש קבוצה משותפת של סוגי הודעות לשימוש בממשקי API.

אובייקט שמכיל שדות מסוג שרירותי. שדה נוסף "@type" מכיל URI שמזהה את הסוג. לדוגמה: { "id": 1234, "@type": "types.example.com/standard/id" }.

הכול

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

string

מזהה את הסוג של הודעת Protobuf שעברה סריאליזציה באמצעות הפניה ל-URI שכוללת קידומת שמסתיימת בקו נטוי ואת שם הסוג שמוגדר במלואו.

דוגמה: type.googleapis.com/google.protobuf.StringValue

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

התחילית היא שרירותית, ומצפים מהטמעות של Protobuf פשוט להסיר את כל מה שעד לתווים / האחרונים (כולל) כדי לזהות את הסוג. type.googleapis.com/ היא תחילית נפוצה שמוגדרת כברירת מחדל, שנדרשת בחלק מההטמעות מדור קודם. התחילית הזו לא מציינת את המקור של הסוג, ולא מצפים מכתובות URI שמכילות אותה להגיב לבקשות כלשהן.

כל המחרוזות של כתובות ה-URL של הסוג חייבות להיות הפניות חוקיות ל-URI, עם הגבלה נוספת (בפורמט הטקסט) שלפיה התוכן של ההפניה חייב לכלול רק תווים אלפאנומריים, תווים מוברחים עם קידוד אחוזים ותווים בערכה הבאה (לא כולל הגרשיים ההפוכים החיצוניים): /-.~_!$&()*+,;=. למרות שאנחנו מאפשרים קידודים באחוזים, ההטמעות לא צריכות לבטל את הקידוד שלהם כדי למנוע בלבול עם מנתחי נתונים קיימים. לדוגמה, בקשה עם הערך type.googleapis.com%2FFoo צריכה להידחות.

בתכנון המקורי של Any, נשקלה האפשרות להפעיל שירות לפתרון סוגים בכתובות ה-URL האלה, אבל ב-Protobuf מעולם לא בוצעה הטמעה של שירות כזה, והפנייה לכתובות ה-URL האלה נחשבת לבעייתית ועלולה לגרום לבעיות אבטחה. אל תנסו לפנות לכתובות URL של סוגים.
value

string (bytes format)

השדה מכיל סריאליזציה של Protobuf של הסוג שמתואר על ידי type_url.

מחרוזת בקידוד Base64.

רמת מהימנות

רמת המהימנות של הפתרון.

טיפוסים בני מנייה (enum)
CONFIDENCE_UNSPECIFIED ערך ברירת המחדל. הערך הזה לא בשימוש.
MEDIUM רמת מהימנות בינונית מציינת שהפתרון כנראה נכון, אבל יכול להיות שיש אפשרויות אחרות.
HIGH רמת ביטחון גבוהה מציינת שהרזולוציה נכונה ומייצגת ישות גיאוספציפית ספציפית (למשל, מקום ספציפי).

הערות על כלים

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