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

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

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

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

בקשות לגבי פרטי מקום (חדש)

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

כדי לגשת לשדות הנתונים, צריך להפעיל את השיטה המתאימה. לדוגמה, כדי לגשת לשם המקום, קוראים לפונקציה 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.

• אסימון סשן

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

  כדי להגדיר את הפרמטר של אסימון הסשן, צריך לקרוא ל-method‏ setSessionToken() כשיוצרים את האובייקט FetchPlaceRequest.

דוגמה לפרטי מקום

בדוגמה הבאה מבקשים את השדות ID,‏ DISPLAY_NAME ו-FORMATTED_ADDRESS של בניין Empire State בניו יורק.

// 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);