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

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

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

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

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

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

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

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

// 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 כדי לציין את הפרמטרים האופציונליים עבור החיפוש.

• includedTypes/excludedTypes, includedPrimaryTypes/excludedPrimaryTypes

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

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

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

  אם חיפוש מסוים מצוין עם כמה סוגים של הגבלות, יוחזרו רק מקומות שעומדים בכל ההגבלות. לדוגמה, אם מציינים את {"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 יכול להכיל ייחוסs ושמות של מחברים. אם הביקורת שלך מוצגת באפליקציה, עליך להציג גם ייחוס או ייחוס למחבר.

למידע נוסף, עיינו במסמכי התיעוד בנושא שיוך (Attribution).