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

בחירת פלטפורמה: Android iOS JavaScript Web Service
מפתחים באזור הכלכלי האירופי (EEA)

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

כברירת מחדל, התגובה מכילה מקומות מכל הסוגים באזור החיפוש. אפשר גם לסנן את התשובה על ידי ציון רשימה של סוגי מקומות שרוצים לכלול בתשובה או להחריג ממנה. לדוגמה, אפשר לציין שבתגובה ייכללו רק מקומות מסוג restaurant (מסעדה), bakery (מאפייה) ו-cafe (בית קפה), או להחריג את כל המקומות מסוג school (בית ספר).

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

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

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

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

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

Places Swift SDK

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
}

Swift

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

Objective-C

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

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

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

איך בודקים אם העסק פתוח

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

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

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

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

  • GMSPlacePropertyUTCOffsetMinutes
  • GMSPlacePropertyBusinessStatus
  • GMSPlacePropertyOpeningHours
  • GMSPlacePropertyCurrentOpeningHours
  • GMSPlacePropertySecondaryOpeningHours

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

תגובה אחת (isOpenWithRequest)

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

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

חיוב על isOpenWithRequest

  • החיוב על השדות GMSPlacePropertyUTCOffsetMinutes ו-GMSPlacePropertyBusinessStatus מתבצע במסגרת מק"ט נתונים בסיסי. שאר שעות הפתיחה מחויבות במסגרת מק"ט Place Details Enterprise.
  • אם לאובייקט GMSPlace כבר יש את השדות האלה מבקשה קודמת, לא תחויבו שוב.

דוגמה: יצירת בקשת GMSPlaceIsOpenWithRequest

בדוגמה הבאה מוצג אופן ההגדרה של GMSPlaceIsOpenWithRequest בתוך אובייקט GMSPlace קיים.

Places Swift SDK

        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
        }

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

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

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

  • רשימת השדות

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

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

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

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

    • השדות הבאים מפעילים את מק"ט Nearby Search Enterprise:

      GMSPlacePropertyCurrentOpeningHours
      GMSPlacePropertySecondaryOpeningHours
      GMSPlacePropertyPhoneNumber
      GMSPlacePropertyPriceLevel
      GMSPlacePropertyRating
      GMSPlacePropertyOpeningHours
      GMSPlacePropertyUserRatingsTotal
      GMSPlacePropertyWebsite

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

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

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

    Places Swift SDK

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

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

  • locationRestriction

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

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

    אם מציינים בבקשה גם את 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, עם כמה יוצאים מן הכלל. לדוגמה, ה-ccTLD של בריטניה הוא uk (‎.co.uk), אבל קוד ISO 3166-1 שלה הוא gb (טכנית, עבור הישות 'ממלכת בריטניה הגדולה וצפון אירלנד'). הפרמטר יכול להשפיע על התוצאות בהתאם לדין החל.

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

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

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

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