בבקשת 'חיפוש בקרבת מקום' (חדש) מזינים את האזור לחיפוש שצוין כעיגול, מוגדר לפי הקואורדינטות של קו הרוחב וקו האורך של נקודת המרכז של העיגול והרדיוס במטרים. הבקשה מחזירה רשימה של מקומות תואמים, שכל אחד מהם מיוצג על ידי אובייקט Place
, בתוך אזור החיפוש שצוין.
כברירת מחדל, התגובה מכילה מקומות מכל הסוגים באזור החיפוש. אם רוצים, אפשר לסנן את התשובה על ידי ציון רשימה של סוגי מקומות שרוצים לכלול בתשובה או להחריג ממנה במפורש. לדוגמה, תוכלו לציין בתשובה רק את המקומות מסוג 'מסעדה', 'מאפייה' ו'בית קפה', או להחריג את כל המקומות מסוג 'בית ספר'.
בקשות של חיפוש בקרבת מקום (חדש)
יוצרים בקשת חיפוש בקרבת מקום (חדש) באמצעות קריאה ל-PlacesClient.searchNearby
, העברת אובייקט SearchNearbyRequest
שמגדיר את הפרמטרים של הבקשה.
האובייקט SearchNearbyRequest
מציין את כל הפרמטרים הנדרשים והאופציונליים של הבקשה. הפרמטרים הנדרשים הם:
- רשימת השדות שצריך להחזיר באובייקט
Place
, שנקראת גם 'אנונימיזציה של שדות'. אם לא תציינו לפחות שדה אחד ברשימת השדות, או אם משמיטים את רשימת השדות, הקריאה תחזיר שגיאה. - הגבלת המיקום של אזור החיפוש, מוגדרת כצמד של קווי רוחב/אורך וכערך רדיוס, במטרים.
הדוגמה הזו של בקשת החיפוש בקרבת מקום מציינת שהאובייקטים של התגובה Place
מכילים את שדות המקום Place.Field.ID
ו-Place.Field.NAME
לכל אובייקט Place
בתוצאות החיפוש. הוא גם מסנן את התשובה כדי להציג רק מקומות מסוג 'מסעדה' ו'בית קפה', אבל לא כולל מקומות מסוג 'פיצה_מסעדה' ו-'american_restaurant'.
// Define a list of fields to include in the response for each returned place. final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.NAME); // Define the search area as a 1000 meter diameter circle in New York, NY. LatLng center = new LatLng(40.7580, -73.9855); CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 1000); // Define a list of types to include. final List<String> includedTypes = Arrays.asList("restaurant", "cafe"); // Define a list of types to exclude. final List<String> excludedTypes = Arrays.asList("pizza_restaurant", "american_restaurant"); // Use the builder to create a SearchNearbyRequest object. final SearchNearbyRequest searchNearbyRequest = SearchNearbyRequest.builder(/* location restriction = */ circle, placeFields) .setIncludedTypes(includedTypes) .setExcludedTypes(excludedTypes) .setMaxResultCount(10) .build()); // Call placesClient.searchNearby() to perform the search. // Define a response handler to process the returned List of Place objects. placesClient.searchNearby(searchNearbyRequest) .addOnSuccessListener(response -> { List<Place> places = response.getPlaces(); });
תגובות של חיפוש בקרבת מקום (חדש)
המחלקה SearchNearbyResponse
מייצגת את התגובה לבקשת חיפוש. אובייקט SearchNearbyResponse
מכיל:
- רשימה של
Place
אובייקטים שמייצגים את כל המקומות התואמים, עם אובייקטPlace
אחד לכל מקום תואם. - כל אובייקט
Place
מכיל רק את השדות שמוגדרים ברשימת השדות שמועברת בבקשה.
לדוגמה, בבקשה הגדרתם רשימת שדות כך:
// Define a list of fields to include in the response for each returned place. final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.NAME);
המשמעות של רשימת השדות הזו היא שכל אובייקט Place
בתשובה מכיל רק את מזהה המקום והשם של כל מקום תואם. לאחר מכן אפשר להשתמש ב-methods Place.getId()
ו-Place.getName()
כדי לגשת לשדות האלה בכל אובייקט Place
.
לדוגמאות נוספות של גישה לנתונים באובייקט Place
, ראו גישה לשדות של נתוני אובייקט של Place.
פרמטרים נדרשים
משתמשים באובייקט SearchNearbyRequest
כדי לציין את הפרמטרים הנדרשים לחיפוש.
רשימת שדות
כשמבקשים פרטי מקום, צריך לציין את הנתונים שיוחזרו באובייקט
Place
של המקום בתור מסיכת שדות. כדי להגדיר את מסכת השדות, מעבירים מערך של ערכים מ-Place.Field
לאובייקטSearchNearbyRequest
. כדאי לבצע אנונימיזציה של שדות כדי לוודא שלא מבקשים נתונים מיותרים, וכך חוסכים זמן עיבוד וחיובים מיותרים.צריך לציין אחד או יותר מהשדות הבאים:
השדות הבאים מפעילים את Nearby Search (בסיסי):
Place.Field.ADDRESS_COMPONENTS
,Place.Field.BUSINESS_STATUS
,Place.Field.ADDRESS
,Place.Field.ICON_BACKGROUND_COLOR
,Place.Field.ICON_URL
,Place.Field.LAT_LNG
,Place.Field.PHOTO_METADATAS
,Place.Field.PLUS_CODE
,Place.Field.ID
,Place.Field.NAME
,Place.Field.TYPES
,Place.Field.UTC_OFFSET
,Place.Field.VIEWPORT
,Place.Field.WHEELCHAIR_ACCESSIBLE_ENTRANCE
השדות הבאים מפעילים את Nearby Search (Advanced) SKU:
Place.Field.CURRENT_OPENING_HOURS
,Place.Field.SECONDARY_OPENING_HOURS
,Place.Field.PHONE_NUMBER
,Place.Field.PRICE_LEVEL
,Place.Field.RATING
,Place.Field.OPENING_HOURS
,Place.Field.USER_RATINGS_TOTAL
,Place.Field.WEBSITE_URI
השדות הבאים מפעילים את Nearby Search (Preferred):
Place.Field.CURBSIDE_PICKUP
,Place.Field.DELIVERY
,Place.Field.DINE_IN
,Place.Field.EDITORIAL_SUMMARY
,Place.Field.RESERVABLE
,Place.Field.REVIEWS
,Place.Field.SERVES_BEER
,Place.Field.SERVES_BREAKFAST
,Place.Field.SERVES_BRUNCH
,Place.Field.SERVES_DINNER
,Place.Field.SERVES_LUNCH
,Place.Field.SERVES_VEGETARIAN_FOOD
,Place.Field.SERVES_WINE
,Place.Field.TAKEOUT
כדי להגדיר את הפרמטר של רשימת השדות, קוראים ל-method
setPlaceFields()
כשמפתחים את האובייקטSearchNearbyRequest
.בדוגמה הבאה מוגדרת רשימה של שני ערכי שדות כדי לציין שהאובייקט
Place
שהוחזר בעקבות בקשה מכיל את השדותPlace.Field.ID
ו-Place.Field.NAME
:
// Define a list of fields to include in the response for each returned place. final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.NAME);
הגבלת מיקום
אובייקט
LocationRestriction
שמגדיר את האזור לחיפוש שצוין כעיגול, שמוגדר לפי נקודת מרכז ורדיוס במטרים. הרדיוס צריך להיות בין גדול מ-0.0 ל-50000.0 או קטן ממנו. חשוב לזכור שציון רדיוס קטן מדי יחזיר את התשובהZERO_RESULTS
.כדי להגדיר את הפרמטר של הגבלת המיקום, כשמפתחים את האובייקט
SearchNearbyRequest
, קוראים ל-methodsetLocationRestriction()
.
פרמטרים אופציונליים
אפשר להשתמש באובייקט SearchNearbyRequest
כדי לציין את הפרמטרים האופציונליים לחיפוש.
-
סוגים וסוגים ראשיים
מאפשרת לציין רשימת סוגים של סוגי טבלה א' שמשמשים לסינון תוצאות החיפוש. אפשר לציין עד 50 סוגים בכל קטגוריה של הגבלת סוג.
למקום אפשר לשייך רק סוג ראשי יחיד מהסוגים טבלה א'. לדוגמה, הסוג הראשי יכול להיות
"mexican_restaurant"
או"steak_house"
. אפשר להשתמש ב-includedPrimaryTypes
וב-excludedPrimaryTypes
כדי לסנן את התוצאות לפי הסוג הראשי של מקום.למקום יכולים להיות גם כמה ערכים של סוגים מהסוגים טבלה א' שמשויכים אליו. לדוגמה, מסעדות יכולות להיות מהסוגים הבאים:
"seafood_restaurant"
,"restaurant"
,"food"
,"point_of_interest"
,"establishment"
. אפשר להשתמש ב-includedTypes
וב-excludedTypes
כדי לסנן את התוצאות ברשימת הסוגים שמשויכים למקום.אם חיפוש מוגדר עם כמה הגבלות סוגים, יוחזרו רק מקומות שעומדים בכל ההגבלות. לדוגמה, אם מציינים את
includedTypes = Arrays.asList("restaurant")
ואתexcludedPrimaryTypes = Arrays.asList("steak_house")
, המקומות המוחזרים מספקים שירותים שקשורים ל-"restaurant"
אבל לא פועלים בעיקר כ"steak_house"
.דוגמה לאופן השימוש ב-
includedTypes
וב-excludedTypes
מופיעה במאמר בקשות חיפוש בקרבת מקום (חדש).הסוגים הכלולים
רשימה של סוגי המקומות מטבלה א לחיפוש. אם משמיטים את הפרמטר הזה, מוחזרים מקומות מכל הסוגים.
כדי להגדיר את הפרמטר של הסוגים הכלולים, צריך להפעיל את השיטה
setIncludedTypes()
כשיוצרים את האובייקטSearchNearbyRequest
.סוגים מוחרגים
רשימה של סוגי מקומות מטבלה א' להחרגה מהחיפוש.
אם מציינים בבקשה גם את
includedTypes
(כמו"school"
) וגם אתexcludedTypes
(למשל"primary_school"
), התשובה תכלול מקומות שמסווגים בתור"school"
אבל לא בתור"primary_school"
. התגובה כוללת מקומות שתואמים ללפחות אחד מתוךincludedTypes
ואף אחד מ-excludedTypes
.אם יש סוגים מתנגשים, כמו סוג שמופיע גם ב-
includedTypes
וגם ב-excludedTypes
, תוחזר שגיאתINVALID_REQUEST
.כדי להגדיר את הפרמטר של הסוגים המוחרגים, צריך להפעיל את השיטה
setExcludedTypes()
כשיוצרים את האובייקטSearchNearbyRequest
.הסוגים הראשיים הכלולים
רשימה של סוגים ראשיים של מקומות מטבלה א' שאפשר לכלול בחיפוש.
כדי להגדיר את הפרמטר של הסוגים הראשיים שכלול, צריך להפעיל את השיטה
setIncludedPrimaryTypes()
כשיוצרים את האובייקטSearchNearbyRequest
.סוגים ראשיים שלא נכללים
רשימה של סוגים ראשיים של מקומות מטבלה א שצריך להחריג מחיפוש.
אם יש סוגים ראשיים מתנגשים, כמו סוג שמופיע גם ב-
includedPrimaryTypes
וגם ב-excludedPrimaryTypes
, תוחזר שגיאתINVALID_ARGUMENT
.כדי להגדיר את הפרמטר של הסוגים הראשיים שלא נכללים, צריך להפעיל את השיטה
setExcludedPrimaryTypes()
כשיוצרים את האובייקטSearchNearbyRequest
. -
מספר התוצאות המקסימלי
מציין את המספר המקסימלי של תוצאות של מקומות שצריך להחזיר. חייב להיות בין 1 ל-20 (ברירת מחדל) כולל.
כדי להגדיר את הפרמטר של מספר התוצאות המקסימלי, צריך להפעיל את השיטה
setMaxResultCount()
כשיוצרים את האובייקטSearchNearbyRequest
. -
העדפת דירוג
סוג הדירוג שבו יש להשתמש. אם משמיטים את הפרמטר הזה, התוצאות מדורגות לפי הפופולריות. יכול להיות אחת מהאפשרויות הבאות:
POPULARITY
(ברירת מחדל) מיון התוצאות לפי הפופולריות שלהן.DISTANCE
מיון התוצאות בסדר עולה לפי המרחק שלהן מהמיקום שצוין.
כדי להגדיר את הפרמטר של העדפת הדירוג, מפעילים את השיטה
setRankPreference()
כשמפתחים את האובייקטSearchNearbyRequest
. -
קוד אזור
קוד האזור שמשמש לעיצוב התשובה, מוגדר כערך של קוד CLDR בן שני תווים. אין ערך ברירת מחדל.
אם שם המדינה בשדה
formattedAddress
בתשובה תואם ל-regionCode
, קוד המדינה לא יופיע ב-formattedAddress
.רוב קודי ה-CLDR זהים לקודי ISO 3166-1, עם כמה יוצאים מן הכלל. לדוגמה, הדומיין ccTLD של בריטניה הוא 'uk' (.co.uk) ואילו קוד ISO 3166-1 הוא 'gb' (טכנית לישות 'בריטניה וצפון אירלנד'). הפרמטר יכול להשפיע על התוצאות בהתאם לחוק הרלוונטי.
כדי להגדיר את הפרמטר של קוד האזור, צריך להפעיל את השיטה
setRegionCode()
כשמפתחים את האובייקטSearchNearbyRequest
.
הצגת ייחוס באפליקציה
כשמוצג באפליקציה מידע שהתקבל מ-PlacesClient
, כמו תמונות וביקורות, האפליקציה צריכה להציג גם את המאפיינים הנדרשים.
מידע נוסף זמין במאמר מדיניות לגבי Places SDK ל-Android.