פרטי מקום (חדש)

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

כדי להשתמש בתכונה הזו, צריך להפעיל את Places API (חדש), הדור הבא של Places API. מידע נוסף זמין במאמר הבא: הפעלת ממשקי API.

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

קבלת פרטים על מקום

GMSPlace הכיתה מכילה מידע על מקום ספציפי, כולל כל שדות הנתונים שמוצגים שדות של נתוני מקום (חדש). לקבלת GMSPlace של אובייקט באמצעות קריאה לאובייקט GMSPlacesClient fetchPlaceWithRequest:, העברת אובייקט GMSFetchPlaceRequest ו שיטת קריאה חוזרת (callback) מסוג GMSPlaceResultCallback.

האובייקט GMSFetchPlaceRequest מציין:

• (חובה) מזהה המקום, מזהה ייחודי של מקום ב'מקומות Google'. במסד הנתונים ובמפות Google.
• (חובה) רשימת השדות שצריך להחזיר באובייקט GMSPlace, שנקראת גם field mask, כפי שמוגדר על ידי GMSPlaceProperty אם לא מציינים שדה אחד לפחות ברשימת השדות, או אם משמיטים שדה. ברשימת השדות, ואז הקריאה מחזירה שגיאה.
• (אופציונלי) קוד האזור שמשמש לעיצוב התשובה.
• (אופציונלי) אסימון הסשן שמשמש לסיום סשן של השלמה אוטומטית (חדש).

יש להגיש בקשה לפרטי מקום

בדוגמה הזו מוצג מקום לפי מזהה ומעבירים את הפרמטרים הבאים:

• מזהה המקום של ChIJV4k8_9UodTERU5KXbkYpSYs.
• רשימת שדות שמציינת להחזיר את שם המקום וכתובת האתר.
• GMSPlaceResultCallback כדי לטפל בתוצאה.

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

Swift

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

// Specify the place data types to return.
let myProperties = [GMSPlaceProperty.name, GMSPlaceProperty.website].map {$0.rawValue}

// Create the GMSFetchPlaceRequest object.
let fetchPlaceRequest = GMSFetchPlaceRequest(placeID: placeID, placeProperties: myProperties, sessionToken: nil)

client.fetchPlace(with: fetchPlaceRequest, callback: {
  (place: GMSPlace?, error: Error?) in
  guard let place, error == nil else { return }
  print("Place found: \(String(describing: place.name))")
})

Objective-C

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

// Specify the place data types to return.
NSArray<NSString *> *myProperties = @[GMSPlacePropertyName, GMSPlacePropertyWebsite];

// Create the GMSFetchPlaceRequest object.
GMSFetchPlaceRequest *fetchPlaceRequest = [[GMSFetchPlaceRequest alloc] initWithPlaceID:placeID placeProperties: myProperties sessionToken:nil];

[placesClient fetchPlaceWithRequest: fetchPlaceRequest callback: ^(GMSPlace *_Nullable place, NSError *_Nullable error) {
    if (error != nil) {
      NSLog(@"An error occurred %@", [error localizedDescription]);
      return;
    } else {
    NSLog(@"Place Found: %@", place.name);
    NSLog(@"The place URL: %@", place.website);
  }
}];

Places Swift SDK ל-iOS (תצוגה מקדימה)

// A hotel in Saigon with an attribution.
let placeID = "ChIJV4k8_9UodTERU5KXbkYpSYs"
let fetchPlaceRequest = FetchPlaceRequest(
  placeID: placeID,
  placeProperties: [.name, .website]
)
switch await placesClient.fetchPlace(with: fetchPlaceRequest) {
case .success(let place):
  // Handle place
case .failure(let placesError):
  // Handle error
}

תשובה עם פרטי מקום

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

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

קבלת סטטוס פתיחה

האובייקט GMSPlacesClient מכיל פונקציה חבר בשם isOpenWithRequest (isOpenRequest ב-Swift ו-isPlaceOpenRequest ב-GooglePlacesSwift) שמחזירה תשובה שמציינת אם המקום פתוח כרגע, לפי השעה שצוינה בשיחה.

הערה: ייתכן שהפונקציות GMSPlace isOpen: ו-GMSPlace isOpenAtDate: שהוצאו משימוש עשויות להיות לא מדויקות ולא מתאימות לשימוש עם Places API (חדש).

השיטה הזו לוקחת ארגומנט יחיד מסוג GMSPlaceIsOpenWithRequest שמכיל:

• אובייקט GMSPlace, או מחרוזת שמציינת מזהה מקום. למידע נוסף על יצירת אובייקט Place עם השדות הנדרשים, ראו פרטי מקום.
  
  הערה: האובייקט Place חייב להכיל מזהה מקום תקין.
• אובייקט אופציונלי NSDate (Obj-C) או Date (Swift) שמציין את השעה שרוצים לבדוק. אם לא צוין זמן, ברירת המחדל היא עכשיו.
• שיטת GMSPlaceOpenStatusResponseCallback לטיפול בתשובה.
>

באמצעות ה-method GMSPlaceIsOpenWithRequest צריך להגדיר את השדות הבאים באובייקט GMSPlace:

• GMSPlacePropertyUTCOffsetMinutes
• GMSPlacePropertyBusinessStatus
• GMSPlacePropertyOpeningHours
• GMSPlacePropertyCurrentOpeningHours
• GMSPlacePropertySecondaryOpeningHours

אם לא ציינתם את השדות האלה באובייקט Place, או אם אתם מעבירים מזהה מקום, השיטה תשתמש ב-GMSPlacesClient GMSFetchPlaceRequest: כדי לאחזר אותם.

תגובה אחת (isOpenWithRequest)

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

שפה	ערך אם פתוח	הערך אם הוא סגור	ערך אם הסטטוס לא ידוע
Swift	.open	.closed	.unknown
Objective-C	GMSPlaceOpenStatusOpen	GMSPlaceOpenStatusClosed	GMSPlaceOpenStatusUnknown
GooglePlacesSwift (תצוגה מקדימה)	true	false	nil

חיוב עבור isOpenWithRequest

• השדות GMSPlacePropertyUTCOffsetMinutes ו-GMSPlacePropertyBusinessStatus מחויבים במסגרת מק"ט נתונים בסיסי. החיוב על שאר שעות הפעילות מתבצע בקטע מק"ט של פרטי מקום (מתקדם).
• אם האובייקט GMSPlace כבר כולל את השדות האלה מבקשה קודמת, לא תחויבו שוב.
• אזהרה אם האובייקט GMSPlace לא כולל את השדות האלה, תחויבו שוב על מק"ט הנתונים הבסיסי. החיוב על שאר שעות הפעילות מתבצע בקטע מק"ט של פרטי מקום (מתקדם). אם בפרויקט שלך ייעשה שימוש ב-isOpenWithRequest, מומלץ לאחזר את פרטי המקום הנדרשים.

דוגמה: שליחת בקשה של GMSPlaceIsOpenWithRequest

הדוגמה הבאה מראה איך לאתחל GMSPlaceIsOpenWithRequest בתוך אובייקט GMSPlace קיים.

Swift

    let isOpenRequest = GMSPlaceIsOpenRequest(place: place, date: nil)
      GMSPlacesClient.shared().isOpen(with: isOpenRequest) { response, error in
        if let error = error {
          // Handle Error
        }
        switch response.status {
          case .open:
            // Handle open
          case .closed:
            // Handle closed
          case .unknown:
            // Handle unknown
        }
      }
        

Objective-C

          GMSPlaceIsOpenRequest *isOpenRequest = [[GMSPlaceIsOpenRequest alloc] initWithPlace:place date:nil];
  
          [[GMSPlacesClient sharedClient] isOpenWithRequest:isOpenRequest callback:^(GMSPlaceIsOpenResponse response, NSError *_Nullable error) {
            if (error) {
              // Handle error
            }
  
            switch (response.status) {
              case GMSPlaceOpenStatusOpen:
                // Handle open
              case GMSPlaceOpenStatusClosed:
                // Handle closed
              case GMSPlaceOpenStatusUnknown:
                // Handle unknown
            }
          }];
          

GooglePlacesSwift

          let isOpenRequest = IsPlaceOpenRequest(place: place)
          switch await placesClient.isPlaceOpen(with: isOpenRequest) {
            case .success(let isOpenResponse):
              switch isOpenResponse.status {
                case true:
                  // Handle open
                case false:
                  // Handle closed
                case nil:
                  // Handle unknown
            case .failure(let placesError):
              // Handle error
          }
          

פרמטרים נדרשים

משתמשים באובייקט GMSFetchPlaceRequest כדי לציין את הפרמטרים הנדרשים.

מזהה מקום

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

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

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

רשימת שדות

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

צריך לציין אחד או יותר מהשדות הבאים:

• השדות הבאים מפעילים את המק"ט של פרטי המקום (מזהה בלבד):

  GMSPlacePropertyPlaceID, GMSPlacePropertyName, GMSPlacePropertyPhotos

• השדות הבאים מפעילים את המק"ט של פרטי המקום (מיקום בלבד):

  GMSPlacePropertyAddressComponents, GMSPlacePropertyFormattedAddress, GMSPlacePropertyCoordinate, GMSPlacePropertyPlusCode, GMSPlacePropertyTypes, GMSPlacePropertyViewport

• השדות הבאים מפעילים את המק"ט של פרטי המקום (בסיסי):

  GMSPlacePropertyBusinessStatus, GMSPlacePropertyIconBackgroundColor, GMSPlacePropertyIconImageURL, GMSPlacePropertyUTCOffsetMinutes, GMSPlacePropertyWheelchairAccessibleEntrance

• השדות הבאים מפעילים את המק"ט של פרטי המקום (מתקדם):

  GMSPlacePropertyCurrentOpeningHours, GMSPlacePropertySecondaryOpeningHours, GMSPlacePropertyPhoneNumber, GMSPlacePropertyPriceLevel, GMSPlacePropertyRating, GMSPlacePropertyOpeningHours, GMSPlacePropertyUserRatingsTotal, GMSPlacePropertyWebsite

• השדות הבאים מפעילים את המק"ט של פרטי המקום (מועדף):

  GMSPlacePropertyCurbsidePickup, GMSPlacePropertyDelivery, GMSPlacePropertyDineIn, GMSPlacePropertyEditorialSummary, GMSPlacePropertyReservable, GMSPlacePropertyReviews, GMSPlacePropertyServesBeer, GMSPlacePropertyServesBreakfast, GMSPlacePropertyServesBrunch, GMSPlacePropertyServesDinner, GMSPlacePropertyServesLunch, GMSPlacePropertyServesVegetarianFood, GMSPlacePropertyServesWine, GMSPlacePropertyTakeout

הדוגמה הבאה מעבירה רשימה של ערכי שדות כדי לציין שהאובייקט GMSPlace שהוחזר על ידי בקשה מכיל את הפונקציה השדות name ו-placeID:

Swift

// Specify the place data types to return.
let fields: [GMSPlaceProperty] = [.placeID, .name]
  

Objective-C

// Specify the place data types to return.
NSArray<GMSPlaceProperty *> *fields = @[GMSPlacePropertyPlaceID, GMSPlacePropertyName];
  

Places Swift SDK ל-iOS (תצוגה מקדימה)

// Specify the place data types to return.
let fields: [PlaceProperty] = [.placeID, .displayName]
    

פרמטרים אופציונליים

משתמשים באובייקט GMSFetchPlaceRequest כדי לציין את הפרמטרים האופציונליים.

regionCode

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

אם שם המדינה בשדה הכתובת בתשובה תואם את קידומת החיוג האזורית, קוד המדינה יושמט מהכתובת.

רוב קודי ה-CLDR זהים לקודי ISO 3166-1. עם כמה יוצאים מן הכלל. לדוגמה, ה-ccTLD של בריטניה הוא "uk" (.co.uk) כשקוד ISO 3166-1 הוא "gb" (טכנית עבור ישות "בריטניה וצפון אירלנד"). הפרמטר יכול להשפיע על התוצאות בהתאם לחוק הרלוונטי.

sessionToken

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

הצגת ייחוס באפליקציה

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

לדוגמה, המאפיין reviews של האובייקט GMSPlacesClient מכיל מערך של עד חמש GMSPlaceReview אובייקטים. כל אובייקט GMSPlaceReview יכול להכיל ייחוס וייחוס של מחברים. אם הביקורת מוצגת באפליקציה, צריך לציין גם ייחוס או מחבר Attribution.

למידע נוסף, עיינו במשאבי העזרה בנושא שיוכים.