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

בחירת פלטפורמה: Android iOS JavaScript שירות אינטרנט

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

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

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

הערה: פרטי מקום (חדש) זמינים ב-Places SDK ל-Android בגרסה 3.3.0 ואילך. מידע נוסף זמין במאמר בחירת גרסת ה-SDK.

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

אפשר לבקש פרטי מקום באמצעות קריאה ל-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);

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

תשובות בנושא פרטי מקום (חדש)

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

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

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

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

• מזהה מקום

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

• רשימת שדות

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

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

  צריך לציין אחד או יותר מהשדות הבאים:

  • השדות הבאים מפעילים את המק"ט של פרטי המקום (מזהים בלבד):

    Place.Field.ID, Place.Field.NAME, Place.Field.PHOTO_METADATAS

  • השדות הבאים מפעילים את המק"ט של פרטי המקום (מיקום בלבד):

    Place.Field.ADDRESS_COMPONENTS, Place.Field.ADDRESS, Place.Field.LAT_LNG, Place.Field.PLUS_CODE, Place.Field.TYPES, Place.Field.VIEWPORT

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

    Place.Field.BUSINESS_STATUS, Place.Field.ICON_BACKGROUND_COLOR, Place.Field.ICON_URL, Place.Field.UTC_OFFSET, Place.Field.WHEELCHAIR_ACCESSIBLE_ENTRANCE

  • השדות הבאים מפעילים את המק"ט של פרטי המקום (מתקדם):

    Place.Field.CURRENT_OPENING_HOURS, Place.Field.SECONDARY_OPENING_HOURS, Place.Field.PHONE_NUMBER, Place.Field.PRICE_LEVEL, Place.Field.RATING, Place.Field.OPENING_HOURS, Place.Field.USER_RATINGS_TOTAL, Place.Field.WEBSITE_URI

  • השדות הבאים מפעילים את המק"ט של פרטי המקום (מועדף):

    Place.Field.CURBSIDE_PICKUP, Place.Field.DELIVERY, Place.Field.DINE_IN, Place.Field.EDITORIAL_SUMMARY, Place.Field.RESERVABLE, Place.Field.REVIEWS, Place.Field.SERVES_BEER, Place.Field.SERVES_BREAKFAST, Place.Field.SERVES_BRUNCH, Place.Field.SERVES_DINNER, Place.Field.SERVES_LUNCH, Place.Field.SERVES_VEGETARIAN_FOOD, Place.Field.SERVES_WINE, Place.Field.TAKEOUT

פרמטרים אופציונליים

הפרמטרים האופציונליים של FetchPlaceRequest הם:

• קוד אזור

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

  אם שם המדינה בשדה Place.Field.ADDRESS בתשובה תואם regionCode, קוד המדינה לא יושמט מ-Place.Field.ADDRESS.

  רוב קודי ה-CLDR זהים לקודי ISO 3166-1, עם כמה יוצאים מן הכלל. לדוגמה, הדומיין ccTLD של בריטניה הוא 'uk' (.co.uk) ואילו קוד ISO 3166-1 הוא 'gb' (טכנית לישות 'בריטניה וצפון אירלנד'). הפרמטר יכול להשפיע על התוצאות בהתאם לחוק הרלוונטי.

  כדי להגדיר את הפרמטר של קוד האזור, צריך להפעיל את השיטה setRegionCode() כשמפתחים את האובייקט FetchPlaceRequest.

• אסימון הסשן

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

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

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

בדוגמה הבאה נשלחת בקשה לשדות ID, NAME ו-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.NAME, Place.Field.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);