מזהי מקומות

בחירת פלטפורמה: 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), ואז להשתמש במזהה המקום שהוחזר כדי לאחזר את פרטי המקום. אפשר לשמור את מזהה המקום ולהשתמש בו כדי לאחזר את אותם פרטי המקום מאוחר יותר. בהמשך מוסבר איך לשמור מזהי מקומות.

דוגמה לשימוש ב-Places SDK ל-iOS

מזהה מקום הוא מזהה טקסט שמזהה מקום באופן ייחודי. ב-Places SDK ל-iOS, אפשר לאחזר את המזהה של מקום מאובייקט GMSPlace. אפשר לשמור את מזהה המקום ולהשתמש בו כדי לאחזר את האובייקט GMSPlace שוב מאוחר יותר.

כדי לקבל מקום לפי מזהה, צריך להפעיל את הפונקציה GMSPlacesClient fetchPlaceFromPlaceID: ולהעביר את הפרמטרים הבאים:

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

ה-API מפעיל את שיטת הקריאה החוזרת שצוינה, ומעביר אובייקט GMSPlace. אם המקום לא נמצא, אובייקט המקום יהיה null.

Places Swift SDK ל-iOS

// Initialize Places Swift Client.
let placesClient = PlacesClient.shared

// A hotel in Saigon with an attribution
let placeID = "ChIJV4k8_9UodTERU5KXbkYpSYs"
    
// Fetch Place Request.
let fetchPlaceRequest = FetchPlaceRequest(
  placeID: placeID,
  placeProperties: [.displayName]
)
    
Task {
  switch await placesClient.fetchPlace(with: fetchPlaceRequest) {
  case .success(let place):
    print("The selected place is: \(place.displayName): \(String(describing: place.description))")
  case .failure(let placesError):
    print("Place not found: \(placeID); \(placesError)")
  }
}

Swift

// A hotel in Saigon with an attribution.
let placeID = "ChIJV4k8_9UodTERU5KXbkYpSYs"

// Specify the place data types to return.
let fields: GMSPlaceField = GMSPlaceField(rawValue: UInt(GMSPlaceField.name.rawValue) |
  UInt(GMSPlaceField.placeID.rawValue))!

placesClient?.fetchPlace(fromPlaceID: placeID, placeFields: fields, sessionToken: nil, callback: {
  (place: GMSPlace?, error: Error?) in
  if let error = error {
    print("An error occurred: \(error.localizedDescription)")
    return
  }
  if let place = place {
    self.lblName?.text = place.name
    print("The selected place is: \(place.name)")
  }
})

Objective-C

// A hotel in Saigon with an attribution.
NSString *placeID = @"ChIJV4k8_9UodTERU5KXbkYpSYs";

// Specify the place data types to return.
GMSPlaceField fields = (GMSPlaceFieldName | GMSPlaceFieldPlaceID);

[_placesClient fetchPlaceFromPlaceID:placeID placeFields:fields sessionToken:nil callback:^(GMSPlace * _Nullable place, NSError * _Nullable error) {
  if (error != nil) {
    NSLog(@"An error occurred %@", [error localizedDescription]);
    return;
  }
  if (place != nil) {
    NSLog(@"The selected place is: %@", [place name]);
  }
}];

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

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

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

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

הקריאה הזו מפעילה את המק"ט Places Details - ID Refresh.

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

INVALID_REQUEST

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

NOT_FOUND

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

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

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

לפעמים, סוגים מסוימים של מזהי מיקומים עלולים לגרום לתגובה 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