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

בחירת פלטפורמה: Android iOS JavaScript Web Service

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

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

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

בקשות של חיפוש בקרבת מקום (חדש)

כדי לשלוח בקשה לחיפוש בקרבת מקום, קוראים ל-GMSPlacesClient searchNearbyWithRequest: ומעבירים אובייקט GMSPlaceSearchNearbyRequest שמגדיר את פרמטרי הבקשה וכן שיטה לקריאה חוזרת (callback) מסוג GMSPlaceSearchNearbyResultCallback לטיפול בתגובה.

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

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

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

SwiftObjective-CPlaces Swift SDK ל-iOS (גרסת Preview)

// Array to hold the places in the response
var placeResults: [GMSPlace] = []

// Define the search area as a 500 meter diameter circle in San Francisco, CA.
let circularLocationRestriction = GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(37.7937, -122.3965), 500)

// Specify the fields to return in the GMSPlace object for each place in the response.
let placeProperties = [GMSPlaceProperty.name, GMSPlaceProperty.coordinate].map {$0.rawValue}

// Create the GMSPlaceSearchNearbyRequest, specifying the search area and GMSPlace fields to return.
var request = GMSPlaceSearchNearbyRequest(locationRestriction: circularLocationRestriction, placeProperties: placeProperties)
let includedTypes = ["restaurant", "cafe"]
request.includedTypes = includedTypes

let callback: GMSPlaceSearchNearbyResultCallback = { [weak self] results, error in
  guard let self, error == nil else {
    if let error {
      print(error.localizedDescription)
    }
    return
  }
  guard let results = results as? [GMSPlace] else {
    return
  }
  placeResults = results
}

GMSPlacesClient.shared().searchNearby(with: request, callback: callback)

// Array to hold the places in the response
_placeResults = [NSArray array];

// Define the search area as a 500 meter diameter circle in San Francisco, CA.
id<GMSPlaceLocationRestriction> circularLocation = GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(37.7937, -122.3965), 500);

// Create the GMSPlaceSearchNearbyRequest, specifying the search area and GMSPlace fields to return.
GMSPlaceSearchNearbyRequest *request = [[GMSPlaceSearchNearbyRequest alloc]
  initWithLocationRestriction:circularLocation
              placeProperties:@[ GMSPlacePropertyName, GMSPlacePropertyCoordinate ]];

// Set the place types to filter on.
NSArray<NSString *> *includedTypes = @[ @"restaurant", @"cafe" ];
request.includedTypes = [[NSMutableArray alloc] initWithArray:includedTypes];

[_placesClient searchNearbyWithRequest:request
  callback:^(NSArray<GMSPlace *> *_Nullable places, NSError *_Nullable error) {
    if (error != nil) {
      NSLog(@"An error occurred %@", [error localizedDescription]);
      return;
    } else {
        // Get list of places.
        _placeResults = places;
    }
  }
];

let restriction = CircularCoordinateRegion(center: CLLocationCoordinate2DMake(37.7937, -122.3965), radius: 500)
let searchNearbyRequest = SearchNearbyRequest(
  locationRestriction: restriction,
  placeProperties: [ .name, .coordinate],
  includedTypes: [ .restaurant, .cafe ],
)
switch await placesClient.searchNearby(with: searchNearbyRequest) {
case .success(let places):
  // Handle places
case .failure(let placesError):
  // Handle error
}

תשובות לחיפוש בקרבת מקום

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

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

אחזור הסטטוס 'פתוח'

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

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

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

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

כדי להשתמש בשיטה 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 מחויבים במסגרת מק"ט הנתונים הבסיסיים. שאר שעות הפתיחה יחויבו במסגרת מק"ט הפרטים של המקום ל-Enterprise.
• אם השדות האלה כבר קיימים באובייקט GMSPlace מבקשה קודמת, לא תחויבו שוב.
• אזהרה אם השדות האלה לא מופיעים באובייקט GMSPlace, תחויבו שוב על מק"ט הנתונים הבסיסיים. שאר שעות הפתיחה יחויבו במסגרת מק"ט הפרטים של המקום ל-Enterprise. אם בפרויקט שלכם נעשה שימוש ב-isOpenWithRequest, מומלץ לוודא שאתם מאחזרים את פרטי המיקום הנדרשים.

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

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

SwiftObjective-CGooglePlacesSwift

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

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

          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
          }
          

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

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

• רשימת שדות

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

  מציינים אחד או יותר מהשדות הבאים:

  • השדות הבאים מפעילים את מק"ט החיפוש בסביבה Pro:

    GMSPlacePropertyAddressComponents
GMSPlacePropertyBusinessStatus
GMSPlacePropertyCoordinate
GMSPlacePropertyFormattedAddress
GMSPlacePropertyName
GMSPlacePropertyIconBackgroundColor
GMSPlacePropertyIconImageURL
GMSPlacePropertyPhotos
GMSPlacePropertyPlaceID
GMSPlacePropertyPlusCode
GMSPlacePropertyTypes
GMSPlacePropertyUTCOffsetMinutes
GMSPlacePropertyViewport
GMSPlacePropertyWheelchairAccessibleEntrance

  • השדות הבאים מפעילים את מק"ט החיפוש בקרבת מקום לארגונים:

    GMSPlacePropertyCurrentOpeningHours
GMSPlacePropertySecondaryOpeningHours
GMSPlacePropertyPhoneNumber
GMSPlacePropertyPriceLevel
GMSPlacePropertyRating
GMSPlacePropertyOpeningHours
GMSPlacePropertyUserRatingsTotal
GMSPlacePropertyWebsite

  • השדות הבאים מפעילים את מק"ט החיפוש בסביבה ב-Enterprise Plus:

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

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

  SwiftObjective-CPlaces Swift SDK ל-iOS (גרסת Preview)
  // Specify the place data types to return.
  let fields: [GMSPlaceProperty] = [.placeID, .name]
          

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

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

• locationRestriction

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

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

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

• includedTypes/excludedTypes, ‏ includedPrimaryTypes/excludedPrimaryTypes

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

  הערה: הערכים בטבלה ב מוחזרים רק בתגובה. אי אפשר להשתמש בערכים בטבלה ב כמסנן.

  לכל מקום יכול להיות רק סוג ראשי אחד מהסוגים שמפורטים בטבלה א' שמשויכים אליו. לדוגמה, הסוג הראשי יכול להיות "mexican_restaurant" או "steak_house". אפשר להשתמש ב-includedPrimaryTypes וב-excludedPrimaryTypes כדי לסנן את התוצאות לפי הסוג הראשי של המקום.

  למקום יכולים להיות גם מספר ערכים של סוגים מהסוגים שמפורטים בטבלה א' שמשויכים אליו. לדוגמה, למסעדה יכולים להיות הסוגים הבאים: "seafood_restaurant", "restaurant", "food", "point_of_interest", "establishment". משתמשים במקשות includedTypes ו-excludedTypes כדי לסנן את התוצאות ברשימת הסוגים שמשויכים למיקום.

  כשמציינים סוג ראשי כללי, כמו "restaurant" או "hotel", התשובה יכולה לכלול מקומות עם סוג ראשי ספציפי יותר מהסוג שצוין. לדוגמה, אפשר לציין הכללה של סוג ראשי של "restaurant". לאחר מכן, התשובה יכולה לכלול מקומות עם סוג ראשי של "restaurant", אבל היא יכולה גם לכלול מקומות עם סוג ראשי ספציפי יותר, כמו "chinese_restaurant" או "seafood_restaurant".

  אם מציינים חיפוש עם כמה הגבלות סוג, יוחזרו רק מקומות שעומדים בכל ההגבלות. לדוגמה, אם מציינים את הערך {"includedTypes": ["restaurant"], "excludedPrimaryTypes": ["steak_house"]}, המקומות שחוזרים הם מקומות שמספקים שירותים שקשורים ל-"restaurant", אבל הם לא פועלים בעיקר בתור "steak_house".

  אם משמיטים את הערכים includedTypes, excludedTypes,‏ includedPrimaryTypes ו-excludedPrimaryTypes מהבקשה, החיפוש מחזיר מקומות מכל הסוגים בתוך גבולות הגבלת המיקום.

  includedTypes

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

  excludedTypes

  רשימה של סוגי מקומות מטבלה א' שרוצים להחריג מחיפוש.

  אם מציינים בבקשה גם את הערך של includedTypes (למשל "school") וגם את הערך של excludedTypes (למשל "primary_school"), התשובה תכלול מקומות שסווגו כ-"school" אבל לא כ-"primary_school". התשובה כוללת מקומות שתואמים לפחות לאחד מה-includedTypes ולאף אחד מה-excludedTypes.

  אם יש סוגי נתונים מתנגשים, למשל סוג שמופיע גם ב-includedTypes וגם ב-excludedTypes, תוחזר שגיאת INVALID_REQUEST.

  includedPrimaryTypes

  רשימה של סוגי המקומות הראשיים מטבלה א' שרוצים לכלול בחיפוש.

  excludedPrimaryTypes

  רשימה של סוגי המקומות הראשיים מטבלה א' שרוצים להחריג מהחיפוש.

  אם יש סוגים ראשיים סותרים, למשל סוג שמופיע גם ב-includedPrimaryTypes וגם ב-excludedPrimaryTypes, תוחזר שגיאה מסוג INVALID_ARGUMENT.

• maxResultCount

  מציין את המספר המקסימלי של תוצאות של מקומות שאפשר להציג. הערך חייב להיות בין 1 ל-20 (ברירת המחדל), כולל.

• rankPreference

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

  • .popularity (ברירת מחדל) מיון התוצאות לפי הפופולריות שלהן.
  • .distance מיון התוצאות בסדר עולה לפי המרחק שלהן מהמיקום שצוין.

• regionCode

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

  אם שם המדינה בשדה formattedAddress בתגובה תואם ל-regionCode, קידומת המדינה לא תופיע ב-formattedAddress. הפרמטר הזה לא משפיע על adrFormatAddress, שתמיד כולל את שם המדינה, או על shortFormattedAddress, שמעולם לא כולל אותו.

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

הצגת שיוך באפליקציה

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

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

למידע נוסף, קראו את המאמר שיוך.