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

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

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

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

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

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

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

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

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

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

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

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

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
}

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

Nearby Search API מחזיר מערך של התאמות בצורת 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
          }
          

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

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

• רשימת שדות

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

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

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

    GMSPlacePropertyAddressComponents, GMSPlacePropertyBusinessStatus, GMSPlacePropertyCoordinate, GMSPlacePropertyFormattedAddress, GMSPlacePropertyName, GMSPlacePropertyIconBackgroundColor, GMSPlacePropertyIconImageURL, GMSPlacePropertyPhotos, GMSPlacePropertyPlaceID, GMSPlacePropertyPlusCode, GMSPlacePropertyTypes, GMSPlacePropertyUTCOffsetMinutes, GMSPlacePropertyViewport, 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]
          

• locationRestriction

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

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

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

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

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

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

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

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