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

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

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

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

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

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

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

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

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

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

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

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

תשובה של Place Details

הפונקציה Place Details מחזירה אובייקט GMSPlace שמכיל פרטים על המקום. רק השדות שצוינו ברשימת השדות מאוכלסים באובייקט GMSPlace.

איך בודקים את סטטוס הפתיחה

האובייקט GMSPlacesClient מכיל פונקציית חבר שנקראת isOpenWithRequest (isOpenRequest ב-Swift ו-isPlaceOpenRequest ב-GooglePlacesSwift) שמחזירה תגובה שמציינת אם המקום פתוח כרגע, על סמך השעה שצוינה בקריאה.

השיטה הזו מקבלת ארגומנט יחיד מסוג GMSPlaceIsOpenWithRequest שמכיל:

• אובייקט GMSPlace או מחרוזת שמציינת מזהה מקום. מידע נוסף על יצירת אובייקט Place עם השדות הנדרשים זמין במאמר פרטי מקום.
  
• אובייקט אופציונלי NSDate (Obj-C) או Date (Swift) שמציין את השעה שרוצים לבדוק. אם לא מציינים שעה, ברירת המחדל היא השעה הנוכחית.
• ‫GMSPlaceOpenStatusResponseCallback method לטיפול בתשובה.
>

כדי להשתמש בשיטה GMSPlaceIsOpenWithRequest, צריך להגדיר את השדות הבאים באובייקט GMSPlace:

• GMSPlacePropertyUTCOffsetMinutes
• GMSPlacePropertyBusinessStatus
• GMSPlacePropertyOpeningHours
• GMSPlacePropertyCurrentOpeningHours
• GMSPlacePropertySecondaryOpeningHours

אם השדות האלה לא מופיעים באובייקט Place, או אם מעבירים מזהה של מקום, השיטה משתמשת ב-GMSPlacesClient GMSFetchPlaceRequest: כדי לאחזר אותם.

תגובה אחת (isOpenWithRequest)

‫isOpenWithRequest מחזירה אובייקט GMSPlaceIsOpenResponse שמכיל ערך בוליאני בשם status שמציין אם העסק פתוח, סגור או אם הסטטוס לא ידוע.

חיוב על isOpenWithRequest

• החיוב על השדות GMSPlacePropertyUTCOffsetMinutes ו-GMSPlacePropertyBusinessStatus מתבצע במסגרת מק"ט של נתונים בסיסיים. שאר שעות הפתיחה מחויבות במסגרת מק"ט Place Details Enterprise.
• אם לאובייקט GMSPlace כבר יש את השדות האלה מבקשה קודמת, לא תחויבו שוב.

דוגמה: יצירת בקשת GMSPlaceIsOpenWithRequest

        let isOpenRequest = IsPlaceOpenRequest(place: place)
        switch await placesClient.isPlaceOpen(with: isOpenRequest) {
          case .success(let isOpenResponse):
            switch isOpenResponse.status {
              case true:
                // Handle open
              case false:
                // Handle closed
              case nil:
                // Handle unknown
          case .failure(let placesError):
            // Handle error
        }
        

    let isOpenRequest = GMSPlaceIsOpenRequest(place: place, date: nil)
      GMSPlacesClient.shared().isOpen(with: isOpenRequest) { response, error in
        if let error = error {
          // Handle Error
        }
        switch response.status {
          case .open:
            // Handle open
          case .closed:
            // Handle closed
          case .unknown:
            // Handle unknown
        }
      }
        

          GMSPlaceIsOpenRequest *isOpenRequest = [[GMSPlaceIsOpenRequest alloc] initWithPlace:place date:nil];

          [[GMSPlacesClient sharedClient] isOpenWithRequest:isOpenRequest callback:^(GMSPlaceIsOpenResponse response, NSError *_Nullable error) {
            if (error) {
              // Handle error
            }

            switch (response.status) {
              case GMSPlaceOpenStatusOpen:
                // Handle open
              case GMSPlaceOpenStatusClosed:
                // Handle closed
              case GMSPlaceOpenStatusUnknown:
                // Handle unknown
            }
          }];
          

פרמטרים נדרשים

משתמשים באובייקט GMSFetchPlaceRequest כדי לציין את הפרמטרים הנדרשים.

מזהה מקום

מזהה המקום שמשמש ב-Places SDK ל-iOS הוא אותו מזהה שמשמש ב-Places API, ב-Places SDK ל-Android ובממשקי API אחרים של Google. כל מזהה מקום יכול להתייחס רק למקום אחד, אבל למקום אחד יכולים להיות יותר ממזהה מקום אחד.

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

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

רשימת השדות

כשמבקשים פרטים על מקום, צריך לציין את הנתונים שיוחזרו באובייקט GMSPlace של המקום כמסכת שדות. כדי להגדיר את מסכת השדה, מעבירים מערך של ערכים מ-GMSPlaceProperty לאובייקט GMSFetchPlaceRequest. הסתרת שדות היא שיטת עיצוב מומלצת שמאפשרת לוודא שלא מתבצעת בקשה לנתונים מיותרים, וכך להימנע מזמן עיבוד מיותר ומחיובים מיותרים.

מציינים אחד או יותר מהשדות הבאים:

• השדות הבאים מפעילים את מק"ט Place Details Essentials ID Only:

  GMSPlacePropertyPlaceID
GMSPlacePropertyPhotos

  רשימה מלאה של השדות והמק"טים המשויכים אליהם מופיעה במאמר בנושא שדות של נתוני מקומות (חדש).

• השדות הבאים מפעילים את מק"ט Place Details Essentials:

  GMSPlacePropertyAddressComponents
GMSPlacePropertyFormattedAddress
GMSPlacePropertyCoordinate
GMSPlacePropertyPlusCode
GMSPlacePropertyTypes
GMSPlacePropertyViewport

  רשימה מלאה של השדות והמק"טים המשויכים אליהם מופיעה במאמר בנושא שדות של נתוני מקומות (חדש).

• השדות הבאים מפעילים את מזהה המק"ט Place Details Pro:

  GMSPlacePropertyBusinessStatus
GMSPlacePropertyIconBackgroundColor
GMSPlacePropertyIconImageURL
GMSPlacePropertyName
GMSPlacePropertyUTCOffsetMinutes
GMSPlacePropertyWheelchairAccessibleEntrance

  רשימה מלאה של השדות והמק"טים המשויכים אליהם מופיעה במאמר בנושא שדות של נתוני מקומות (חדש).

• השדות הבאים מפעילים את מזהה המק"ט Place Details Pro:

  GMSPlacePropertyCurrentOpeningHours
GMSPlacePropertySecondaryOpeningHours
GMSPlacePropertyPhoneNumber
GMSPlacePropertyPriceLevel
GMSPlacePropertyRating
GMSPlacePropertyOpeningHours
GMSPlacePropertyUserRatingsTotal
GMSPlacePropertyWebsite

  רשימה מלאה של השדות והמק"טים המשויכים אליהם מופיעה במאמר בנושא שדות של נתוני מקומות (חדש).

• השדות הבאים מפעילים את מזהה המק"ט של Place Details Enterprise:

  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: [PlaceProperty] = [.placeID, .displayName]
    

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

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

פרמטרים אופציונליים

כדי לציין את הפרמטרים האופציונליים, משתמשים באובייקט GMSFetchPlaceRequest.

regionCode

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

אם שם המדינה בשדה הכתובת בתשובה תואם לקוד האזור, קוד המדינה מושמט מהכתובת.

רוב הקודים של CLDR זהים לקודים של ISO 3166-1, אבל יש כמה יוצאים מן הכלל. לדוגמה, ה-ccTLD של בריטניה הוא uk (‎.co.uk), אבל קוד ISO 3166-1 שלה הוא gb (טכנית, עבור הישות 'ממלכת בריטניה הגדולה וצפון אירלנד'). הפרמטר יכול להשפיע על התוצאות בהתאם לדין החל.

sessionToken

אסימוני סשן הם מחרוזות שנוצרות על ידי המשתמש ועוקבות אחרי קריאות ל-Autocomplete (New) בתור 'סשנים'. ההשלמה האוטומטית (חדש) משתמשת באסימוני סשן כדי לקבץ את השאילתה ואת שלבי הבחירה של חיפוש השלמה אוטומטית של משתמש בסשן נפרד למטרות חיוב. טוקנים של סשנים מועברים לקריאות של Place Details (חדש) אחרי קריאות של Autocomplete (חדש). מידע נוסף זמין במאמר אסימוני סשן.

הצגת שיוכים באפליקציה

אם האפליקציה מציגה מידע שהתקבל מ-GMSPlacesClient, כמו תמונות וביקורות, היא צריכה להציג גם את הקרדיטים הנדרשים.

לדוגמה, המאפיין reviews של האובייקט GMSPlacesClient מכיל מערך של עד חמישה אובייקטים מסוג GMSPlaceReview. כל אובייקט GMSPlaceReview יכול להכיל שיוכים ושיוכים של מחברים. אם אתם מציגים את הביקורת באפליקציה, אתם צריכים להציג גם את השיוך או את שיוך המחבר.

מידע נוסף מופיע במאמר בנושא שיוכים.