בקשה לחיפוש בקרבת מקום (חדשה) מקבלת כקלט את האזור לחיפוש שצוין כעיגול, שמוגדר לפי קואורדינטות קו הרוחב וקו האורך של נקודת המרכז של העיגול והרדיוס במטרים. הבקשה מחזירה רשימה של מקומות תואמים, שכל אחד מהם מיוצג באובייקט Place, בתוך אזור החיפוש שצוין.
כברירת מחדל, התגובה מכילה מקומות מכל הסוגים שנמצאים באזור החיפוש. אפשר גם לסנן את התשובה על ידי ציון רשימה של סוגי המקומות שרוצים לכלול או להחריג באופן מפורש מהתגובה. לדוגמה, אפשר לציין בתגובה שרוצים לכלול רק מקומות מסוג 'מסעדה', 'מאפייה' ו'בית קפה', או להחריג את כל המקומות מסוג 'בית ספר'.
בקשות של חיפוש בקרבת מקום (חדש)
כדי לשלוח בקשה מסוג 'חיפוש בקרבת מקום (חדש)', קוראים ל-PlacesClient.searchNearby ומעבירים אובייקט SearchNearbyRequest שמגדיר את פרמטרים הבקשה.
האובייקט SearchNearbyRequest מציין את כל הפרמטרים הנדרשים והאופציונליים של הבקשה. הפרמטרים הנדרשים כוללים:
- רשימת השדות להחזרה באובייקט
Place, שנקראת גם מסכת שדות. אם לא מציינים לפחות שדה אחד ברשימת השדות, או אם משמיטים את רשימת השדות, הקריאה מחזירה שגיאה. - הגבלת המיקום של אזור החיפוש, מוגדרת כצמד קו אורך/רוחב וערך רדיוס, במטרים.
בדוגמה הזו של בקשת חיפוש בקרבת מקום מצוין שאובייקטי התגובה מסוג Place מכילים את שדות המיקום Place.Field.ID ו-Place.Field.DISPLAY_NAME לכל אובייקט 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.DISPLAY_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 זמינות במאמר גישה לשדות הנתונים של אובייקט מקום.
פרמטרים נדרשים
משתמשים באובייקט SearchNearbyRequest כדי לציין את הפרמטרים הנדרשים לחיפוש.
רשימת שדות
כשמבקשים פרטים על מקום, צריך לציין את הנתונים להחזרה באובייקט
Placeשל המקום כמסכת שדה. כדי להגדיר את מסכת השדה, מעבירים מערך ערכים מ-Place.FieldלאובייקטSearchNearbyRequest. אנו ממליצים להשתמש בהסתרת שדות כדי לוודא שאתם לא מבקשים נתונים מיותרים, וכך להימנע מזמן עיבוד ומחיובים מיותרים.מציינים אחד או יותר מהשדות הבאים:
השדות הבאים מפעילים את מק"ט החיפוש בקרבת מקום (בסיסי):
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.PRIMARY_TYPE,Place.Field.PRIMARY_TYPE_DISPLAY_NAME,Place.Field.ID,Place.Field.NAME,Place.Field.TYPES,Place.Field.UTC_OFFSET,Place.Field.VIEWPORT,Place.Field.WHEELCHAIR_ACCESSIBLE_ENTRANCEהשדות הבאים מפעילים את מק"ט לחיפוש בקרבת מקום (מתקדם):
Place.Field.CURRENT_OPENING_HOURS,Place.Field.CURRENT_SECONDARY_OPENING_HOURSPlace.Field.INTERNATIONAL_PHONE_NUMBER,Place.Field.NATIONAL_PHONE_NUMBERPlace.Field.OPENING_HOURS,Place.Field.PRICE_LEVEL,Place.Field.RATING,Place.Field.SECONDARY_OPENING_HOURS,Place.Field.USER_RATING_COUNTPlace.Field.WEBSITE_URI
השדות הבאים מפעילים את מק"ט (מועדף) בחיפוש בקרבת מקום:
Place.Field.ALLOWS_DOGS,Place.Field.CURBSIDE_PICKUP,Place.Field.DELIVERY,Place.Field.DINE_IN,Place.Field.EDITORIAL_SUMMARY,Place.Field.EV_CHARGE_OPTIONS,Place.Field.FUEL_OPTIONS,Place.Field.GOOD_FOR_CHILDREN,Place.Field.GOOD_FOR_GROUPS,Place.Field.GOOD_FOR_WATCHING_SPORTS,Place.Field.LIVE_MUSIC,Place.Field.MENU_FOR_CHILDREN,Place.Field.OUTDOOR_SEATING,Place.Field.PARKING_OPTIONS,Place.Field.PAYMENT_OPTIONS,Place.Field.RESERVABLE,Place.Field.RESTROOM,Place.Field.REVIEWS,Place.Field.SERVES_BEER,Place.Field.SERVES_BREAKFAST,Place.Field.SERVES_BRUNCH,Place.Field.SERVES_COCKTAILS,Place.Field.SERVES_COFFEE,Place.Field.SERVES_DESSERT,Place.Field.SERVES_DINNER,Place.Field.SERVES_LUNCH,Place.Field.SERVES_VEGETARIAN_FOOD,Place.Field.SERVES_WINE,Place.Field.TAKEOUT
כדי להגדיר את הפרמטר של רשימת השדות, צריך להפעיל את השיטה
setPlaceFields()בזמן היצירה של האובייקטSearchNearbyRequest.בדוגמה הבאה מוגדרת רשימה של שני ערכי שדות כדי לציין שהאובייקט
Placeשמוחזר על ידי בקשה מכיל את השדותPlace.Field.IDו-Place.Field.DISPLAY_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.DISPLAY_NAME);
הגבלת מיקום
אובייקט
LocationRestrictionשמגדיר את האזור לחיפוש כמעגל, שמוגדר על ידי נקודת מרכז ורדיוס במטרים. הרדיוס צריך להיות גדול מ-0.0 וקטן מ-50000.0. חשוב לזכור שציון רדיוס קטן מדי יגרום להצגת הערךZERO_RESULTSבתגובה.כדי להגדיר את הפרמטר של הגבלת המיקום, צריך לבצע קריאה ל-method
setLocationRestriction()בזמן היצירה של האובייקטSearchNearbyRequest.
פרמטרים אופציונליים
משתמשים באובייקט SearchNearbyRequest כדי לציין את הפרמטרים האופציונליים לחיפוש.
-
סוגים וסוגים ראשיים
מאפשר לציין רשימה של סוגים מתוך הסוגים שמפורטים בטבלה א', שמשמש לסינון תוצאות החיפוש. אפשר לציין עד 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 = Arrays.asList("restaurant")ו-excludedPrimaryTypes = Arrays.asList("steak_house"), המקומות שחוזרים מספקים שירותים שקשורים ל-"restaurant", אבל הם לא פועלים בעיקר בתור"steak_house".דוגמה לשימוש ב-
includedTypesוב-excludedTypesמופיעה בקטע בקשות של חיפוש בקרבת מקום (חדש).סוגי הפריטים הכלולים
רשימה של סוגי המקומות מטבלה א' שרוצים לחפש. אם הפרמטר הזה לא יצוין, המערכת תחזיר מקומות מכל הסוגים.
כדי להגדיר את הפרמטר של הסוגים הכלולים, צריך לבצע קריאה ל-method
setIncludedTypes()כשיוצרים את האובייקטSearchNearbyRequest.סוגי מודעות מוחרגים
רשימה של סוגי מקומות מטבלה א' שרוצים להחריג מחיפוש.
אם מציינים בבקשה גם את הערך של
includedTypes(למשל"school") וגם את הערך שלexcludedTypes(למשל"primary_school"), התשובה תכלול מקומות שסווגו כ-"school"אבל לא כ-"primary_school". התשובה כוללת מקומות שתואמים לפחות לאחד מה-includedTypesולאף אחד מה-excludedTypes.אם יש סוגי נתונים מתנגשים, למשל סוג שמופיע גם ב-
includedTypesוגם ב-excludedTypes, תוחזר שגיאתINVALID_REQUEST.כדי להגדיר את הפרמטר של הסוגים שאינם נכללים, צריך לבצע קריאה ל-method
setExcludedTypes()כשיוצרים את האובייקטSearchNearbyRequest.סוגי ראשיים כלולים
רשימה של סוגי המקומות הראשיים מטבלה א' שרוצים לכלול בחיפוש.
כדי להגדיר את הפרמטר של סוגי הנתונים הראשיים הכלולים, צריך לקרוא ל-method
setIncludedPrimaryTypes()בזמן היצירה של האובייקטSearchNearbyRequest.סוגי פריטים ראשיים שלא נכללים
רשימה של סוגי המקומות הראשיים מטבלה א' שרוצים להחריג מהחיפוש.
אם יש סוגים ראשיים סותרים, למשל סוג שמופיע גם ב-
includedPrimaryTypesוגם ב-excludedPrimaryTypes, תוחזר שגיאה מסוגINVALID_ARGUMENT.כדי להגדיר את הפרמטר של סוגי המשנה שאינם נכללים, צריך לבצע קריאה ל-method
setExcludedPrimaryTypes()בזמן היצירה של האובייקטSearchNearbyRequest. -
מספר התוצאות המקסימלי
מציין את המספר המקסימלי של תוצאות של מקומות שאפשר להציג. הערך חייב להיות בין 1 ל-20 (ברירת המחדל), כולל.
כדי להגדיר את הפרמטר של מספר התוצאות המקסימלי, צריך לקרוא ל-method
setMaxResultCount()בזמן היצירה של האובייקטSearchNearbyRequest. -
העדפת דירוג
סוג הדירוג שבו רוצים להשתמש. אם משמיטים את הפרמטר הזה, התוצאות מדורגות לפי פופולריות. יכול להיות אחד מהערכים הבאים:
POPULARITY(ברירת מחדל) מיון התוצאות לפי הפופולריות שלהן.DISTANCEמיון התוצאות בסדר עולה לפי המרחק שלהן מהמיקום שצוין.
כדי להגדיר את הפרמטר של העדפת הדירוג, צריך לבצע קריאה ל-method
setRankPreference()בזמן היצירה של האובייקטSearchNearbyRequest. -
קוד אזור
קוד האזור שמשמש לפורמט התשובה, שצוין בתור ערך של קוד CLDR בן שני תווים. אין ערך ברירת מחדל.
אם שם המדינה בשדה
FORMATTED_ADDRESSבתגובה תואם ל-regionCode, קידומת המדינה לא תופיע ב-FORMATTED_ADDRESS.רוב הקודים של CLDR זהים לקודי ISO 3166-1, מלבד כמה חריגים בולטים. לדוגמה, הדומיין ברמה העליונה של בריטניה הוא "uk" (.co.uk), והקוד שלו לפי תקן ISO 3166-1 הוא "gb" (טכנית, הישות היא "The United Kingdom of Great Britain and Northern Ireland"). הפרמטר יכול להשפיע על התוצאות בהתאם לדין החל.
כדי להגדיר את הפרמטר של קוד האזור, קוראים ל-method
setRegionCode()כשיוצרים את האובייקטSearchNearbyRequest.
הצגת שיוך באפליקציה
אם האפליקציה שלכם מציגה מידע שהתקבל מ-PlacesClient, כמו תמונות וביקורות, האפליקציה חייבת גם להציג את הקרדיטים הנדרשים.
מידע נוסף זמין במאמר המדיניות של Places SDK ל-Android.