פרטי מקום

‫Places SDK for 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 מחזירה את הערך True אם המקום פתוח בתאריך מסוים, על סמך openingHours ו-UTCOffsetMinutes, ועל סמך התאריך והשעה הנוכחיים.

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

    בסרטון הזה מוסבר איך משתמשים ב-isOpen עם פרטי מקום .

קבלת שעות פתיחה מיוחדות

שעות הפתיחה הרגילות מתקבלות דרך 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:, היא חייבת להציג גם את פרטי השיוך. אפשר לעיין בתיעוד בנושא שיוך.

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

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

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

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

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

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