מזהי מקומות

בחירת פלטפורמה: Android iOS JavaScript Web Service
מפתחים באזור הכלכלי האירופי (EEA)

מבוא

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

  • אחזור כתובת של מזהה מקום ב-Geocoding API ובשירות המרת כתובות לקואורדינטות (geocoding),‏ Maps JavaScript API.
  • ציון נקודת מוצא, יעד ונקודות ציון ביניים ב-Routes API וב-Directions API (הגרסה הקודמת) ובשירות המסלולים, Maps JavaScript API (הגרסה הקודמת).
  • ציון מקורות ויעדים ב-Routes API וב-Distance Matrix API (גרסה קודמת) וב-Distance Matrix Service, ‏ Maps JavaScript API (גרסה קודמת).
  • אחזור פרטי מקום ב-Places API (חדש), ב-Places SDK ל-Android (חדש), ב-Places 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 Maps Platform. לדוגמה, אפשר להשתמש באותו מזהה מקום כדי להפנות למקום ב-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 מטרים מנקודה בסידני, אוסטרליה, שמכילים את המילה "cruise":

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 Maps Platform. לכן, אתם יכולים לאחסן ערכים של מזהי מקומות לשימוש מאוחר יותר.

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

מזהי מקומות עשויים להשתנות בגלל עדכונים במסד הנתונים של מפות 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.

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

INVALID_REQUEST

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

NOT_FOUND

קוד הסטטוס 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