בקשת חיפוש בקרבת מקום (חדש) מקבלת את האזור כקלט
לחיפוש שצוין כעיגול, המוגדר לפי קו הרוחב וקו האורך
של נקודת המרכז של המעגל והרדיוס במטרים.
הבקשה מחזירה רשימה של מקומות תואמים, כשכל אחד מהם מיוצג באמצעות
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
class מייצג את התגובה מבקשת חיפוש. 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
בתגובה מכיל רק את
ומזהה המקום והשם של כל מקום מתאים. לאחר מכן אפשר להשתמש בPlace.getId()
ו-Place.getName()
כדי לגשת לשדות האלה בכל אובייקט Place
.
לדוגמאות נוספות של גישה לנתונים באובייקט Place
, ראו גישה למקום
שדות נתונים של אובייקט.
פרמטרים נדרשים
משתמשים ב
SearchNearbyRequest
כדי לציין את הפרמטרים הנדרשים לחיפוש.
רשימת שדות
כשמבקשים פרטי מקום, צריך לציין את הנתונים שיוחזרו אובייקט
Place
למקום בתור מסכת שדות. כדי להגדיר את מסיכת השדות, מעבירים מערך של ערכיםPlace.Field
לאובייקטSearchNearbyRequest
. התממה של שדות היא שיטה טובה לעיצוב כדי להבטיח שלא תבקשו נתונים מיותרים, וכך זמן עיבוד וחיובים מיותרים.צריך לציין אחד או יותר מהשדות הבאים:
השדות הבאים מפעילים את האפשרות חיפוש בקרבת מקום (בסיסי) SKU:
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
השדות הבאים מפעילים את האפשרות חיפוש בקרבת מקום (מתקדם) 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
השדות הבאים מפעילים את האפשרות חיפוש בקרבת מקום (מועדף) SKU:
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
כדי להגדיר את הפרמטר של רשימת השדות, קוראים לפונקציה
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
כתגובה.כדי להגדיר את הפרמטר של הגבלת המיקום, קוראים לפונקציה
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
זמינה בכתובת בקשות לחיפוש בקרבת מקום (חדש).הסוגים הכלולים
רשימה של סוגי המקומות מתוך טבלה א' לחיפוש. אם משמיטים את הפרמטר הזה, מוחזרים מקומות מכל הסוגים.
כדי להגדיר את הפרמטר של הסוגים הכלולים, צריך להפעיל את השיטה
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
כמו תמונות וביקורות, האפליקציה חייבת גם להציג את הייחוסים הנדרשים.
למידע נוסף, ראה מדיניות בנושא מקומות SDK עבור ב-Android.