מזהי מקומות

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

מבוא

מזהה מקום הוא מזהה ייחודי של מקום במסד הנתונים של מקומות Google ובמפות 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 (חדש) וב-Places Library.
  • שימוש בפרמטרים של מזהה מקום ב-Maps Embed API.
  • שליפת שאילתות חיפוש בכתובות URL של מפות Google.
  • הצגת מגבלות מהירות ב-Roads API.
  • איך מוצאים מצולעים של גבולות ומגדירים להם סגנון בסגנון מבוסס-נתונים לגבולות.

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

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

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

סקירה כללית

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

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

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

אפשר להשתמש באותו מזהה מקום ב-Places API ובמספר ממשקי API של הפלטפורמה של מפות Google. לדוגמה, אפשר להשתמש באותו מזהה מקום כדי להפנות למקום ב-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. אם המקום לא נמצא, אובייקט המקום הוא nil.

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.

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

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