אתם יכולים לבקש פרטים נוספים על מקום מסוים או על נקודת עניין מסוימת באמצעות מזהה המקום שלהם, ולשלוח בקשה לפרטי מקום (חדש). השירות 'פרטי מקום (חדש)' מחזיר מידע מקיף יותר על המקום שצוין, כמו הכתובת המלאה, מספר הטלפון, דירוגים וביקורות של משתמשים.
יש הרבה דרכים להשיג מזהה מקום. אפשר להשתמש:
בקשות Place Details (New)
כדי לבקש פרטים על מקום, קוראים ל-method PlacesClient.fetchPlace() ומעבירים אובייקט FetchPlaceRequest שמכיל מזהה מקום ורשימת שדות, וגם פרמטרים אופציונליים:
// Define a place ID.
final String placeId = "INSERT_PLACE_ID_HERE";
// Specify the list of fields to return.
final List<Place.Field> placeFields = Arrays.asList("INSERT_PLACE_FIELDS_HERE");
// Construct a request object, passing the place ID and field list.
final FetchPlaceRequest request = FetchPlaceRequest.newInstance(placeId, placeFields);
// Pass the request object and make the request
Task<FetchPlaceResponse> placeTask = placesClient.fetchPlace(request);
תשובות לפרטי מקום (חדש)
השיטה Place Details (New) מחזירה נתונים בצורה של אובייקט Place, שכולל רק את השדות שביקשתם באמצעות field list. תוצאות של נתוני מקומות לא יכולות להיות ריקות, ולכן מוחזרות רק תוצאות של מקומות עם נתונים (לדוגמה, אם למקום המבוקש אין תמונות, השדה photos לא יופיע בתוצאה).
כדי לגשת לשדות נתונים, צריך להפעיל את השיטה המתאימה.
לדוגמה, כדי לגשת לשם המקום, קוראים ל-getName().
פרמטרים נדרשים
הפרמטרים הנדרשים עבור
FetchPlaceRequest
הם:
-
מזהה מקום
מזהה טקסטואלי שמזהה באופן ייחודי מקום, ומוחזר מ-חיפוש טקסט (חדש), חיפוש בקרבת מקום (חדש) או Autocomplete (חדש). מידע נוסף על מזהי מקומות זמין במאמר סקירה כללית על מזהי מקומות.
-
רשימת השדות
כשמבקשים מיקום, צריך לציין אילו נתונים של המיקום רוצים לקבל. כדי לעשות זאת, מעבירים רשימה של ערכי
Place.Fieldשמציינים את הנתונים שרוצים להחזיר. אין רשימת ברירת מחדל של שדות שמוחזרים בתגובה.רשימות של שדות הן שיטה טובה לתכנון כדי לוודא שלא מבקשים נתונים מיותרים, וכך להימנע מזמן עיבוד מיותר ומחיובים מיותרים.הרשימה הזו חשובה כי היא משפיעה על העלות של כל בקשה. מידע נוסף זמין במאמר שימוש וחיוב.
מציינים אחד או יותר מהשדות הבאים:
השדות הבאים מפעילים את המק"ט Place Details Essentials IDs Only:
Place.Field.ID
Place.Field.PHOTO_METADATAS
Place.Field.RESOURCE_NAME
השדות הבאים מפעילים את מק"ט Place Details Essentials:
Place.Field.ADDRESS_COMPONENTS
ADR_FORMAT_ADDRESS
Place.Field.FORMATTED_ADDRESS*
* יש להשתמש במקוםPlace.Field.ADDRESS(הוצא משימוש).
Place.Field.LOCATION*
* לשימוש במקוםPlace.Field.LAT_LNG(הוצא משימוש).
Place.Field.PLUS_CODE
Place.Field.SHORT_FORMATTED_ADDRESS
Place.Field.TYPES
Place.Field.VIEWPORTהשדות הבאים מפעילים את מזהה המק"ט Place Details Pro:
Place.Field.ACCESSIBILITY_OPTIONS*
* אפשר להשתמש במקוםPlace.Field.WHEELCHAIR_ACCESSIBLE_ENTRANCE(הוצא משימוש).
Place.Field.BUSINESS_STATUS
Place.Field.DISPLAY_NAME*
* השימוש ב-Place.Field.NAMEהוצא משימוש, לכן צריך להשתמש במקומו ב-
.
Place.Field.GOOGLE_MAPS_URI
Place.Field.ICON_BACKGROUND_COLOR
Place.Field.ICON_MASK_URL*
* יש להשתמש במקוםPlace.Field.ICON_URL(הוצא משימוש).
Place.Field.PRIMARY_TYPE
Place.Field.PRIMARY_TYPE_DISPLAY_NAME
Place.Field.SUB_DESTINATIONS
Place.Field.UTC_OFFSETהשדות הבאים מפעילים את מזהה המק"ט Place Details Enterprise:
Place.Field.CURRENT_OPENING_HOURS
Place.Field.CURRENT_SECONDARY_OPENING_HOURS
Place.Field.INTERNATIONAL_PHONE_NUMBER*
* אפשר להשתמש במקום ב-Place.Field.PHONE_NUMBER, שהוצא משימוש.
Place.Field.NATIONAL_PHONE_NUMBER
Place.Field.OPENING_HOURS
Place.Field.PRICE_LEVEL
Place.Field.RATING
Place.Field.SECONDARY_OPENING_HOURS
Place.Field.USER_RATING_COUNT*
* אפשר להשתמש במקוםPlace.Field.USER_RATINGS_TOTAL, שהוצא משימוש.
Place.Field.WEBSITE_URIהשדות הבאים מפעילים את המק"ט Place Details Enterprise Plus:
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
פרמטרים אופציונליים
הפרמטרים האופציונליים של
FetchPlaceRequest
הם:
קוד אזור
קוד האזור שמשמש לעיצוב התשובה, שמוגדר כערך קוד CLDR באורך שני תווים. אין ערך ברירת מחדל.
אם שם המדינה בשדה
Place.Field.FORMATTED_ADDRESSבתשובה תואם לערךregionCode, קוד המדינה מושמט מ-Place.Field.FORMATTED_ADDRESS.רוב הקודים של CLDR זהים לקודי ISO 3166-1, אבל יש כמה יוצאים מן הכלל. לדוגמה, ה-ccTLD של בריטניה הוא uk (.co.uk), אבל קוד ISO 3166-1 שלה הוא gb (טכנית, עבור הישות 'ממלכת בריטניה הגדולה וצפון אירלנד'). הפרמטר יכול להשפיע על התוצאות בהתאם לדין החל.
כדי להגדיר את פרמטר קוד האזור, צריך לבצע קריאה ל-method
setRegionCode()כשיוצרים את האובייקטFetchPlaceRequest.-
טוקן סשן
אסימוני סשן הם מחרוזות שנוצרות על ידי המשתמשים ועוקבות אחרי קריאות ל-Autocomplete (חדש) בתור 'סשנים'. ההשלמה האוטומטית (חדש) משתמשת באסימוני סשן כדי לקבץ את השאילתה ולמקם את שלבי הבחירה של חיפוש השלמה אוטומטית של משתמש בסשן נפרד למטרות חיוב. אסימוני סשן מועברים לקריאות של Place Details (חדש) שמגיעות אחרי קריאות של Autocomplete (חדש). מידע נוסף זמין במאמר אסימוני סשן.
כדי להגדיר את פרמטר טוקן הסשן, צריך לבצע קריאה ל-method
setSessionToken()כשיוצרים את האובייקטFetchPlaceRequest.
דוגמה לפרטי מקום
בדוגמה הבאה מוצגת בקשה לשדות ID, DISPLAY_NAME ו-FORMATTED_ADDRESS של בניין האמפייר סטייט בניו יורק.
// Define a place ID.
final String placeId = "ChIJaXQRs6lZwokRY6EFpJnhNNE";
// Specify the list of fields to return.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.DISPLAY_NAME, Place.Field.FORMATTED_ADDRESS);
// Construct a request object, passing the place ID and field list.
final FetchPlaceRequest request = FetchPlaceRequest.newInstance(placeId, placeFields);
// Pass the request object and make the request
Task<FetchPlaceResponse> placeTask = placesClient.fetchPlace(request);