Places SDK ל-iOS מספק לאפליקציה שלך מידע עשיר על מקומות, כולל השם והכתובת של המקום, המיקום הגיאוגרפי המצוין כקואורדינטות של קווי אורך ורוחב, סוג המקום (כמו מועדון לילה, חנות לחיות מחמד, מוזיאון) ועוד. כדי לגשת למידע הזה לגבי מקום ספציפי, תוכלו להשתמש במזהה המקום – מזהה קבוע שמזהה מקום באופן ייחודי.
פרטי המקום
הכיתה
GMSPlace
מספקת מידע על מקום ספציפי. ניתן לתפוס אובייקט
GMSPlace
בדרכים הבאות:
- התקשרות אל
GMSPlacesClient findPlaceLikelihoodsFromUserLocationWithPlaceFields:
. מומלץ לעיין במדריך לבדיקת המקום הנוכחי. - מתקשרים אל
GMSPlacesClient fetchPlaceFromPlaceID:
ומעבירים את המספרGMSPlaceField
, מזהה מקום ושיטת קריאה חוזרת. בבקשות של פרטי מקום, אם לא תציינו לפחות שדה אחד בבקשה, או אם תשמיטו את הפרמטרfields
מהבקשה, כל השדות האפשריים יוחזרו והחיוב יתבצע בהתאם. אפשר לעיין במדריך לקבלת מקום לפי מזהה.
כשמבקשים מקום, צריך לציין אילו סוגים של נתוני מקום
ברצונך להחזיר. כדי לעשות את זה, אפשר לקבוע ערך בשדה GMSPlaceField
, ולציין את סוגי הנתונים שיוחזרו. זהו שיקול חשוב, מאחר שהוא ישפיע על
העלות של כל בקשה.
מאחר שהתוצאות של נתוני המקומות לא יכולות להיות ריקות, מוחזרות רק
תוצאות של מקומות עם נתונים (לדוגמה, אם למקום המבוקש אין
תמונות, השדה photos
לא יופיע בתוצאה).
הדוגמה הבאה מעבירה רשימה של שני ערכי שדות כדי לציין את הנתונים שהוחזרו על ידי הבקשה:
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))
Objective-C
// A hotel in Saigon with an attribution. NSString *placeID = @"ChIJV4k8_9UodTERU5KXbkYpSYs"; // Specify the place data types to return. GMSPlaceField fields = (GMSPlaceFieldName | GMSPlaceFieldPlaceID);
למידע נוסף על שדות של מקומות למידע נוסף על אופן החיוב של בקשות לנתוני מקום, ראו שימוש וחיוב.
הסיווג
GMSPlace
עשוי להכיל את נתוני המקום הבאים:
name
– שם המקום.editorialSummary
– תיאור פשוט של מקום.placeID
– המזהה הטקסטי של המקום. אפשר לקרוא עוד על מזהי מקומות בהמשך הדף.coordinate
– המיקום הגיאוגרפי של המקום, המצוין כקואורדינטות של קווי אורך ורוחב.phoneNumber
– מספר הטלפון של המקום, בפורמט בינלאומי.formattedAddress
– הכתובת של המיקום הזה בפורמט שקריא לבני אדם.לעיתים קרובות, כתובת זו זהה לכתובת למשלוח דואר. לתשומת ליבך: בחלק מהמדינות, כמו בריטניה, אסור להפיץ כתובות למשלוח דואר אמיתיות בגלל הגבלות רישוי.
הכתובת בפורמט הנכון מורכבת באופן לוגי מרכיב כתובת אחד או יותר. לדוגמה, הכתובת " 111 8th Avenue, New York, NY" מורכבת מהרכיבים הבאים: "111" (מספר הרחוב), "8th Avenue" (המסלול), "New York" (העיר) ו-"NY" (מדינת ארה"ב).
אל תנתחו את הכתובת בפורמט פרוגרמטי. במקום זאת, צריך להשתמש ברכיבי הכתובת הנפרדים, שכוללים את תגובת ה-API בנוסף לשדה הכתובת המעוצב.
openingHours
– שעות הפתיחה של המקום (כפי שמיוצג על ידיGMSOpeningHours
). מתקשרים אלGMSOpeningHours.weekdayText
כדי לקבל רשימה של מחרוזות מקומיות של שעות הפתיחה היומיות במהלך השבוע. אפשר להפעיל אתGMSOpeningHours.Periods
כדי להחזיר רשימה של פריטים מסוגGMSPeriod
עם מידע מפורט יותר, המקביל לנתונים שסופקו על ידיweekdayText
. הערה: אם מקום כלשהו פתוח תמיד, התקופה מיוצגת ביום ראשון בחצות, וה-closeEvent
הוא null.currentOpeningHours
ו-secondaryOpeningHours
– שדות שחלים עליהם חגים ושינויים זמניים בלוח הזמנים שלהם.addressComponents
– מערך שלGMSAddressComponent
אובייקטים שמייצגים את רכיבי הכתובת של מקום. הרכיבים האלה מסופקים כדי לחלץ מידע מובנה על כתובת של מקום, לדוגמה כדי למצוא את העיר שבה המקום נמצא. אל תשתמשו ברכיבים האלה לעיצוב כתובות. במקום זאת, השתמשו במאפייןformattedAddress
שמספק כתובת בפורמט מותאם לשוק המקומי.שימו לב לעובדות הבאות לגבי המערך
addressComponents
:- מערך רכיבי הכתובת עשוי להכיל יותר רכיבים מאשר ה-
formattedAddress
. - המערך לא כולל בהכרח את כל הישויות הפוליטיות
שמכילות כתובת, פרט לאלה שכלולות
ב-
formattedAddress
. - לא בטוח שהפורמט של התשובה יישאר זהה בין
הבקשות. באופן ספציפי, מספר
addressComponents
משתנה בהתאם לכתובת המבוקשת, והוא עשוי להשתנות עם הזמן לגבי אותה כתובת. מיקום של רכיב יכול לשנות את מיקומו במערך. סוג הרכיב יכול להשתנות. ייתכן שחסר רכיב מסוים בתגובה מאוחרת יותר.
- מערך רכיבי הכתובת עשוי להכיל יותר רכיבים מאשר ה-
userRatingsTotal
– כמה ביקורות נכללים בדירוג של המקום.
המחלקה
GMSPlace
מכילה את הפונקציות הבאות לחברים:
-
isOpen
מחשב אם מקום מסוים פתוח בשעה מסוימת, על סמךopeningHours
ו-UTCOffsetMinutes
, ועל סמך התאריך והשעה הנוכחיים. isOpenAtDate
מחשבת אם מקום מסוים פתוח בתאריך מסוים, על סמךopeningHours
ו-UTCOffsetMinutes
, ועל סמך התאריך והשעה הנוכחיים.
כשמשתמשים בפונקציות האלה כדי לקבל זמני פתיחה ו/או תאריכים, הבקשה המקורית מסוג fetchPlaceFromPlaceID:
או findPlaceLikelihoodsFromUserLocationWithPlaceFields:
צריכה לכלול את השדות GMSPlaceFieldOpeningHours
וגם GMSPlaceFieldUTCOffsetMinutes
. אם אחד מהשדות האלה חסר, האובייקט GMSPlace
שמתקבל לא יכלול זמני פתיחה או תאריכים, והקריאה תחזיר את הערך GMSPlaceOpenStatusUnknown
. כדי לקבל תוצאות מדויקות, צריך לבקש
את השדות GMSPlaceFieldBusinessStatus
ו-GMSPlaceFieldUTCOffsetMinutes
בבקשת המקום המקורית. אם לא התבקשת לעשות זאת, ההנחה היא שהעסק פועל.
isOpen
עם פרטי המקום.
ליהנות משעות פתיחה יוצאות מן הכלל
שעות הפתיחה הרגילות מתקבלות דרךopeningHours
, currentOpeningHours
ו-secondaryOpeningHours
תומכים בשינויים זמניים בלוח הזמנים בחגים.
ניתן לסנן ולהציג שעות פתיחה חריגות בימים מיוחדים אלה, אם הן זמינות.
Swift
func examineOpeningHours(place: GMSPlace) { // Check if the current opening hours contains a special day that has exceptional hours guard let currentOpeningHours = place.currentOpeningHours else { return } if let specialDays = currentOpeningHours.specialDays { guard !specialDays.isEmpty else { return } if let specialDay = specialDays.filter { $0.isExceptional }.first { // Indicate exceptional hours } } // Check if current opening hours contains a truncated time period let periods = currentOpeningHours.periods if !periods.isEmpty { for period in periods { let open = period.open let close = period.close if let open = open { let date = open.date if open.isTruncated { // Indicate truncated time period } } } } // Check if the place's secondary opening hours indicate when delivery is available let secondaryOpeningHours = place.secondaryOpeningHours guard let hoursType = secondaryOpeningHours.first?.hoursType else { return } if (hoursType == GMSPlaceHoursTypeDelivery) { // Indicate hours where delivery is available } }
Objective-C
- (void)examineOpeningHours:(GMSPlace *) place { // Check if the current opening hours contains a special day that has exceptional hours GMSOpeningHours *currentOpeningHours = place.currentOpeningHours; if (currentOpeningHours != nil) { NSArray<GMSPlaceSpecialDay *> *specialDays = currentOpeningHours.specialDays; if ([specialDays count] != 0) { for (GMSPlaceSpecialDay *specialDay in specialDays) { NSDate *date = specialDay.date; if ([specialDay isExceptional]) { // Indicate exceptional hours } } } } // Check if current opening hours contains a truncated time period NSArray <GMSPeriod *> * periods = currentOpeningHours.periods; if ([periods count] != 0) { for (GMSPeriod * period in periods) { GMSTimeOfWeek *open = period.open; GMSTimeOfWeek *close = period.close; if (open) { if ([open isTruncated]) { // Indicate truncated time period } } } } // Check if the place's secondary opening hours indicate when delivery is available GMSOpeningHours *secondaryOpeningHours = place.secondaryOpeningHours; GMSPlaceHoursType hoursType = secondaryOpeningHours.getHoursType; if (hoursType == GMSPlaceHoursTypeDelivery) { // Indicate hours where delivery is available } }
קבלת מקום לפי מזהה
מזהה מקום הוא מזהה טקסט שמזהה מקום באופן ייחודי. ב-Place SDK ל-iOS, אפשר לאחזר את המזהה של מקום מאובייקט GMSPlace
. אפשר לאחסן את מזהה המקום ולהשתמש בו כדי לאחזר שוב את האובייקט GMSPlace
מאוחר יותר.
כדי לקבל מקום לפי מזהה, צריך להתקשר
ל-GMSPlacesClient
fetchPlaceFromPlaceID:
ולהעביר את הפרמטרים הבאים:
- מחרוזת שמכילה מזהה מקום.
GMSPlaceField
אחד או יותר, המציינים את סוגי הנתונים להחזרה.- אסימון של סשן, אם המשתמש מקבל קריאה כדי לסיים שאילתה של השלמה אוטומטית. אחרת, צריך להזין אפס.
GMSPlaceResultCallback
לטיפול בתוצאה.
ה-API מפעיל את שיטת הקריאה החוזרת (callback) שצוינה, ומעביר אובייקט
GMSPlace
. אם המקום לא נמצא, אובייקט המקום הוא אפס.
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]); } }];
הצגת ייחוסים באפליקציה
כשבאפליקציה מוצג מידע שהתקבל מ-GMSPlacesClient
lookUpPlaceID:callback:
, צריך להציג באפליקציה גם ייחוס (Attribution)
אפשר לעיין במסמכי התיעוד בנושא
שיוך (Attribution).
מידע נוסף על מזהי מקומות
מזהה המקום שבו נעשה שימוש ב-Place SDK ל-iOS הוא אותו מזהה שנעשה בו שימוש ב-Places API, ב-Place SDK ל-Android וב-Google APIs אחרים.
כל מזהה מקום יכול להתייחס רק למקום אחד, אבל לכל מקום יכול להיות יותר ממזהה אחד של מקום.
יש נסיבות מסוימות שעלולות לגרום למקום לקבל מזהה מקום חדש. לדוגמה, מצב כזה יכול לקרות אם עסק עובר למיקום חדש.
כשמבקשים מקום על ידי ציון מזהה מקום, אפשר להיות בטוחים שתמיד מקבלים את אותו מקום בתשובה (אם המקום עדיין קיים). עם זאת, חשוב לשים לב שהתשובה עשויה להכיל מזהה מקום השונה מזה שצוין בבקשה שלך.
מידע נוסף זמין בסקירה הכללית על מזהה מקום.