מזהי מקומות

בחירת פלטפורמה: Android iOS JavaScript Web Service

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

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

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

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

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

סקירה כללית

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

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

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

אפשר להשתמש באותו מזהה מקום ב-Places API ובמספר ממשקי Google Maps Platform API. לדוגמה, אפשר להשתמש באותו מזהה מקום כדי להפנות למקום ב-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 באמצעות שליחת בקשה מסוג Text Search (New).

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 (קודם)

אפשר למצוא מזהה מקום באמצעות 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. לכן אפשר לשמור ערכים של מזהי מקומות לשימוש מאוחר יותר.

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

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

Places API (חדש)

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

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

Places API (קודם)

לדוגמה, באמצעות Places API (קודם):

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

הקריאה הזו מפעילה את המק"ט Place Detail New Essentials IDs Only או את המק"ט 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