Places SDK ל-iOS (חדש) מספק לאפליקציה מידע עשיר מידע על מקומות, כולל השם והכתובת של המקום, המיקומים הגיאוגרפיים המיקום מצוין כקואורדינטות של קו אורך/רוחב, סוג המקום (כגון כמו מועדון לילה, חנות לחיות מחמד, מוזיאון) ועוד. כדי לגשת למידע הזה עבור אפשר להשתמש במזהה מקום, שהוא מזהה קבוע שמזהה מקום מסוים.
קבלת פרטים על מקום
GMSPlace
הכיתה מכילה מידע על מקום ספציפי, כולל כל שדות הנתונים שמוצגים
שדות של נתוני מקום (חדש). לקבלת
GMSPlace
של אובייקט באמצעות קריאה לאובייקט
GMSPlacesClient
fetchPlaceWithRequest:
,
העברת אובייקט GMSFetchPlaceRequest
ו
שיטת קריאה חוזרת (callback) מסוג
GMSPlaceResultCallback
.
האובייקט GMSFetchPlaceRequest
מציין:
- (חובה) מזהה המקום, מזהה ייחודי של מקום ב'מקומות Google'. במסד הנתונים ובמפות Google.
- (חובה) רשימת השדות שצריך להחזיר באובייקט
GMSPlace
, שנקראת גם field mask, כפי שמוגדר על ידיGMSPlaceProperty
אם לא מציינים שדה אחד לפחות ברשימת השדות, או אם משמיטים שדה. ברשימת השדות, ואז הקריאה מחזירה שגיאה. - (אופציונלי) קוד האזור שמשמש לעיצוב התשובה.
- (אופציונלי) אסימון הסשן שמשמש לסיום סשן של השלמה אוטומטית (חדש).
יש להגיש בקשה לפרטי מקום
בדוגמה הזו מוצג מקום לפי מזהה ומעבירים את הפרמטרים הבאים:
- מזהה המקום של
ChIJV4k8_9UodTERU5KXbkYpSYs
. - רשימת שדות שמציינת להחזיר את שם המקום וכתובת האתר.
GMSPlaceResultCallback
כדי לטפל בתוצאה.
ה-API מפעיל את שיטת הקריאה החוזרת שצוינה ומעביר
GMSPlace
לאובייקט. אם המקום לא נמצא, אובייקט המקום הוא אפס.
Swift
// A hotel in Saigon with an attribution. let placeID = "ChIJV4k8_9UodTERU5KXbkYpSYs" // Specify the place data types to return. let myProperties = [GMSPlaceProperty.name, GMSPlaceProperty.website].map {$0.rawValue} // Create the GMSFetchPlaceRequest object. let fetchPlaceRequest = GMSFetchPlaceRequest(placeID: placeID, placeProperties: myProperties, sessionToken: nil) client.fetchPlace(with: fetchPlaceRequest, callback: { (place: GMSPlace?, error: Error?) in guard let place, error == nil else { return } print("Place found: \(String(describing: place.name))") })
Objective-C
// A hotel in Saigon with an attribution. NSString *placeID = @"ChIJV4k8_9UodTERU5KXbkYpSYs"; // Specify the place data types to return. NSArray<NSString *> *myProperties = @[GMSPlacePropertyName, GMSPlacePropertyWebsite]; // Create the GMSFetchPlaceRequest object. GMSFetchPlaceRequest *fetchPlaceRequest = [[GMSFetchPlaceRequest alloc] initWithPlaceID:placeID placeProperties: myProperties sessionToken:nil]; [placesClient fetchPlaceWithRequest: fetchPlaceRequest callback: ^(GMSPlace *_Nullable place, NSError *_Nullable error) { if (error != nil) { NSLog(@"An error occurred %@", [error localizedDescription]); return; } else { NSLog(@"Place Found: %@", place.name); NSLog(@"The place URL: %@", place.website); } }];
GooglePlacesSwift
// A hotel in Saigon with an attribution. let placeID = "ChIJV4k8_9UodTERU5KXbkYpSYs" let fetchPlaceRequest = FetchPlaceRequest( placeID: placeID, placeProperties: [.name, .website] ) switch await placesClient.fetchPlace(with: fetchPlaceRequest) { case .success(let place): // Handle place case .failure(let placesError): // Handle error }
תשובה עם פרטי מקום
השדה 'פרטי מקום' מחזיר
אובייקט GMSPlace
שמכיל פרטים על המקום. רק השדות שצוינו ברשימת השדות מאוכלסים באובייקט GMSPlace
.
יחד עם שדות הנתונים, האובייקט GMSPlace
התשובה מכילה את פונקציות האיבר הבאות:
-
isOpen
מחשבת אם המקום פתוח בזמן נתון. isOpenAtDate
הפונקציה קובעת אם מקום מסוים פתוח בתאריך מסוים.
פרמטרים נדרשים
משתמשים באובייקט GMSFetchPlaceRequest
כדי לציין את הפרמטרים הנדרשים.
מזהה מקום
מזהה המקום שנעשה בו שימוש ב-Places SDK ל-iOS הוא אותו מזהה כמו ב-Places API, Place SDK ל-Android וממשקי API אחרים של Google. כל מזהה מקום יכול להתייחס למקום אחד בלבד, אבל למקום אחד יכולים להיות יותר ממזהה מקום אחד.
יש נסיבות מסוימות שעשויות לגרום למקום לקבל מזהה חדש של מקום. לדוגמה, מצב כזה יכול לקרות אם עסק עובר למיקום חדש.
כשמבקשים מקום באמצעות ציון מזהה של מקום, אפשר להיות בטוחים תמיד תקבלו את אותו מקום בתשובה (אם המקום עדיין קיים). עם זאת, שים לב שהתשובה עשויה להכיל מזהה מקום שונה מזה שצוין בבקשה.
רשימת שדות
כשמבקשים פרטי מקום, צריך לציין את הנתונים
מוחזר באובייקט GMSPlace
עבור המקום בתור מסיכת שדה. כדי להגדיר את המסכה של השדות
להעביר מערך של ערכים
GMSPlaceProperty
לאובייקט GMSFetchPlaceRequest
.
התממה של שדות היא שיטה טובה לעיצוב כדי להבטיח שלא תבקשו נתונים מיותרים,
עוזר להימנע מזמן עיבוד ומחיובים מיותרים.
צריך לציין אחד או יותר מהשדות הבאים:
השדות הבאים מפעילים את המק"ט של פרטי המקום (מזהה בלבד):
GMSPlacePropertyPlaceID
,GMSPlacePropertyName
,GMSPlacePropertyPhotos
השדות הבאים מפעילים את המק"ט של פרטי המקום (מיקום בלבד):
GMSPlacePropertyAddressComponents
,GMSPlacePropertyFormattedAddress
,GMSPlacePropertyCoordinate
,GMSPlacePropertyPlusCode
,GMSPlacePropertyTypes
,GMSPlacePropertyViewport
השדות הבאים מפעילים את המק"ט של פרטי המקום (בסיסי):
GMSPlacePropertyBusinessStatus
,GMSPlacePropertyIconBackgroundColor
,GMSPlacePropertyIconImageURL
,GMSPlacePropertyUTCOffsetMinutes
,GMSPlacePropertyWheelchairAccessibleEntrance
השדות הבאים מפעילים את המק"ט של פרטי המקום (מתקדם):
GMSPlacePropertyCurrentOpeningHours
,GMSPlacePropertySecondaryOpeningHours
,GMSPlacePropertyPhoneNumber
,GMSPlacePropertyPriceLevel
,GMSPlacePropertyRating
,GMSPlacePropertyOpeningHours
,GMSPlacePropertyUserRatingsTotal
,GMSPlacePropertyWebsite
השדות הבאים מפעילים את המק"ט של פרטי המקום (מועדף):
GMSPlacePropertyCurbsidePickup
,GMSPlacePropertyDelivery
,GMSPlacePropertyDineIn
,GMSPlacePropertyEditorialSummary
,GMSPlacePropertyReservable
,GMSPlacePropertyReviews
,GMSPlacePropertyServesBeer
,GMSPlacePropertyServesBreakfast
,GMSPlacePropertyServesBrunch
,GMSPlacePropertyServesDinner
,GMSPlacePropertyServesLunch
,GMSPlacePropertyServesVegetarianFood
,GMSPlacePropertyServesWine
,GMSPlacePropertyTakeout
הדוגמה הבאה מעבירה רשימה של
ערכי שדות
כדי לציין שהאובייקט GMSPlace
שהוחזר על ידי בקשה מכיל את הפונקציה
השדות name
ו-placeID
:
Swift
// Specify the place data types to return. let fields: [GMSPlaceProperty] = [.placeID, .name]
Objective-C
// Specify the place data types to return. NSArray<GMSPlaceProperty *> *fields = @[GMSPlacePropertyPlaceID, GMSPlacePropertyName];
GooglePlacesSwift
// Specify the place data types to return. let fields: [PlaceProperty] = [.placeID, .displayName]
פרמטרים אופציונליים
משתמשים באובייקט GMSFetchPlaceRequest
כדי לציין את הפרמטרים האופציונליים.
regionCode
קוד האזור שמשמש לעיצוב התשובה, מצוין בתור ערך CLDR בן שני תווים. לפרמטר הזה יכולה להיות גם אפקט הטיה בתוצאות החיפוש. אין ערך ברירת מחדל.
אם שם המדינה בשדה הכתובת בתשובה תואם את קידומת החיוג האזורית, קוד המדינה יושמט מהכתובת.
רוב קודי ה-CLDR זהים לקודי ISO 3166-1. עם כמה יוצאים מן הכלל. לדוגמה, ה-ccTLD של בריטניה הוא "uk" (.co.uk) כשקוד ISO 3166-1 הוא "gb" (טכנית עבור ישות "בריטניה וצפון אירלנד"). הפרמטר יכול להשפיע על התוצאות בהתאם לחוק הרלוונטי.
sessionToken
אסימוני סשן הם מחרוזות שנוצרו על ידי משתמשים ועוקבות אחרי ההשלמה האוטומטית (חדש) שיחות כ'סשנים'. השלמה אוטומטית (חדש) משתמשת באסימוני הפעלה כדי לקבץ את שלבי השאילתה ובחירת המקום של חיפוש ההשלמה האוטומטית של המשתמש לסשן נפרד למטרות חיוב. אסימוני הסשן מועברים לפרטי המקום (חדש) קריאות שמגיעות לאחר הפעלות של השלמה אוטומטית (חדש). מידע נוסף זמין במאמר הבא: אסימונים של סשן.
הצגת ייחוס באפליקציה
מתי האפליקציה מציגה מידע שהתקבל מ
GMSPlacesClient
כמו תמונות וביקורות, האפליקציה חייבת גם להציג את הייחוסים הנדרשים.
לדוגמה, המאפיין reviews
של האובייקט GMSPlacesClient
מכיל מערך של עד חמש
GMSPlaceReview
אובייקטים. כל אובייקט GMSPlaceReview
יכול להכיל ייחוס וייחוס של מחברים.
אם הביקורת מוצגת באפליקציה, צריך לציין גם ייחוס או מחבר
Attribution.
למידע נוסף, אפשר לקרוא את מאמרי העזרה בנושא שיוכים.