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

בחירת פלטפורמה: Android iOS JavaScript Web Service
מפתחים באזור הכלכלי האירופי (EEA)

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

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

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

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

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

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

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

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

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

Places Swift SDK

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

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 retur<n.
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.
    • >

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

  • GMSPlacePropertyUTCOffsetMinutes
  • GMSPlacePropertyBusinessStatus
  • GMSPlacePropertyOpeningHours
  • GMSPlacePropertyCurrentOpeningHours
  • GMSPlacePropertySecondaryOpeningHours

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

תגובה אחת (isOpenWithRequest)

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

שפה הערך אם הפריט פתוח ערך אם העסק סגור ערך אם הסטטוס לא ידוע
Places Swift true false nil
Swift .open .closed .unknown
Objective-C GMSPlaceOpenStatusOpen GMSPlaceOpenStatusClosed GMSPlaceOpenStatusUnknown

חיוב על isOpenWithRequest

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

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

בדוגמה הבאה מוצג אופן ההגדרה של GMSPlaceIsOpenWithRequest בתוך אובייקט GMSPlace קיים.

Places Swift SDK

        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
        }

Swift

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

Objective-C

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

Places Swift SDK

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

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

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

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

regionCode

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

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

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

sessionToken

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

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

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

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

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