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

בחירת פלטפורמה: Android iOS JavaScript Web Service

מפתחים באזור הכלכלי האירופי (EEA)

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

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

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

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

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

הפרמטרים הנדרשים ל-FetchPlaceRequest הם:

  • מזהה מקום

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

  • רשימת שדות

    כששולחים בקשה לגבי מקום, צריך לציין אילו נתונים של המקום רוצים לקבל. כדי לעשות את זה, מעבירים רשימה של ערכי Place.Field שמציינים את הנתונים שרוצים להחזיר. אין רשימת ברירת מחדל של שדות שמוחזרים בתגובה.

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

    מציינים אחד או יותר מהשדות הבאים:

    • השדות הבאים מפעילים את המק"ט Place Details Essentials IDs Only:

      Place.Field.ID
      Place.Field.PHOTO_METADATAS
      Place.Field.RESOURCE_NAME

      רשימה מלאה של השדות והמקט"ים שמשויכים אליהם מופיעה במאמר בנושא שדות של נתוני מקומות (חדש).

    • השדות הבאים מפעילים את Place Details Essentials SKU:

      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 SKU:

      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.

  • טוקן לסשן

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

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

דוגמה ל-Place Details

בדוגמה הבאה נשלחת בקשה לשדות 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);