בקשת 'חיפוש בקרבת מקום (חדש)' מקבלת כקלט את האזור לחיפוש שצוין כעיגול, ומוגדר לפי הקואורדינטות של קווי האורך והרוחב של נקודת המרכז של המעגל ושל הרדיוס במטרים. הבקשה תחזיר רשימה של מקומות תואמים, שכל אחד מהם מיוצג על ידי אובייקט GMSPlace
, באזור החיפוש שצוין.
כברירת מחדל, התשובה מכילה מקומות מכל הסוגים בתוך אזור החיפוש. אפשר גם לסנן את התשובה על ידי ציון רשימה של סוגי מקומות שייכללו בתגובה או יוחרגו ממנה. לדוגמה, אפשר לציין שהתשובה תכלול רק את המקומות מסוג 'מסעדה', 'מאפייה' ו'בית קפה', או להחריג את כל המקומות מסוג 'בית ספר'.
בקשות של חיפוש בקרבת מקום (חדש)
שולחים בקשת 'חיפוש בקרבת מקום' על ידי קריאה לפונקציה GMSPlacesClient searchNearbyWithRequest:
, העברת אובייקט GMSPlaceSearchNearbyRequest
שמגדיר את הפרמטרים של הבקשה ושיטת קריאה חוזרת מסוג GMSPlaceSearchNearbyResultCallback
לטיפול בתגובה.
האובייקט GMSPlaceSearchNearbyRequest
מציין את כל הפרמטרים החובה והפרמטרים אופציונליים של הבקשה. הפרמטרים הנדרשים הם:
- רשימת השדות שיש להחזיר באובייקט
GMSPlace
, שנקראת גם מסכת שדות, כפי שמוגדרת על ידיGMSPlaceProperty
. אם לא מציינים לפחות שדה אחד ברשימת השדות, או אם משמיטים את רשימת השדות, הקריאה תחזיר שגיאה. - הגבלת המיקום, כלומר המעגל שמגדיר את אזור החיפוש.
בדוגמה הזו של בקשת חיפוש בקרבת מקום, האובייקטים GMSPlace
מכילים את שם המקום (GMSPlacePropertyName
) והקואורדינטות (GMSPlacePropertyCoordinate
) של כל אובייקט GMSPlace
בתוצאות החיפוש. בנוסף, המערכת מסננת את התשובה כך שמוחזרות רק מקומות מסוג 'מסעדה' ו'בית קפה'.
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; } } ];
GooglePlacesSwift
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
בתשובה מכיל את הפונקציות הבאות לחברים:
-
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).