Places SDK ל-Android מספק לאפליקציה מידע עשיר על מקומות, כולל השם והכתובת של המקום, המיקום הגיאוגרפי שצוין כקואורדינטות של קו הרוחב/קו האורך, סוג המקום (למשל מועדון לילה, חנות לחיות מחמד, מוזיאון) ועוד. כדי לגשת למידע הזה לגבי מקום ספציפי, אפשר להשתמש במזהה המקום – מזהה יציב שמזהה מקום באופן ייחודי.
פרטי המקום
האובייקט Place
מספק מידע על מקום ספציפי. אפשר לקבל אובייקט Place
בדרכים הבאות:
- קריאה ל-
PlacesClient.fetchPlace()
– אפשר לעיין במדריך איך למצוא מקום לפי מזהה. - מחייגים למספר
PlacesClient.findCurrentPlace()
– אפשר לעיין במדריך בנושא קבלת המיקום הנוכחי.
כשמבקשים מקום, צריך לציין אילו נתוני מקום להחזיר. כדי לעשות זאת, מעבירים רשימה של ערכים מסוג Place.Field שמציינים את הנתונים שרוצים להחזיר. חשוב להביא בחשבון את הרשימה הזו כי היא משפיעה על העלות של כל בקשה.
מאחר שתוצאות של נתוני מקומות לא יכולות להיות ריקות, רק תוצאות של מקומות עם נתונים מוחזרות. לדוגמה, אם אין תמונות של המקום המבוקש, השדה photos
לא יופיע בתוצאה.
בדוגמה הבאה מועברת רשימה של שלושה ערכים של Place.Field כדי לציין את הנתונים שמוחזרים על ידי בקשה:
Kotlin
// Specify the fields to return. val placeFields = listOf(Place.Field.NAME, Place.Field.RATING, Place.Field.OPENING_HOURS)
Java
// Specify the fields to return. final List<Place.Field> placeFields = Arrays.asList(Place.Field.NAME, Place.Field.RATING, Place.Field.OPENING_HOURS);
גישה לשדות הנתונים של אובייקט מקום
אחרי שמקבלים את האובייקט Place
, משתמשים בשיטות של האובייקט כדי לגשת לשדות הנתונים שצוינו בבקשה. אם השדה חסר באובייקט Place
, השיטה הרלוונטית מחזירה null. בהמשך מפורטות דוגמאות לכמה מהשיטות הזמינות.
getAddress()
– הכתובת של המקום, בפורמט קריא לבני אדם.getAddressComponents()
–List
של רכיבי הכתובת של המקום הזה. הרכיבים האלה נועדו לחלץ מידע מובנה על הכתובת של מקום, למשל כדי למצוא את העיר שבה המקום נמצא. אל תשתמשו ברכיבים האלה כדי לעצב כתובות. במקום זאת, צריך להפעיל את הפונקציהgetAddress()
, שמספקת כתובת בפורמט מקומי.getId()
– המזהה הטקסטואלי של המקום. בהמשך הדף מפורט מידע נוסף על מזהי מקומות.getLatLng()
– המיקום הגיאוגרפי של המקום, שמוגדר כקואורדינטות של קו אורך וקו רוחב.getName()
– שם המקום.getOpeningHours()
– הOpeningHours
של המקום. קוראים לפונקציהOpeningHours.getWeekdayText()
כדי להחזיר רשימה של מחרוזות שמייצגות את שעות הפתיחה והסגירה של כל יום בשבוע. קוראים ל-OpeningHours.getPeriods()
כדי להחזיר רשימה של אובייקטים מסוגperiod
עם מידע מפורט יותר, שזהה לנתונים שסופקו על ידיgetWeekdayText()
.האובייקט
Place
מכיל גם את השיטהgetCurrentOpeningHours()
שמחזירה את שעות הפתיחה של המקום בשבעת הימים הבאים, ואת השיטהgetSecondaryOpeningHours()
שמחזירה את שעות הפתיחה המשניות של המקום בשבעת הימים הבאים.isOpen()
– ערך בוליאני שמציין אם המקום פתוח כרגע. אם לא מציינים שעה, ברירת המחדל היא 'עכשיו'. הערךisOpen
יוחזר רק אם גםPlace.Field.UTC_OFFSET
וגםPlace.Field.OPENING_HOURS
זמינים. כדי להבטיח תוצאות מדויקות, צריך לבקש את השדותPlace.Field.BUSINESS_STATUS
ו-Place.Field.UTC_OFFSET
בבקשה המקורית של המקום. אם לא תתבצע בקשה כזו, נניח שהעסק פעיל. בסרטון הזה מוסבר איך משתמשים ב-isOpen
עם פרטי המקום.
מספר דוגמאות:
Kotlin
val name = place.name val address = place.address val location = place.latLng
Java
final CharSequence name = place.getName(); final CharSequence address = place.getAddress(); final LatLng location = place.getLatLng();
אחזור מקום לפי מזהה
מזהה מקום הוא מזהה טקסט שמזהה מקום באופן ייחודי. ב-Places SDK ל-Android, אפשר לאחזר את המזהה של מקום באמצעות קריאה ל-Place.getId()
.
שירות מילוי אוטומטי של מקומות מחזיר גם מזהה מקום לכל מקום שתואם לשאילתת החיפוש ולמסנן שסיפקתם. אפשר לשמור את מזהה המקום ולהשתמש בו כדי לאחזר את האובייקט Place
מאוחר יותר.
כדי לקבל מקום לפי מזהה, צריך להפעיל את השיטה PlacesClient.fetchPlace()
ולהעביר את הערך FetchPlaceRequest
.
ממשק ה-API מחזיר FetchPlaceResponse
ב-Task
.
השדה FetchPlaceResponse
מכיל אובייקט Place
שתואם למזהה המקום שצוין.
בדוגמה הבאה מוצגת קריאה ל-fetchPlace()
כדי לקבל פרטים על המקום שצוין.
Kotlin
// Define a Place ID. val placeId = "INSERT_PLACE_ID_HERE" // Specify the fields to return. val placeFields = listOf(Place.Field.ID, Place.Field.NAME) // Construct a request object, passing the place ID and fields array. val request = FetchPlaceRequest.newInstance(placeId, placeFields) placesClient.fetchPlace(request) .addOnSuccessListener { response: FetchPlaceResponse -> val place = response.place Log.i(PlaceDetailsActivity.TAG, "Place found: ${place.name}") }.addOnFailureListener { exception: Exception -> if (exception is ApiException) { Log.e(TAG, "Place not found: ${exception.message}") val statusCode = exception.statusCode TODO("Handle error with given status code") } }
Java
// Define a Place ID. final String placeId = "INSERT_PLACE_ID_HERE"; // Specify the fields to return. final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.NAME); // Construct a request object, passing the place ID and fields array. final FetchPlaceRequest request = FetchPlaceRequest.newInstance(placeId, placeFields); placesClient.fetchPlace(request).addOnSuccessListener((response) -> { Place place = response.getPlace(); Log.i(TAG, "Place found: " + place.getName()); }).addOnFailureListener((exception) -> { if (exception instanceof ApiException) { final ApiException apiException = (ApiException) exception; Log.e(TAG, "Place not found: " + exception.getMessage()); final int statusCode = apiException.getStatusCode(); // TODO: Handle error with given status code. } });
אחזור הסטטוס 'פתוח'
השיטה PlacesClient.isOpen(IsOpenRequest request)
מחזירה אובייקט IsOpenResponse
שמציין אם המקום פתוח כרגע, על סמך השעה שצוינה בקריאה.
לשיטה הזו יש ארגומנטים יחידים מסוג IsOpenRequest
שמכילים:
- אובייקט
Place
או מחרוזת שמציינת מזהה מקום. - ערך זמן אופציונלי שצוין בו השעה באלפיות שנייה מ-1970-01-01T00:00:00Z. אם לא מציינים שעה, ברירת המחדל היא 'עכשיו'.
כדי להשתמש בשיטה הזו, השדות הבאים צריכים להופיע באובייקט Place
:
Place.Field.BUSINESS_STATUS
Place.Field.CURRENT_OPENING_HOURS
Place.Field.OPENING_HOURS
Place.Field.UTC_OFFSET
אם השדות האלה לא יסופקו באובייקט Place
, או אם מעבירים מזהה מקום, השיטה תשתמש ב-PlacesClient.fetchPlace()
כדי לאחזר אותם. למידע נוסף על יצירת אובייקט המקום עם השדות הנדרשים, ראו פרטי מקום.
הדוגמה הבאה קובעת אם מקום מסוים פתוח כרגע. בדוגמה הזו, מעבירים רק את מזהה המקום אל isOpen()
:
Kotlin
val isOpenCalendar: Calendar = Calendar.getInstance() val placeId = "ChIJD3uTd9hx5kcR1IQvGfr8dbk" val request: IsOpenRequest = try { IsOpenRequest.newInstance(placeId, isOpenCalendar.timeInMillis) } catch (e: IllegalArgumentException) { e.printStackTrace() return } val isOpenTask: Task<IsOpenResponse> = placesClient.isOpen(request) isOpenTask.addOnSuccessListener { response -> val isOpen = response.isOpen } // ...
Java
@NonNull Calendar isOpenCalendar = Calendar.getInstance(); String placeId = "ChIJD3uTd9hx5kcR1IQvGfr8dbk"; IsOpenRequest isOpenRequest; try { isOpenRequest = IsOpenRequest.newInstance(placeId, isOpenCalendar.getTimeInMillis()); } catch (IllegalArgumentException e) { e.printStackTrace(); return; } Task<IsOpenResponse> placeTask = placesClient.isOpen(isOpenRequest); placeTask.addOnSuccessListener( (response) -> isOpen = response.isOpen()); // ...
בדוגמה הבאה מוצגת קריאה ל-isOpen()
שבה מעבירים אובייקט Place
.
האובייקט Place
חייב לכלול מזהה מקום תקין:
Kotlin
val isOpenCalendar: Calendar = Calendar.getInstance() var place: Place val placeId = "ChIJD3uTd9hx5kcR1IQvGfr8dbk" // Specify the required fields for an isOpen request. val placeFields: List<Place.Field> = listOf( Place.Field.BUSINESS_STATUS, Place.Field.CURRENT_OPENING_HOURS, Place.Field.ID, Place.Field.OPENING_HOURS, Place.Field.UTC_OFFSET ) val placeRequest: FetchPlaceRequest = FetchPlaceRequest.newInstance(placeId, placeFields) val placeTask: Task<FetchPlaceResponse> = placesClient.fetchPlace(placeRequest) placeTask.addOnSuccessListener { placeResponse -> place = placeResponse.place val isOpenRequest: IsOpenRequest = try { IsOpenRequest.newInstance(place, isOpenCalendar.timeInMillis) } catch (e: IllegalArgumentException) { e.printStackTrace() return@addOnSuccessListener } val isOpenTask: Task<IsOpenResponse> = placesClient.isOpen(isOpenRequest) isOpenTask.addOnSuccessListener { isOpenResponse -> val isOpen = isOpenResponse.isOpen } // ... } // ...
Java
@NonNull Calendar isOpenCalendar = Calendar.getInstance(); String placeId = "ChIJD3uTd9hx5kcR1IQvGfr8dbk"; // Specify the required fields for an isOpen request. List<Place.Field> placeFields = new ArrayList<>(Arrays.asList( Place.Field.BUSINESS_STATUS, Place.Field.CURRENT_OPENING_HOURS, Place.Field.ID, Place.Field.OPENING_HOURS, Place.Field.UTC_OFFSET )); FetchPlaceRequest request = FetchPlaceRequest.newInstance(placeId, placeFields); Task<FetchPlaceResponse> placeTask = placesClient.fetchPlace(request); placeTask.addOnSuccessListener( (placeResponse) -> { Place place = placeResponse.getPlace(); IsOpenRequest isOpenRequest; try { isOpenRequest = IsOpenRequest.newInstance(place, isOpenCalendar.getTimeInMillis()); } catch (IllegalArgumentException e) { e.printStackTrace(); return; } Task<IsOpenResponse> isOpenTask = placesClient.isOpen(isOpenRequest); isOpenTask.addOnSuccessListener( (isOpenResponse) -> isOpen = isOpenResponse.isOpen()); // ... }); // ...
הצגת שיוך באפליקציה
כשמוצגים באפליקציה פרטי מקום, כולל ביקורות על מקומות, צריך להציג באפליקציה גם את הקרדיטים. מידע נוסף זמין במאמר שיוכים (Attributions).
מידע נוסף על מזהי מקומות
מזהה המקום שמשמש ב-Places SDK ל-Android הוא אותו מזהה שמופיע ב-Places API. כל מזהה מקום יכול להתייחס רק למקום אחד, אבל למקום אחד יכולים להיות כמה מזהי מקום. יש גם נסיבות אחרות שעשויות לגרום לכך שמיקום מסוים יקבל מזהה חדש. לדוגמה, זה יכול לקרות אם עסק עובר למיקום חדש.
כשמבקשים מקום על ידי ציון מזהה מקום, אפשר להיות בטוחים שתמיד תקבלו את אותו מקום בתגובה (אם המקום עדיין קיים). עם זאת, חשוב לזכור שהתגובה עשויה לכלול מזהה מקום ששונה מזה שצוין בבקשה.
מידע נוסף זמין במאמר סקירה כללית על מזהי מקומות.