כדי לבקש פרטים נוספים על מקום מסוים או על נקודת עניין, אפשר להשתמש במזהה המקום שלו ולשלוח בקשה לפרטי מקום (חדש). השירות 'פרטי מקום (חדש)' מחזיר מידע מקיף יותר על המקום שצוין, כמו הכתובת המלאה, מספר הטלפון, דירוג המשתמשים והביקורות.
יש הרבה דרכים להשיג מזהה מקום. אפשר להשתמש:
בקשות 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 (חדש) מחזירה נתונים בצורה של אובייקט Place, שכולל רק את השדות שביקשתם באמצעות רשימת השדות. תוצאות של נתוני מקומות לא יכולות להיות ריקות, ולכן מוחזרות רק תוצאות של מקומות עם נתונים (לדוגמה, אם למקום המבוקש אין תמונות, השדה photos לא יופיע בתוצאה).
כדי לגשת לשדות נתונים, קוראים לשיטה המתאימה.
לדוגמה, כדי לגשת לשם המקום, קוראים ל-getName().
פרמטרים נדרשים
הפרמטרים הנדרשים עבור
FetchPlaceRequest
הם:
-
מזהה מקום
מזהה טקסטואלי שמזהה באופן ייחודי מקום, ומוחזר מ-Text Search (חדש), Nearby Search (חדש) או 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השדות הבאים מפעילים את מק"ט פרטי מקום 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 (New) אחרי קריאות של Autocomplete (New). מידע נוסף זמין במאמר אסימוני סשן.
כדי להגדיר את הפרמטר של טוקן הסשן, צריך לבצע קריאה ל-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);