פרטי מקום

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

פרטי המקום

הכיתה GMSPlace מספקת מידע על מקום ספציפי. אפשר לקבל אובייקט GMSPlace בדרכים הבאות:

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

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

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

Swift

      // A hotel in Saigon with an attribution.
      let placeID = "ChIJV4k8_9UodTERU5KXbkYpSYs"

      // Specify the place data types to return.
      let fields: GMSPlaceField = GMSPlaceField(rawValue: UInt(GMSPlaceField.name.rawValue) |
      UInt(GMSPlaceField.placeID.rawValue))

Objective-C

      // A hotel in Saigon with an attribution.
      NSString *placeID = @"ChIJV4k8_9UodTERU5KXbkYpSYs";

      // Specify the place data types to return.
      GMSPlaceField fields = (GMSPlaceFieldName | GMSPlaceFieldPlaceID);

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

הכיתה GMSPlace יכולה להכיל את נתוני המקומות הבאים:

  • ‫name – שם המקום.
  • editorialSummary – תיאור של מקום.
  • ‫placeID – המזהה הטקסטואלי של המקום. בהמשך הדף הזה מפורט מידע נוסף על מזהי מקומות.
  • ‫coordinate – המיקום הגיאוגרפי של המקום, שמצוין כקואורדינטות של קו רוחב וקו אורך.
  • phoneNumber – מספר הטלפון של המקום, בפורמט לחיוג בינלאומי.
  • ‫formattedAddress – הכתובת של המיקום הזה, שקריאה לאנשים.

    בדרך כלל הכתובת הזו זהה לכתובת למשלוח דואר. שימו לב שבמדינות מסוימות, כמו בריטניה, אסור להפיץ כתובות דואר אמיתיות בגלל הגבלות רישוי.

    הכתובת בפורמט מורכבת באופן לוגי מרכיב כתובת אחד או יותר. לדוגמה, הכתובת "111 8th Avenue, New York, NY" מורכבת מהרכיבים הבאים: "111" (מספר הרחוב), "8th Avenue" (המסלול), "New York" (העיר) ו-"NY" (המדינה בארה"ב).

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

  • ‫openingHours – שעות הפתיחה של המקום (כפי שמיוצגות על ידי GMSOpeningHours). אפשר להפעיל את GMSOpeningHours.weekdayText כדי לקבל רשימה של מחרוזות מקומיות של שעות הפתיחה היומיות במהלך השבוע. מפעילים את GMSOpeningHours.Periods כדי להחזיר רשימה של GMSPeriod עם מידע מפורט יותר, ששווה ערך לנתונים שסופקו על ידי weekdayText. הערה: אם המקום פתוח תמיד, פרק הזמן מיוצג כיום ראשון בחצות, והערך של closeEvent הוא null.
  • ‫currentOpeningHours ו-secondaryOpeningHours – שדות שבהם אפשר להזין שינויים זמניים בלוח הזמנים של מקום מסוים, למשל בחגים.

  • ‫addressComponents – מערך של אובייקטים מסוג GMSAddressComponent שמייצגים רכיבים של הכתובת של המקום. הרכיבים האלה מסופקים כדי לחלץ מידע מובנה על הכתובת של מקום, למשל כדי למצוא את העיר שבה המקום נמצא. אל תשתמשו ברכיבים האלה כדי לעצב את הכתובת. במקום זאת, השתמשו במאפיין formattedAddress, שמספק כתובת בפורמט מקומי.

    שימו לב לעובדות הבאות לגבי המערך addressComponents:

    • מערך רכיבי הכתובת יכול להכיל יותר רכיבים מאשר formattedAddress.
    • המערך לא בהכרח כולל את כל הישויות הפוליטיות שמכילות כתובת, מלבד אלה שנכללות ב-formattedAddress.
    • אין ערובה לכך שפורמט התגובה יישאר זהה בין הבקשות. ‫במיוחד, מספר ה-addressComponents משתנה בהתאם לכתובת המבוקשת ויכול להשתנות עם הזמן עבור אותה כתובת. רכיב יכול לשנות את המיקום שלו במערך. סוג הרכיב יכול להשתנות. יכול להיות שרכיב מסוים לא יופיע בתגובה מאוחרת יותר.
  • userRatingsTotal – מייצג את מספר הביקורות שמרכיבות את הדירוג של המקום.

הכיתה GMSPlace מכילה את פונקציות החברים הבאות:

  • ‫ isOpen מחשב אם מקום פתוח בזמן נתון, על סמך openingHours ו-UTCOffsetMinutes, והתאריך והשעה הנוכחיים.
  • isOpenAtDate מחשב אם מקום פתוח בתאריך נתון, על סמך openingHours ו-UTCOffsetMinutes, והתאריך והשעה הנוכחיים.

    • כשמשתמשים בפונקציות האלה כדי לקבל שעות פתיחה או תאריכים, הבקשה המקורית של fetchPlaceFromPlaceID: או findPlaceLikelihoodsFromUserLocationWithPlaceFields: צריכה לציין גם את השדה GMSPlaceFieldOpeningHours וגם את השדה GMSPlaceFieldUTCOffsetMinutes. אם אחד מהשדות האלה חסר, האובייקט GMSPlace שנוצר לא יכיל שעות פתיחה או תאריכים, והקריאה תחזיר את הערך GMSPlaceOpenStatusUnknown. כדי לקבל תוצאות מדויקות, צריך לבקש את השדות GMSPlaceFieldBusinessStatus ו-GMSPlaceFieldUTCOffsetMinutes בבקשה המקורית של המקום. אם לא נשלחה בקשה, ההנחה היא שהעסק פעיל.

    כדי ללמוד איך להשתמש ב-isOpen עם Place Details, אפשר לצפות בסרטון שמסביר איך לקבל את שעות הפתיחה .

קבלת שעות פתיחה חריגות

שעות הפתיחה הרגילות מתקבלות דרך openingHours, ו-currentOpeningHours ו-secondaryOpeningHours תומכים בשינויים זמניים בלוח הזמנים ובשינויים בלוח הזמנים בחגים. אם יש שעות פתיחה חריגות בימים המיוחדים האלה, אפשר לסנן ולהציג אותן.

Swift

    func examineOpeningHours(place: GMSPlace) {

      // Check if the current opening hours contains a special day that has exceptional hours
      guard let currentOpeningHours = place.currentOpeningHours else { return }
      if let specialDays = currentOpeningHours.specialDays {
        guard !specialDays.isEmpty else { return }
        if let specialDay = specialDays.filter { $0.isExceptional }.first  {
          // Indicate exceptional hours
        }
      }

      // Check if current opening hours contains a truncated time period
      let periods = currentOpeningHours.periods

      if !periods.isEmpty {
        for period in periods {
          let open = period.open
          let close = period.close

          if let open = open {
            let date = open.date

            if open.isTruncated {
              // Indicate truncated time period
            }
          }
        }
      }

      // Check if the place's secondary opening hours indicate when delivery is available
      let secondaryOpeningHours = place.secondaryOpeningHours
      guard let hoursType = secondaryOpeningHours.first?.hoursType else {
      return
      }

      if (hoursType == GMSPlaceHoursTypeDelivery) {
        // Indicate hours where delivery is available
      }
  }

Objective-C

- (void)examineOpeningHours:(GMSPlace *) place {

    // Check if the current opening hours contains a special day that has exceptional hours
    GMSOpeningHours *currentOpeningHours = place.currentOpeningHours;
    if (currentOpeningHours != nil) {
      NSArray<GMSPlaceSpecialDay *> *specialDays = currentOpeningHours.specialDays;
      if ([specialDays count] != 0) {
        for (GMSPlaceSpecialDay *specialDay in specialDays) {
          NSDate *date = specialDay.date;
          if ([specialDay isExceptional]) {
            // Indicate exceptional hours
          }
        }
      }
    }

    // Check if current opening hours contains a truncated time period
    NSArray <GMSPeriod *> * periods = currentOpeningHours.periods;

    if ([periods count] != 0) {
      for (GMSPeriod * period in periods) {
        GMSTimeOfWeek *open = period.open;
        GMSTimeOfWeek *close = period.close;

        if (open) {
          if ([open isTruncated]) {
            // Indicate truncated time period
          }
        }
      }
    }

    // Check if the place's secondary opening hours indicate when delivery is available
    GMSOpeningHours *secondaryOpeningHours = place.secondaryOpeningHours;
    GMSPlaceHoursType hoursType = secondaryOpeningHours.getHoursType;

    if (hoursType == GMSPlaceHoursTypeDelivery) {
      // Indicate hours where delivery is available
    }
}

אחזור מקום לפי מזהה

מזהה מקום הוא מזהה טקסטואלי שמזהה מקום באופן ייחודי. ב-Places SDK ל-iOS, אפשר לאחזר את המזהה של מקום מאובייקט GMSPlace. אפשר לאחסן את מזהה המקום ולהשתמש בו כדי לאחזר את האובייקט GMSPlace שוב מאוחר יותר.

כדי לקבל מקום לפי מזהה, מפעילים את GMSPlacesClient fetchPlaceFromPlaceID: ומעבירים את הפרמטרים הבאים:

  • מחרוזת שמכילה מזהה מקום.
  • ‫GMSPlaceField אחד או יותר, שמציינים את סוגי הנתונים שיוחזרו.
  • טוקן לסשן, אם הקריאה מתבצעת כדי להשלים שאילתה של השלמה אוטומטית. אחרת, מעבירים nil.
  • ‫GMSPlaceResultCallback לטיפול בתוצאה.

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

Places Swift SDK ל-iOS

// Initialize Places Swift Client.
let placesClient = PlacesClient.shared

// A hotel in Saigon with an attribution
let placeID = "ChIJV4k8_9UodTERU5KXbkYpSYs"
    
// Fetch Place Request.
let fetchPlaceRequest = FetchPlaceRequest(
  placeID: placeID,
  placeProperties: [.displayName]
)
    
Task {
  switch await placesClient.fetchPlace(with: fetchPlaceRequest) {
  case .success(let place):
    print("The selected place is: \(place.displayName): \(String(describing: place.description))")
  case .failure(let placesError):
    print("Place not found: \(placeID); \(placesError)")
  }
}

Swift

// A hotel in Saigon with an attribution.
let placeID = "ChIJV4k8_9UodTERU5KXbkYpSYs"

// Specify the place data types to return.
let fields: GMSPlaceField = GMSPlaceField(rawValue: UInt(GMSPlaceField.name.rawValue) |
  UInt(GMSPlaceField.placeID.rawValue))!

placesClient?.fetchPlace(fromPlaceID: placeID, placeFields: fields, sessionToken: nil, callback: {
  (place: GMSPlace?, error: Error?) in
  if let error = error {
    print("An error occurred: \(error.localizedDescription)")
    return
  }
  if let place = place {
    self.lblName?.text = place.name
    print("The selected place is: \(place.name)")
  }
})

Objective-C

// A hotel in Saigon with an attribution.
NSString *placeID = @"ChIJV4k8_9UodTERU5KXbkYpSYs";

// Specify the place data types to return.
GMSPlaceField fields = (GMSPlaceFieldName | GMSPlaceFieldPlaceID);

[_placesClient fetchPlaceFromPlaceID:placeID placeFields:fields sessionToken:nil callback:^(GMSPlace * _Nullable place, NSError * _Nullable error) {
  if (error != nil) {
    NSLog(@"An error occurred %@", [error localizedDescription]);
    return;
  }
  if (place != nil) {
    NSLog(@"The selected place is: %@", [place name]);
  }
}];

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

כשהאפליקציה מציגה מידע שהתקבל מ-GMSPlacesClient lookUpPlaceID:callback:, היא צריכה להציג גם את השיוך (Attribution). למידע נוסף על מאפיינים

מידע נוסף על מזהי מקומות

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

כל מזהה מקום יכול להתייחס למקום אחד בלבד, אבל למקום אחד יכולים להיות כמה מזהי מקומות.

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

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

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