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

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

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

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

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

שולחים בקשה לחיפוש בקרבת מקום באמצעות הקריאה GMSPlacesClient searchNearbyWithRequest:, ומעבירים אובייקט GMSPlaceSearchNearbyRequest שמגדיר את פרמטרים של הבקשה ושיטת קריאה חוזרת, מהסוג 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

אם השדות האלה לא מופיעים באובייקט Place, או אם מעבירים מזהה של מקום, השיטה משתמשת ב-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 יכול להכיל שיוכים ושיוכים של מחברים. אם אתם מציגים את הביקורת באפליקציה, אתם צריכים להציג גם את השיוך או את שיוך המחבר.

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