דף זה תורגם על ידי Cloud Translation API.

פרטי מקומות

בחירת פלטפורמה: Android iOS JavaScript שירות אינטרנט

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

פרטי המקום

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

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

אזהרה: אם לא תציינו לפחות שדה אחד בבקשה, או אם תשמיטו את הפרמטר fields בבקשה, כל השדות האפשריים יוחזרו ואנחנו נחייב אתכם בהתאם. רלוונטי רק לבקשות לקבלת פרטי מקום.

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

GMSPlaceFieldTakeout, GMSPlaceFieldDelivery, GMSPlaceFieldDineIn, GMSPlaceFieldCurbsidePickup, GMSPlaceFieldPhoneNumber, GMSPlaceFieldWebsite, GMSPlaceFieldOpeningHours ו-GMSPlaceFieldAddressComponents לא נתמכים GMSPlaceLikelihoodList אובייקטים של מיקום.

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

הסיווג 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

ליהנות משעות פתיחה יוצאות מן הכלל

שעות הפתיחה הרגילות מתקבלות דרך 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
    }
}

קבלת מקום לפי מזהה

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

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

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

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

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) אפשר לעיין במסמכי התיעוד בנושא שיוך (Attribution).

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

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

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

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

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

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