מזהי מקומות

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

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

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

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

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

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

סקירה כללית

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

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

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

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

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

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

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

דוגמה באמצעות ה-API של 'מקומות'

כדי למצוא מזהה מקום, אפשר לשלוח בקשת חיפוש מקום באמצעות ה-API של מקומות Google.

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

למשל: 

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

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