פרטי מקום (חדש)

כדי לבקש פרטים נוספים על מקום מסוים או על אתר תיירותי מסוים, אפשר להשתמש במזהה המקום שלו ולשלוח בקשה לפרטים על המקום (חדש). 'פרטי המקום' (חדש) מחזיר מידע מקיף יותר על המקום שצוין, כמו הכתובת המלאה, מספר הטלפון, הדירוג של המשתמשים והביקורות.

יש הרבה דרכים לקבל מזהה מקום. אפשר להשתמש:

• חיפוש טקסט (חדש)
• חיפוש בקרבת מקום (חדש)
• השלמה אוטומטית (חדש)

בקשות של 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_HOURS Place.Field.INTERNATIONAL_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.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 (טכנית, הישות היא 'הממלכה המאוחדת של בריטניה הגדולה וצפון אירלנד'). הפרמטר יכול להשפיע על התוצאות בהתאם לדין החל.

  כדי להגדיר את הפרמטר של קוד האזור, קוראים ל-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);