פרטי מקום (חדש)

Places SDK ל-iOS (חדש) מספק לאפליקציה מידע עשיר מידע על מקומות, כולל השם והכתובת של המקום, המיקומים הגיאוגרפיים המיקום מצוין כקואורדינטות של קו אורך/רוחב, סוג המקום (כגון כמו מועדון לילה, חנות לחיות מחמד, מוזיאון) ועוד. כדי לגשת למידע הזה עבור אפשר להשתמש במזהה מקום, שהוא מזהה קבוע שמזהה מקום מסוים.

קבלת פרטים על מקום

GMSPlace הכיתה מכילה מידע על מקום ספציפי, כולל כל שדות הנתונים שמוצגים שדות של נתוני מקום (חדש). לקבלת GMSPlace של אובייקט באמצעות קריאה לאובייקט GMSPlacesClient fetchPlaceWithRequest:, העברת אובייקט GMSFetchPlaceRequest ו שיטת קריאה חוזרת (callback) מסוג GMSPlaceResultCallback.

האובייקט GMSFetchPlaceRequest מציין:

• (חובה) מזהה המקום, מזהה ייחודי של מקום ב'מקומות Google'. במסד הנתונים ובמפות Google.
• (חובה) רשימת השדות שצריך להחזיר באובייקט GMSPlace, שנקראת גם field mask, כפי שמוגדר על ידי GMSPlaceProperty אם לא מציינים שדה אחד לפחות ברשימת השדות, או אם משמיטים שדה. ברשימת השדות, ואז הקריאה מחזירה שגיאה.
• (אופציונלי) קוד האזור שמשמש לעיצוב התשובה.
• (אופציונלי) אסימון הסשן שמשמש לסיום סשן של השלמה אוטומטית (חדש).

יש להגיש בקשה לפרטי מקום

בדוגמה הזו מוצג מקום לפי מזהה ומעבירים את הפרמטרים הבאים:

• מזהה המקום של ChIJV4k8_9UodTERU5KXbkYpSYs.
• רשימת שדות שמציינת להחזיר את שם המקום וכתובת האתר.
• GMSPlaceResultCallback כדי לטפל בתוצאה.

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

// 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))")
})

// 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);
  }
}];

// 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:

// Specify the place data types to return.
let fields: [GMSPlaceProperty] = [.placeID, .name]
  

// Specify the place data types to return.
NSArray<GMSPlaceProperty *> *fields = @[GMSPlacePropertyPlaceID, GMSPlacePropertyName];
  

// 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.

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