Maps Tools Resolution API

‫Maps Tools Resolution API הוא חלק מ-Maps Grounding Lite. הוא מספק נקודות קצה (endpoints) באצווה שממירות שמות של מיקומים וכתובות URL של מפות Google למזהי מקומות במפות Google. אתם יכולים להשתמש במזהי המקומות שמוחזרים עם ממשקי API אחרים של Google Maps Platform. כל תשובה כוללת גם קישור ששומר את המקומות שזוהו כרשימה במפות Google.

‫Resolution API זמין גם כשיטות REST וגם ככלים בשרת MCP של Maps Grounding Lite:

פונקציה שיטת REST כלי MCP
זיהוי שמות או כתובות של מיקומים כמקומות resolveNames resolve_names
המרת כתובות URL של מפות Google למקומות resolveMapsUrls resolve_maps_urls

לפני שמתחילים

כדי להשתמש ב-Resolution API, אתם צריכים פרויקט בענן ב-Google Cloud עם חיוב מופעל ושירות ה-API של Maps Grounding Lite מופעל. הוראות להפעלה מופיעות במאמר הפעלת שירות Maps Grounding Lite בפרויקט ב-Google Cloud.

גישה ל-API ואימות

‫Resolution API תומך גם במפתח API וגם בפרטי כניסה של OAuth 2.0.

מפתח API

כדי לאמת בקשות, אתם יכולים להעביר מפתח API תקף של Google Maps Platform בכותרת X-Goog-Api-Key או לצרף אותו לכתובת ה-URL של הבקשה:

https://mapstools.googleapis.com/v1:resolveNames?key=API_KEY

בדוגמאות שבדף הזה, מחליפים את הערך API_KEY במפתח ה-API שלכם.

היקפי ההרשאות של OAuth 2.0

אם אתם משתמשים בהרשאת OAuth, היקף ההרשאות הבא נתמך:

  • https://www.googleapis.com/auth/maps-platform.mapstools

מכסות שימוש

מכסות ברירת המחדל הבאות חלות על Resolution API:

  • ‫ResolveNames: ‏600 שאילתות לדקה, לכל פרויקט.
  • ‫ResolveMapsUrls: ‏600 שאילתות לדקה, לכל פרויקט.
  • גודל אצווה: עד 20 שאילתות או כתובות URL לכל בקשה.

כל בקשה נספרת כשאילתה אחת, לא משנה כמה פריטים היא מכילה.

תמחור

בקשות אל ResolveNames ואל ResolveMapsUrls מחויבות בחינם (0$) במסגרת המק"ט Places API חיפוש טקסט Essentials (IDs Only). כמו בשאר התכונות של Maps Grounding Lite, לפרויקט צריך להיות חשבון לחיוב.

אימות בקשות ואילוצים

כדי למנוע עומס יתר ולהבטיח זמני תגובה מהירים, בקשות Batch עוברות אימות קפדני:

  • מגבלת גודל האצווה: שתי השיטות מאפשרות עד 20 פריטים לכל בקשה.
  • דרישות של ResolveNames:
    • כל פריט ב-queries חייב לציין פרמטר text לא ריק.
    • השאילתות צריכות לייצג שם או כתובת של מקום ספציפי (לדוגמה, "Googleplex, Mountain View, CA" או "Eiffel Tower, Paris").
    • חיפושים כלליים לפי קטגוריות (לדוגמה, "מסעדות בניו יורק") או שמות כלליים של רשתות בלי מיקום (לדוגמה, "סטארבקס") לא נתמכים, ויכול להיות שהם לא יניבו תוצאות.
  • דרישות לשימוש ב-ResolveMapsUrls:
    • כל כתובת URL צריכה להיות כתובת URL תקינה מבחינה מבנית של מפות Google.
    • הפורמטים הנתמכים כוללים:
      • כתובת ה-URL הרגילה של המקום: https://www.google.com/maps/place/...
      • כתובת URL מקוצרת: https://maps.app.goo.gl/...
    • אין תמיכה בכתובות URL כלליות של מפות Google שמבוססות על שאילתות (לדוגמה, https://maps.google.com/?q=restaurant) ובכתובות URL שלא מפנות למקום ייחודי אחד.

שמירת מקומות שזוהו במפות Google

אם לפחות פריט אחד באצווה נפתר, התשובה כוללת שדה saveToMapsUrl. זהו קישור יחיד למפות Google שמכיל את כל המקומות שזוהו בהצלחה בקבוצה. הציגו את הקישור הזה למשתמשים שרוצים לשמור, לשתף או לפתוח את המקומות שנמצאו כרשימה במפות Google.

תמיד צריך להשתמש בקישור שמוחזר על ידי ה-API. אל תיצרו את הקישור בעצמכם. אם אף אחד מהפריטים באצווה לא נפתר, התגובה לא כוללת את saveToMapsUrl.

טיפול בשגיאות חלקיות

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

איך לפרש את התשובה

  1. התאמה מובטחת של 1:1: הרשימה המוחזרת של results (עבור ResolveNames) או הרשימה של entities (עבור ResolveMapsUrls) ממפה 1:1 עם רשימת הקלט, לפי אינדקס.
  2. רכיבים ריקים במקרה של כשלים: אם הפריט באינדקס i לא נפתר, רשימת התוצאות מכילה אובייקט ריק {} באינדקס i.
  3. מפת failedRequests: התשובה מכילה מפת failedRequests.
    • המפתח הוא האינדקס מבוסס-האפס של הפריט שנכשל (מיוצג כמחרוזת ב-JSON).
    • הערך הוא אובייקט google.rpc.Status שמכיל את קוד השגיאה והודעה שמסבירה למה הפריט נכשל.
  4. ‫saveToMapsUrl covers only successes: הקישור saveToMapsUrl כולל רק את הפריטים שהבעיה שלהם נפתרה. פריטים שנכשלו לא נכללים.

אל תניחו שכל הקבוצה נכשלה בגלל שפריט אחד נכשל. תמיד כדאי לבדוק את failedRequests כדי לראות אילו פריטים, אם בכלל, לא נפתרו.

שגיאות בכל פריט

בטבלה הבאה מפורטות השגיאות ברמת הפריט שעשויות להופיע ב-failedRequests:

שיטה סיבה קוד שליחת הודעה
ResolveNames אי אפשר לזהות מקום לפי השם או הכתובת. ‫5 (NOT_FOUND) Place not found.
ResolveMapsUrls אי אפשר לפענח את כתובת ה-URL למקום. ‫3 (INVALID_ARGUMENT) Failed to resolve Maps URL to a place.
שתי השיטות הייתה שגיאה פנימית במהלך פתרון הבעיה. ‫13 (INTERNAL) Internal server error. Please retry. If the problem persists, please open a support case. https://goo.gle/maps-platform-support

מנסים שוב רק את הפריטים שנכשלו עם INTERNAL.

כשלים ברמה העליונה

ה-API מחזיר שגיאה ברמה העליונה במקום תגובה חלקית במקרים הבאים:

  • בקשה לא תקינה (400 INVALID_ARGUMENT): הבקשה מכילה יותר מ-20 פריטים, בקשת ResolveNames לא מכילה שאילתות או מכילה שאילתה עם ערך text ריק, או שבקשת ResolveMapsUrls מכילה כתובת URL ריקה או כתובת URL לא תקינה מבחינה תחבירית. אם יש פריט אחד לא תקין, כל הבקשה נכשלת.
  • שגיאות אימות, הרשאה או מכסה: לדוגמה, מפתח ה-API חסר או לא תקין, או שהבקשה חורגת ממגבלות השימוש.
  • שגיאות בחיבור לשרת (500 INTERNAL): מנסים שוב לשלוח את הבקשה.

שימוש ב-Resolution API עם MCP

שרת ה-MCP של Maps Grounding Lite בכתובת https://mapstools.googleapis.com/mcp חושף את Resolution API כשני כלים:

  • ‫resolve_names: ממירה קבוצה של שמות או כתובות של מיקומים למזהי מקומות.
  • ‫resolve_maps_urls: פותר קבוצה של כתובות URL במפות Google למזהי מקומות.

כשמגדירים את ה-LLM כך שישתמש בשרת Maps Grounding Lite MCP, הכלים האלה זמינים לצד הכלים האחרים של Maps Grounding Lite. הכלים מקבלים את אותם קלטים, אוכפים את אותן מגבלות ומחזירים את אותה תגובה של כישלון חלקי כמו ה-methods של REST.

התשובות של הכלי כוללות את השדה save_to_maps_url. תיאורי הכלים מנחים את ה-LLM להציג את הקישור הזה כשהמשתמש רוצה לשמור, לשתף או לפתוח את המקומות שנמצאו כרשימה במפות Google, במקום ליצור קישור בעצמו.

בדוגמה הבאה משתמשים ב-curl כדי להפעיל את הכלי resolve_names ישירות:

curl --location 'https://mapstools.googleapis.com/mcp' \
--header 'content-type: application/json' \
--header 'accept: application/json, text/event-stream' \
--header 'X-Goog-Api-Key: API_KEY' \
--data '{
  "method": "tools/call",
  "params": {
    "name": "resolve_names",
    "arguments": {
      "queries": [
        { "text": "Googleplex, Mountain View, CA" },
        { "text": "Eiffel Tower, Paris" }
      ]
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

כדי להפעיל את resolve_maps_urls, צריך להגדיר את name ל-resolve_maps_urls ולהעביר מערך urls ב-arguments.

מפרט של API בארכיטקטורת REST ודוגמאות ל-curl

ResolveNames

Method: POST

https://mapstools.googleapis.com/v1:resolveNames

פורמט גוף הבקשה

{
  "queries": [
    { "text": "string" }
  ],
  "locationBias": {
    "viewport": {
      "low": { "latitude": number, "longitude": number },
      "high": { "latitude": number, "longitude": number }
    }
  },
  "regionCode": "string"
}
  • ‫queries (חובה): רשימה חוזרת של שאילתות לפתרון (עד 20).
  • locationBias (אופציונלי): תיבה תוחמת של אזור התצוגה כדי להטות את התוצאות לאזור מקומי.
  • ‫regionCode (אופציונלי): קוד מדינה של CLDR (לדוגמה, "US" או "FR") כדי להטות את התוצאות.

דוגמה ל-Curl: פתרון מוצלח

השאילתה הזו פותרת את "Googleplex" ו "מגדל אייפל".

curl -X POST \
-H "Content-Type: application/json" \
-d '{
  "queries": [
    { "text": "Googleplex, Mountain View, CA" },
    { "text": "Eiffel Tower, Paris" }
  ]
}' \
"https://mapstools.googleapis.com/v1:resolveNames?key=API_KEY"
תגובת JSON
{
  "results": [
    {
      "entity": {
        "place": "places/ChIJj61dQgK6j4AR4GeTYWZsKWw"
      },
      "confidence": "HIGH"
    },
    {
      "entity": {
        "place": "places/ChIJLU7jZClu5kcR4PcOOO6p3I0"
      },
      "confidence": "HIGH"
    }
  ],
  "saveToMapsUrl": "https://www.google.com/maps/@?api=1&map_action=shortlist&place_ids=ChIJj61dQgK6j4AR4GeTYWZsKWw,ChIJLU7jZClu5kcR4PcOOO6p3I0"
}

דוגמה ל-Curl: תוצאות מעורבות (כשל חלקי)

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

curl -X POST \
-H "Content-Type: application/json" \
-d '{
  "queries": [
    { "text": "This is not a real place name at all 123456789" },
    { "text": "Eiffel Tower, Paris" }
  ]
}' \
"https://mapstools.googleapis.com/v1:resolveNames?key=API_KEY"
תגובת JSON
{
  "results": [
    {},
    {
      "entity": {
        "place": "places/ChIJLU7jZClu5kcR4PcOOO6p3I0"
      },
      "confidence": "HIGH"
    }
  ],
  "failedRequests": {
    "0": {
      "code": 5,
      "message": "Place not found."
    }
  },
  "saveToMapsUrl": "https://www.google.com/maps/@?api=1&map_action=shortlist&place_ids=ChIJLU7jZClu5kcR4PcOOO6p3I0"
}

ResolveMapsUrls

Method: POST

https://mapstools.googleapis.com/v1:resolveMapsUrls

פורמט גוף הבקשה

{
  "urls": [
    "string"
  ]
}
  • ‫urls (חובה): רשימה חוזרת של מחרוזות של כתובות URL במפות Google שצריך לפתור (עד 20).

דוגמה ל-Curl: פתרון מוצלח

בדוגמה הבאה מתבצעת פתירה של כתובת URL רגילה של מקום במפות Google:

curl -X POST \
-H "Content-Type: application/json" \
-d '{
"urls": [
"https://www.google.com/maps/place/Googleplex/@37.4220041,-122.0862515,17z/data=!3m1!4b1!4m6!3m5!1s0x808fba02425dad8f:0x6c296c66619367e0!8m2!3d37.4219998!4d-122.0840575!16s%2Fg%2F11c8b0ssp6"
]
}' \
"https://mapstools.googleapis.com/v1:resolveMapsUrls?key=API_KEY"
תגובת JSON
{
  "entities": [
    {
      "place": "places/ChIJj61dQgK6j4AR4GeTYWZsKWw"
    }
  ],
  "saveToMapsUrl": "https://www.google.com/maps/@?api=1&map_action=shortlist&place_ids=ChIJj61dQgK6j4AR4GeTYWZsKWw"
}

דוגמה ל-Curl: תוצאות מעורבות (כשל חלקי)

בדוגמה הבאה, כתובת URL אחת של מקום תקינה, וכתובת URL אחת לא תקינה:

curl -X POST \
-H "Content-Type: application/json" \
-d '{
  "urls": [
    "https://www.google.com/maps/place/Googleplex/@37.4220041,-122.0862515,17z/data=!3m1!4b1!4m6!3m5!1s0x808fba02425dad8f:0x6c296c66619367e0!8m2!3d37.4219998!4d-122.0840575!16s%2Fg%2F11c8b0ssp6",
    "https://www.google.com/not-a-place"
  ]
}' \
"https://mapstools.googleapis.com/v1:resolveMapsUrls?key=API_KEY"
תגובת JSON
{
  "entities": [
    {
      "place": "places/ChIJj61dQgK6j4AR4GeTYWZsKWw"
    },
    {}
  ],
  "failedRequests": {
    "1": {
      "code": 3,
      "message": "Failed to resolve Maps URL to a place."
    }
  },
  "saveToMapsUrl": "https://www.google.com/maps/@?api=1&map_action=shortlist&place_ids=ChIJj61dQgK6j4AR4GeTYWZsKWw"
}

דוגמה ל-Curl: כשל באימות

בדוגמה הבאה מועברות יותר מ-20 כתובות URL בבקשה אחת:

python3 -c 'import json; print(json.dumps({"urls": ["https://www.google.com/maps/place/Googleplex"] * 21}))' | \
curl -X POST \
-H "Content-Type: application/json" \
-d @- \
"https://mapstools.googleapis.com/v1:resolveMapsUrls?key=API_KEY"
תגובת JSON
{
  "error": {
    "code": 400,
    "message": "Request contains more than 20 URLs.",
    "status": "INVALID_ARGUMENT"
  }
}

שליחת משוב

כדי לדווח על בעיה או לשלוח משוב על Resolution API, אתם יכולים להשתמש ברכיב הציבורי של Issue Tracker ב-Maps Grounding Lite: