Maps Tools Resolution API (ניסיוני)

Maps Tools Resolution API מספק נקודות קצה לעיבוד ברצף (batch processing) כדי לפתור שמות של מיקומים וכתובות URL למזהי מקומות במפות Google.

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

שיטות אימות

ממשקי ה-API תומכים בפרטי כניסה של מפתח API ושל OAuth 2.0:

1. מפתח API

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

https://mapstools.googleapis.com/v1alpha:resolveNames?key=YOUR_API_KEY

2. היקפי הרשאות OAuth 2.0

אם משתמשים בהרשאת OAuth, אפשר להשתמש בהיקפי ההרשאות הבאים:

  • https://www.googleapis.com/auth/maps-platform.mapstools (מומלץ)

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

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

  • מגבלת גודל האצווה: בשני ממשקי ה-API אפשר לשלוח עד 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 כלליות של מפות שמבוססות על שאילתות (למשל, https://maps.google.com/?q=restaurant) ובכתובות URL שלא מפנות למקום ייחודי יחיד.

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

שני ממשקי ה-API האלה מיועדים לעיבוד פעולות מקובצות. אם חלק מהפריטים באצווה לא נפתרים, הבקשה הכוללת לא נכשלת עם שגיאה ברמה העליונה. במקום זאת, ה-API מחזיר תגובה מסוג Partial Success (הצלחה חלקית).

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

  1. התאמה של 1:1: התוצאות שמוחזרות (עבור ResolveNames) או רשימות הישויות (עבור ResolveMapsUrls) ממופות 1:1 עם רשימת הקלט.
  2. רכיבים ריקים במקרה של כשלים: אם פריט באינדקס i לא נפתר, רשימת התוצאות תכיל אובייקט ריק {} באינדקס i.
  3. ‫failedRequests Map: התשובה מכילה מפה של failedRequests.
    • המפתח הוא האינדקס מבוסס-0 של הפריט שנכשל (מיוצג כמחרוזת ב-JSON).
    • הערך value הוא אובייקט google.rpc.Status שמכיל את קוד השגיאה הספציפי (מסטטוסים רגילים של gRPC/HTTP) והודעה מפורטת שמסבירה למה הפעולה נכשלה.

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

שגיאת HTTP ברמה העליונה (למשל, 400 Bad Request) מוחזרת רק אם בקשת האימות נכשלת (למשל, כשמעבירים יותר מ-20 פריטים או כשחסרים שדות חובה).

מפרט API ודוגמאות ל-Curl

1. ResolveNames API

שיטה: POST

https://mapstools.googleapis.com/v1alpha: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/v1alpha:resolveNames?key=KEY"
תגובת JSON
{
  "results": [
    {
      "entity": {
        "place": "places/ChIJj61dQgK6j4AR4GeTYWZsKWw"
      },
      "confidence": "HIGH"
    },
    {
      "entity": {
        "place": "places/ChIJLU7jZClu5kcR4PcOOO6p3I0"
      },
      "confidence": "HIGH"
    }
  ]
}

דוגמה ל-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/v1alpha:resolveNames?key=KEY"
תגובת JSON
{
  "results": [
    {},
    {
      "entity": {
        "place": "places/ChIJLU7jZClu5kcR4PcOOO6p3I0"
      },
      "confidence": "HIGH"
    }
  ],
  "failedRequests": {
    "0": {
      "code": 5,
      "message": "Place not found."
    }
  }
}

2. ResolveMapsUrls API

שיטה: POST

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

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

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

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

פתרון של קישור רגיל למקום במפות 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!1s0x808fba024255ad8f:0x6ca26666619367e0!8m2!3d37.4219998!4d-122.0840575!16s%2Fg%2F11c8b0ssp6"
]
}' \
"https://mapstools.googleapis.com/v1alpha:resolveMapsUrls?key=KEY"
תגובת JSON
{
  "entities": [
    {
      "place": "places/ChIJj61VQgK6j4AR4GeTYWZmomw"
    }
  ]
}

דוגמה ל-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!1s0x808fba024255ad8f:0x6ca26666619367e0!8m2!3d37.4219998!4d-122.0840575!16s%2Fg%2F11c8b0ssp6",
    "https://www.google.com/not-a-place"
  ]
}' \
"https://mapstools.googleapis.com/v1alpha:resolveMapsUrls?key=KEY"
תגובת JSON
{
  "entities": [
    {
      "place": "places/ChIJj61VQgK6j4AR4GeTYWZmomw"
    },
    {}
  ],
  "failedRequests": {
    "1": {
      "code": 3,
      "message": "Invalid URL."
    }
  }
}

דוגמה ל-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/v1alpha:resolveMapsUrls?key=KEY"
תגובת JSON
{
  "error": {
    "code": 400,
    "message": "Request contains more than 20 URLs.",
    "status": "INVALID_ARGUMENT"
  }
}