ערכת 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
, משתמשים ב-methods של האובייקט כדי לגשת לשדות הנתונים שצוינו בבקשה. אם השדה חסר באובייקט Place
, ה-method הקשור מחזירה null. ריכזנו כאן דוגמאות לכמה מהשיטות הזמינות.
רשימה מלאה של כל ה-methods מופיעה בחומר העזר בנושא API Place
.
getAddress()
– כתובת המקום, בפורמט קריא לאנשים.getAddressComponents()
–List
של רכיבי כתובת למקום הזה. הרכיבים האלה סופקו כדי לחלץ מידע מובנה לגבי כתובת של מקום, לדוגמה, כדי למצוא את העיר שבה המקום נמצא. אל תשתמשו ברכיבים האלה כדי לעצב את הכתובות. במקום זאת, תוכלו לקרוא לפונקציהgetAddress()
, שמספקת כתובת בפורמט שמותאם לשוק המקומי.getId()
– המזהה הטקסטואלי של המקום. בהמשך הדף הזה ניתן לקרוא מידע נוסף על מזהי מקומות.getLatLng()
– המיקום הגיאוגרפי של המקום, כקואורדינטות של קו אורך וקו רוחבgetName()
– שם המקום.getOpeningHours()
–OpeningHours
של המקום. קוראים לפונקציהOpeningHours.getWeekdayText()
כדי להחזיר רשימת מחרוזות שמייצגות את שעות הפתיחה והסגירה בכל יום בשבוע. קוראים לפונקציהOpeningHours.getPeriods()
כדי להחזיר רשימה של אובייקטיםperiod
עם מידע מפורט יותר שמקביל לנתונים שלgetWeekdayText()
.האובייקט
Place
מכיל גם את השיטהgetCurrentOpeningHours()
שמחזירה את שעות הפעילות של מקום במהלך 7 הימים הבאים, וגם את הפונקציהgetSecondaryOpeningHours()
שמחזירה את שעות הפעילות המשניות של מקום במהלך 7 הימים הבאים.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. } });
קבלת סטטוס פתיחה
ה-method 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()
כדי לאחזר אותם. למידע נוסף על יצירת אובייקט Place עם השדות הנדרשים, ראו פרטי מקום.
הדוגמה הבאה קובעת אם מקום פתוח עכשיו. בדוגמה הזו מעבירים את מזהה המקום רק ל-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()); // ... }); // ...
הצגת ייחוס באפליקציה
כשהאפליקציה שלך מציגה פרטי מקום, כולל ביקורות על מקומות, היא צריכה גם להציג את כל הקרדיטים. מידע נוסף זמין במאמר שיוך (Attribution).
מידע נוסף על מזהי מקומות
מזהה המקום שנעשה בו שימוש ב-Places SDK ל-Android הוא אותו מזהה שבו נעשה שימוש ב-Places API. כל מזהה מקום יכול להתייחס למקום אחד בלבד, אבל לכל מקום יכול להיות יותר ממזהה אחד של מקום. יש נסיבות אחרות שיכולות לגרום למקום לקבל מזהה חדש של מקום. לדוגמה, זה יכול לקרות אם עסק עובר למיקום חדש.
כשמבקשים מקום באמצעות ציון מזהה מקום, אפשר להיות בטוחים שתמיד יתקבל אותו מקום בתשובה (אם המקום עדיין קיים). עם זאת, חשוב לשים לב שהתשובה עשויה להכיל מזהה מקום שונה מזה שצוין בבקשה.
למידע נוסף, ראו סקירה כללית על מזהי מקומות.