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

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

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

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

בקשות Place Details (New)

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

כדי לגשת לשדות נתונים, צריך להפעיל את השיטה המתאימה. לדוגמה, כדי לגשת לשם המקום, קוראים ל-getName().

פרמטרים נדרשים

הפרמטרים הנדרשים עבור FetchPlaceRequest הם:

• מזהה מקום

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

• רשימת השדות

  כשמבקשים מידע על מקום, צריך לציין אילו נתונים על המקום רוצים לקבל. כדי לעשות זאת, מעבירים רשימה של ערכי 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*
        * Use instead of Place.Field.ADDRESS (deprecated).
    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);