פרטי מקומות

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

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

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

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

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

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

    הכתובת המעוצבת מורכבת באופן לוגי מכתובת אחת או יותר רכיבים. לדוגמה, הכתובת "שדרות רוטשילד 11, תל אביב" מורכב מהרכיבים הבאים: "111" (מספר הרחוב), "8th Avenue" (השדרה 8) (המסלול), "תל אביב" (העיר) ו-"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
    }
}

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

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

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

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

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

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

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

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

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

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

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