Maps Tools Resolution API

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

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

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

כדי להשתמש ב-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:

מנסים שוב רק את הפריטים שנכשלו עם 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 כך שישתמש בשרת MCP של Maps Grounding Lite, הכלים האלה זמינים לצד הכלים האחרים של Maps Grounding Lite. הכלים מקבלים את אותם קלטים, אוכפים את אותן מגבלות ומחזירים את אותה תגובה של כישלון חלקי כמו השיטות של 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

שיטה: POST

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

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

{
  "urls": [
    "string"
  ]
}

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

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

בדוגמה הבאה, כתובת URL רגילה של מקום במפות Google מומרת לכתובת 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://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:

• דיווח על באג
• הגשת בקשה להוספת תכונה
• שליחת משוב