מזהי מקומות

בחירת פלטפורמה: Android iOS JavaScript שירות אינטרנט

המזהה הייחודי של מקום במסד הנתונים של כתובות ב-Google ובמפות Google. מזהי מקומות יתקבלו בבקשות לממשקי ה-API הבאים של מפות Google:

  • אחזור כתובת למזהה מקום בשירות האינטרנט Geocoding API וב-Geocoding API, Maps JavaScript API.
  • ציון ציוני דרך, נקודות יעד וציוני דרך ב-Routes API ובשירות האינטרנט Directions API וב-Directions API, Maps JavaScript API.
  • ציון מקורות ויעדים ב-Routes API ובשירות האינטרנט Distance Matrix API ו-Distance Matrix Service, Maps JavaScript API.
  • אחזור פרטי מקום בשירות האינטרנט של Places API, SDK של מקומות ל-Android, SDK של מקומות ל-iOS וספריית מקומות.
  • שימוש בפרמטרים של מזהה מקום ב-Maps Embed API.
  • אחזור שאילתות חיפוש בכתובות URL של מפות Google.
  • הצגת מגבלות מהירות ב-Roads API.
  • איתור ועיצוב של פוליגונים של גבולות בסגנון מבוסס-נתונים לצורך קביעת גבולות.

איך למצוא את המזהה של מקום ספציפי

רוצה למצוא את מזהה המקום של מקום ספציפי? אפשר להשתמש בכלי לאיתור מזהי מקומות שבהמשך כדי לחפש מקום ולקבל את המזהה שלו:

אפשר גם לראות את הכלי לאיתור מזהי מקומות לפי הקוד שלו במסמכי התיעוד של Maps JavaScript API.

סקירה

מזהה מקום הוא מזהה טקסטואלי שמזהה מקום באופן ייחודי. האורך של המזהה עשוי להשתנות (אין אורך מקסימלי למזהי מקומות). דוגמאות:

  • ChIJgUbEo8cfqokR5lP9_Wh_DaM
  • GhIJQWDl0CIeQUARxks3icF8U8A
  • EicxMyBNYXJrZXQgU3QsIFdpbG1pbmd0b24sIE5DIDI4NDAxLCBVU0EiGhIYChQKEgnRTo6ixx-qiRHo_bbmkCm7ZRAN
  • EicxMyBNYXJrZXQgU3QsIFdpbG1pbmd0b24sIE5DIDI4NDAxLCBVU0E
  • IhoSGAoUChIJ0U6OoscfqokR6P225pApu2UQDQ

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

אפשר להשתמש באותו מזהה מקום ב-Places API ובמספר ממשקי API של הפלטפורמה של מפות Google. לדוגמה, אפשר להשתמש באותו מזהה מקום כדי לציין מקום ב-Places API, ב-Maps JavaScript API, ב-Geocoding API, ב-Maps Embed API וב-Roads API.

אחזור פרטי מקום באמצעות מזהה המקום

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

הדוגמאות הבאות מראות איך לבקש כתובת URL של סמל עבור Places API (חדש) ו-Places API.

Places API (חדש)

בעזרת Places API אפשר למצוא מזהה מקום באמצעות בקשה של חיפוש טקסט (חדש).

curl -X POST -d '{
  "textQuery" : "Spicy Vegetarian Food in Sydney, Australia"
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.id,places.displayName,places.formattedAddress' \
'https://places.googleapis.com/v1/places:searchText'

התגובה כוללת מזהה מקום בשדה id, כפי שמוצג בהמשך:

{
  "places": [
    {
      "id": "ChIJs5ydyTiuEmsR0fRSlU0C7k0",
      "formattedAddress": "29 King St, Sydney NSW 2000, Australia",
      "displayName": {
        "text": "Peace Harmony",
        "languageCode": "en"
      }
    },
  ...
}

עכשיו אפשר לשלוח בקשה לפרטי מקום (חדש) על-ידי הכללת מזהה המקום בכתובת ה-URL של הבקשה:

https://places.googleapis.com/v1/places/ChIJs5ydyTiuEmsR0fRSlU0C7k0?fields=id,displayName&key=API_KEY

Places API

בעזרת Places API אפשר למצוא מזהה מקום באמצעות בקשת חיפוש מקום.

הדוגמה הבאה היא בקשת חיפוש למקומות מסוג 'מסעדה' ברדיוס של 1,500 מטר מנקודה בסידני, אוסטרליה, עם המילה 'שייט':

https://maps.googleapis.com/maps/api/place/nearbysearch/json?location=-33.8670522,151.1957362&radius=1500&type=restaurant&keyword=cruise&key=YOUR_API_KEY

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

{
  "html_attributions" : [],
  "results" : [
    {
      "geometry" : {
        "location" : {
          "lat" : -33.870775,
          "lng" : 151.199025
        }
      },
      ...
      "place_id" : "ChIJrTLr-GyuEmsRBfy61i59si0",
      ...
    }
  ],
  "status" : "OK"
}

עכשיו אפשר לשלוח בקשה של פרטי מקום ולהוסיף את מזהה המקום בפרמטר place_id:

https://maps.googleapis.com/maps/api/place/details/json?place_id=ChIJrTLr-GyuEmsRBfy61i59si0&key=YOUR_API_KEY

שמירת מזהי מקומות לשימוש במועד מאוחר יותר

מזהי מקומות פטורים מהגבלות השמירה במטמון המפורטות בסעיף 3.2.3(ב) בתנאים ובהגבלות של הפלטפורמה של מפות Google. לכן אפשר לשמור ערכים של מזהה מקום לשימוש במועד מאוחר יותר.

רענון של מזהי מקומות שמורים

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

Places API (חדש)

לדוגמה, שימוש בפרטי מקום (חדש):

https://places.googleapis.com/v1/places/ChIJ05IRjKHxEQ0RJLV_5NLdK2w?fields=id&key=API_KEY

Places API

לדוגמה, באמצעות ה-API הקודם של Place Details: 

https://maps.googleapis.com/maps/api/place/details/json?place_id=ChIJ05IRjKHxEQ0RJLV_5NLdK2w&fields=place_id&key=API_KEY

הקריאה הזו מפעילה את המק"ט Place Detailed New (IDs בלבד) או Places Details - ID Refresh.

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

קודי שגיאה לשימוש במזהי מקומות

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

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

באופן ספציפי, סוגים מסוימים של מזהי מקומות עשויים לגרום לפעמים לתשובה NOT_FOUND, או שה-API עשוי להחזיר מזהה מקום אחר בתשובה. דוגמאות למזהי מקומות:

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

בדרך כלל המזהים האלה מוצגים כמחרוזת ארוכה (אין אורך מקסימלי למזהי מקומות). למשל:

EpID4LC14LC_4LCo4LCv4LGN4LCo4LCX4LCw4LGNIC0g4LC44LGI4LCm4LGN4LCs4LC-4LCm4LGNIOCwsOCxi-CwoeCxjeCwoeCxgSAmIOCwteCwv-CwqOCwr-CxjSDgsKjgsJfgsLDgsY0g4LCu4LGG4LCv4LC_4LCo4LGNIOCwsOCxi-CwoeCxjeCwoeCxgSwg4LC14LC_4LCo4LCv4LGNIOCwqOCwl-CwsOCxjSDgsJXgsL7gsLLgsKjgsYAsIOCwsuCwleCxjeCwt-CxjeCwruCwv-CwqOCwl-CwsOCxjSDgsJXgsL7gsLLgsKjgsYAsIOCwuOCwsOCxguCwsOCxjSDgsKjgsJfgsLDgsY0g4LC14LGG4LC44LGN4LCf4LGNLCDgsLjgsK_gsYDgsKbgsL7gsKzgsL7gsKbgsY0sIOCwueCxiOCwpuCwsOCwvuCwrOCwvuCwpuCxjSwg4LCk4LGG4LCy4LCC4LCX4LC-4LCjIDUwMDA1OSwg4LCt4LC-4LCw4LCk4LCm4LGH4LC24LCCImYiZAoUChIJ31l5uGWYyzsR9zY2qk9lDiASFAoSCd9ZebhlmMs7Efc2NqpPZQ4gGhQKEglDz61OZpjLOxHgDJCFY-o1qBoUChIJi37TW2-YyzsRr_uv50r7tdEiCg1MwFcKFS_dyy4