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

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

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

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

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

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

  • (חובה) מזהה המקום, מזהה ייחודי של מקום במסד הנתונים של מקומות Google ובמפות Google.
  • (חובה) רשימת השדות שיש להחזיר באובייקט GMSPlace, שנקראת גם מסכת שדות, כפי שהוגדרה על ידי 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);
  }
}];

GooglePlacesSwift

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

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

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

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

  • isOpen מחשבת אם מקום מסוים פתוח בשעה הנתונה.
  • isOpenAtDate מחשבת אם מקום מסוים פתוח בתאריך מסוים.

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

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

מזהה מקום

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

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

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

רשימת שדות

כשמבקשים פרטי מקום, צריך לציין את הנתונים שיוחזרו באובייקט 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];

GooglePlacesSwift

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

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

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

regionCode

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

אם שם המדינה בשדה הכתובת בתשובה תואם לקוד האזור, קוד המדינה לא יופיע בכתובת.

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

sessionToken

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

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

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

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

למידע נוסף, עיינו במסמכי התיעוד בנושא שיוך (Attribution).