פרטי מקום

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

פרטי המקום

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

• קוראים לפונקציה GMSPlacesClient findPlaceLikelihoodsFromUserLocationWithPlaceFields:. אפשר לעיין במדריך בנושא קבלת המיקום הנוכחי.
• קוראים ל-GMSPlacesClient fetchPlaceFromPlaceID:, מעבירים את GMSPlaceField, מזהה מקום ושיטת קריאה חוזרת. בבקשות לפרטים של מקומות, אם לא מציינים שדה אחד לפחות בבקשה, או אם משמיטים את הפרמטר fields מהבקשה, כל השדות האפשריים יחזרו וייחויב בהתאם. איך מקבלים מקום לפי מזהה

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

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

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

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

      // 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 עם פרטי המקום.

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

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

- (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. אם המקום לא נמצא, אובייקט המקום יהיה null.

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

// 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 ובממשקי Google API אחרים.

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

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

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

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