Places SDK ל-iOS (חדש) מספק לאפליקציה מידע עשיר על מקומות, כולל השם והכתובת של המקום, המיקום הגיאוגרפי שמצוין כקואורדינטות של קווי אורך ורוחב, סוג המקום (למשל מועדון לילה, חנות לחיות מחמד, מוזיאון) ועוד. כדי לגשת למידע הזה לגבי מקום ספציפי, אפשר להשתמש במזהה המקום – מזהה קבוע שמזהה מקום באופן ייחודי.
קבלת פרטים על המקום
המחלקה GMSPlace
מכילה מידע על מקום ספציפי, כולל כל שדות הנתונים שמוצגים בקטע שדות של נתוני מקום (חדש). מקבלים אובייקט GMSPlace
באמצעות קריאה ל-GMSPlacesClient
fetchPlaceWithRequest:
, העברת אובייקט GMSFetchPlaceRequest
ושיטת קריאה חוזרת מסוג GMSPlaceResultCallback
.
האובייקט GMSFetchPlaceRequest
מציין:
- (חובה) מזהה המקום, מזהה ייחודי של מקום במסד הנתונים של מקומות Google ובמפות Google.
- (חובה) רשימת השדות שיש להחזיר באובייקט
GMSPlace
, שנקראת גם מסכת שדות, כפי שהוגדרה על ידי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 }
תשובה לגבי 'פרטי מקום'
התכונה Place Details מחזירה אובייקט GMSPlace
שמכיל פרטים על המקום. רק השדות שצוינו ברשימת השדות יאוכלסו באובייקט GMSPlace
.
יחד עם שדות הנתונים, האובייקט GMSPlace
בתשובה מכיל את הפונקציות הבאות לחברים:
-
isOpen
מחשבת אם מקום מסוים פתוח בשעה הנתונה. isOpenAtDate
מחשבת אם מקום מסוים פתוח בתאריך מסוים.
פרמטרים נדרשים
יש להשתמש באובייקט GMSFetchPlaceRequest
כדי לציין את הפרמטרים הנדרשים.
מזהה מקום
מזהה המקום שמשמש ב-Place SDK ל-iOS זהה למזהה שמשמש ב-Places API, ב-Places SDK ל-Android וב-Google APIs אחרים. כל מזהה מקום יכול להתייחס רק למקום אחד, אבל למקום אחד יכול להיות יותר ממזהה אחד של מקום.
יש נסיבות מסוימות שעלולות לגרום למקום לקבל מזהה מקום חדש. לדוגמה, מצב כזה יכול לקרות אם עסק עובר למיקום חדש.
כשאתם מבקשים לקבל מקום על ידי ציון מזהה מקום, אתם יכולים להיות בטוחים שתקבלו תמיד את אותו מקום בתשובה (אם המקום עדיין קיים). עם זאת, שימו לב שהתשובה עשויה להכיל מזהה מקום שונה מזה שצוין בבקשה.
רשימת שדות
כשמבקשים פרטי מקום, צריך לציין את הנתונים שיוחזרו באובייקט 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, למעט כמה יוצאים מן הכלל. לדוגמה, שם הדומיין ברמה העליונה של בריטניה הוא "uk" (.co.uk) קוד ISO 3166-1 הוא "gb" (המונח הטכני הוא "בריטניה" וצפון אירלנד). הפרמטר יכול להשפיע על התוצאות בהתאם לדין החל.
sessionToken
אסימוני סשן הם מחרוזות שנוצרו על ידי משתמשים, שעוקבות אחר קריאות להשלמה אוטומטית (חדשות) כ'סשנים'. ההשלמה האוטומטית (חדש) משתמשת באסימוני פעילות כדי לקבץ את השאילתה ולמקם את שלבי הבחירה של חיפוש בהשלמה אוטומטית של משתמש בסשן נפרד למטרות חיוב. אסימוני הסשן מועברים לקריאות של פרטי מקום (חדש) שמתבצעות אחרי קריאות להשלמה אוטומטית (חדשה). מידע נוסף זמין במאמר אסימוני סשנים.
הצגת ייחוסים באפליקציה
כשבאפליקציה מוצג מידע שהתקבל מ-GMSPlacesClient
,
כמו תמונות וביקורות, האפליקציה צריכה להציג גם את פרטי הייחוס הנדרשים.
לדוגמה, המאפיין reviews
של האובייקט GMSPlacesClient
מכיל מערך של עד חמישה אובייקטים מסוג GMSPlaceReview
. כל אובייקט GMSPlaceReview
יכול להכיל ייחוסs ושמות של מחברים.
אם הביקורת שלך מוצגת באפליקציה, עליך להציג גם ייחוס או ייחוס למחבר.
למידע נוסף, עיינו במסמכי התיעוד בנושא שיוך (Attribution).