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

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

אחזור פרטי מקום

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

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

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

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

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

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

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

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

תגובה של Place Details

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

אחזור סטטוס פתוח

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

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

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

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

• GMSPlacePropertyUTCOffsetMinutes
• GMSPlacePropertyBusinessStatus
• GMSPlacePropertyOpeningHours
• GMSPlacePropertyCurrentOpeningHours
• GMSPlacePropertySecondaryOpeningHours

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

תגובה אחת (isOpenWithRequest)

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

חיוב עבור isOpenWithRequest

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

דוגמה: שליחת בקשה מסוג GMSPlaceIsOpenWithRequest

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

          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
          }
          

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

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

מזהה מקום

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

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

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

רשימת שדות

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

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

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

  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, מלבד כמה חריגים בולטים. לדוגמה, הדומיין ברמה העליונה של בריטניה הוא ‎"uk" (‎.co.uk), ואילו קוד ה-ISO 3166-1 שלה הוא ‎"gb" (טכנית, עבור הישות 'בריטניה וצפון אירלנד'). הפרמטר יכול להשפיע על התוצאות בהתאם לדין החל.

sessionToken

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

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

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

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

למידע נוסף, קראו את המאמר שיוך.