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

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

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

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

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

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

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

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

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

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

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

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

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

משתמשים באובייקט 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];
          

  GooglePlacesSwift

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

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

  אם מציינים גם את 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.

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