כדי לבקש פרטים נוספים על מקום מסוים או על אתר תיירותי מסוים, אפשר להשתמש במזהה המקום שלו ולשלוח בקשה לפרטים על המקום (חדש). 'פרטי המקום' (חדש) מחזיר מידע מקיף יותר על המקום שצוין, כמו הכתובת המלאה, מספר הטלפון, הדירוג של המשתמשים והביקורות.
יש הרבה דרכים לקבל מזהה מקום. אפשר להשתמש:
בקשות של Place Details (חדש)
כדי לבקש פרטים על מקום, צריך להפעיל את השיטה 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 Details (New) מחזירה נתונים בצורת אובייקט Place, שכולל רק את השדות שביקשת באמצעות רשימת השדות. אי אפשר לקבל תוצאות ריקות של נתוני מקומות, ולכן המערכת מחזירה רק תוצאות של מקומות עם נתונים (לדוגמה, אם אין תמונות של מקום מסוים, השדה 'תמונות' לא יופיע בתוצאה).
כדי לגשת לשדות הנתונים, צריך להפעיל את השיטה המתאימה.
לדוגמה, כדי לגשת לשם המקום, קוראים לפונקציה getName().
פרמטרים נדרשים
הפרמטרים הנדרשים ל-FetchPlaceRequest הם:
-
מזהה מקום
מזהה טקסט שמזהה באופן ייחודי מקום, וחוזרים עליו מחיפוש טקסט (חדש), מחיפוש בקרבת מקום (חדש) או מהשלמה אוטומטית (חדש). למידע נוסף על מזהי מקומות, ראו סקירה כללית על מזהי מקומות.
-
רשימת שדות
כשמבקשים מקום, צריך לציין אילו נתוני מקום להחזיר. כדי לעשות זאת, מעבירים רשימה של ערכים של
Place.Fieldשמציינים את הנתונים להחזרה. אין רשימת ברירת מחדל של שדות שמוחזרים בתגובה.רשימות שדות הן שיטה טובה לתכנון כדי לוודא שאתם לא מבקשים נתונים מיותרים, וכך להימנע מזמן עיבוד מיותר וחיובים מיותרים.הרשימה הזו חשובה כי היא משפיעה על העלות של כל בקשה. למידע נוסף, ראו שימוש וחיובים.
מציינים אחד או יותר מהשדות הבאים:
השדות הבאים מפעילים את מק"ט פרטי המקום (מזהי מקום בלבד):
Place.Field.DISPLAY_NAME,Place.Field.ID,Place.Field.PHOTO_METADATAS,Place.Field.RESOURCE_NAME
השדות הבאים מפעילים את מק"ט פרטי המקום (מיקום בלבד):
Place.Field.ADDRESS_COMPONENTS,ADR_FORMAT_ADDRESS,Place.Field.FORMATTED_ADDRESS,Place.Field.LOCATION,Place.Field.PLUS_CODE,Place.Field.SHORT_FORMATTED_ADDRESS,Place.Field.TYPES,Place.Field.VIEWPORT
השדות הבאים מפעילים את מק"ט 'פרטי מקום (בסיסי)':
Place.Field.ACCESSIBILITY_OPTIONS,Place.Field.BUSINESS_STATUS,Place.Field.GOOGLE_MAPS_URI,Place.Field.ICON_BACKGROUND_COLOR,Place.Field.ICON_MASK_URL,Place.Field.PRIMARY_TYPE,Place.Field.PRIMARY_TYPE_DISPLAY_NAME,Place.Field.SUB_DESTINATIONS,Place.Field.UTC_OFFSET
השדות הבאים מפעילים את מק"ט פרטי המקום (מתקדם):
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
פרמטרים אופציונליים
הפרמטרים האופציונליים של FetchPlaceRequest הם:
קוד אזור
קוד האזור שמשמש לפורמט התשובה, שצוין בתור ערך של קוד CLDR בן שני תווים. אין ערך ברירת מחדל.
אם שם המדינה בשדה
Place.Field.FORMATTED_ADDRESSבתגובה תואם ל-regionCode, קידומת המדינה לא תופיע ב-Place.Field.FORMATTED_ADDRESS.רוב קודי CLDR זהים לקודי ISO 3166-1, מלבד כמה חריגים בולטים. לדוגמה, הדומיין ברמה העליונה של בריטניה הוא "uk" (.co.uk), והקוד שלו לפי תקן ISO 3166-1 הוא "gb" (טכנית, הישות היא "The United Kingdom of Great Britain and Northern Ireland"). הפרמטר יכול להשפיע על התוצאות בהתאם לדין החל.
כדי להגדיר את הפרמטר של קוד האזור, קוראים ל-method
setRegionCode()כשיוצרים את האובייקטFetchPlaceRequest.-
טוקן לסשן
אסימוני סשנים הם מחרוזות שנוצרות על ידי משתמשים ומשמשות למעקב אחרי קריאות של השלמה אוטומטית (חדשה) בתור 'סשנים'. ב'השלמה אוטומטית (חדש)' נעשה שימוש באסימוני סשן כדי לקבץ את שלבי השאילתה ובחירת המיקום בחיפוש של משתמש עם השלמה אוטומטית לסשן נפרד למטרות חיוב. אסימוני הסשן מועברים לשיחות מסוג 'פרטי מקום (חדש)' שמגיעות אחרי שיחות מסוג 'השלמה אוטומטית (חדש)'. למידע נוסף, תוכלו לקרוא את המאמר אסימוני סשן.
כדי להגדיר את הפרמטר של אסימון הסשן, קוראים ל-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);