מזהי מקומות

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

מבוא

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

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

דוגמה לשימוש בספריית המקומות ב-Maps JavaScript API

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

var map;

function initialize() {
  // Create a map centered in Pyrmont, Sydney (Australia).
  map = new google.maps.Map(document.getElementById('map'), {
    center: {lat: -33.8666, lng: 151.1958},
    zoom: 15
  });

  // Search for Google's office in Australia.
  var request = {
    location: map.getCenter(),
    radius: '500',
    query: 'Google Sydney'
  };

  var service = new google.maps.places.PlacesService(map);
  service.textSearch(request, callback);
}

// Checks that the PlacesServiceStatus is OK, and adds a marker
// using the place ID and location from the PlacesService.
function callback(results, status) {
  if (status == google.maps.places.PlacesServiceStatus.OK) {
    var marker = new google.maps.Marker({
      map: map,
      place: {
        placeId: results[0].place_id,
        location: results[0].geometry.location
      }
    });
  }
}

google.maps.event.addDomListener(window, 'load', initialize);

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

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

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

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

הקריאה הזו מפעילה את המק"ט 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