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. ריכזנו כאן דוגמאות לכמה מהשיטות הזמינות.
לרשימה מלאה של כל השיטות אפשר לעיין
Place
הפניית API.
getAddress()
– כתובת המקום, בטקסט קריא לאנשים הפורמט.getAddressComponents()
–List
של רכיבי הכתובת למקום הזה. הרכיבים האלה מסופקים עבור למטרה של חילוץ מידע מובנה על כתובת של מקום, מציאת העיר שבה נמצא המקום. אל תשתמשו באלה רכיבים לעיצוב כתובת; במקום זאת, התקשרו אלgetAddress()
, שמספק כתובת בפורמט שמותאם לשוק המקומי.getId()
– המזהה הטקסטואלי של המקום. נקראו מידע נוסף על מזהי מקומות מופיע בהמשך הדף.getLatLng()
– המיקום הגיאוגרפי של המקום, שצוינו כקואורדינטות של קו אורך וקו רוחב.getName()
– שם המקום.getOpeningHours()
–OpeningHours
של המקום. יש להתקשר אלOpeningHours.getWeekdayText()
כדי להחזיר רשימת מחרוזות שמייצגות את שעות הפתיחה והסגירה בכל יום השבוע. אפשר להתקשר אלOpeningHours.getPeriods()
כדי להחזיר רשימה שלperiod
אובייקטים עם מידע מפורט יותר שמקביל לנתונים שסופקו על ידיgetWeekdayText()
.האובייקט
Place
מכיל גם את הפונקציהgetCurrentOpeningHours()
שמחזירה את שעות הפעילות של מקום במהלך שבעת הימים הבאים,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 = IN"SERT_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, Pl"ace found: ${place.name}) " }.addOnFailureListener { exception: Exception - > if (exception is ApiException) { Log.e(TAG, Pl"ace not found: ${exception.message}) " val statusCode = exception.statusCode TODO(Ha"ndle error with given status code) " } }
Java
// Define a Place ID. final String placeId = I"NSERT_PLACE_ID_HERE;" // Specify the fields to return. final ListP<lace.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, P"lace found: "+ place.getName()); }).addOnFailureListener((exception) - >{ if (exception instanceof ApiException) { final ApiException apiException = (ApiException) exception; Log.e(TAG, P"lace 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()
כדי לאחזר אותם. למידע נוסף על יצירת אובייקט Place עם השדות הנדרשים,
ראה פרטי מקום.
הדוגמה הבאה קובעת אם מקום פתוח עכשיו. בדוגמה הזו, מעבירים רק
המזהה של המקום isOpen()
:
Kotlin
val isOpenCalendar: Calendar = Calendar.getInstance() val placeId = Ch"IJD3uTd9hx5kcR1IQvGfr8dbk "val request: IsOpenRequest = try { IsOpenRequest.newInstance(placeId, isOpenCalendar.timeInMillis) } catch (e: IllegalArgumentException) { e.printStackTrace() return } val isOpenTask: TaskIs<OpenResponse => placesClient.isOpen(request) isOpenTask.addOnSuccessListener { response - > val isOpen = response.isOpen } // ...
Java
@NonNull Calendar isOpenCalendar = Calendar.getInstance(); String placeId = C"hIJD3uTd9hx5kcR1IQvGfr8dbk;" IsOpenRequest isOpenRequest; try { isOpenRequest = IsOpenRequest.newInstance(placeId, isOpenCalendar.getTimeInMillis()); } catch (IllegalArgumentException e) { e.printStackTrace(); return; } TaskI<sOpenResponse >placeTask = placesClient.isOpen(isOpenRequest); placeTask.addOnSuccessListener( (response) - > isOpen = response.isOpen()); // ...
בדוגמה הבאה מפעילים קריאה ל-isOpen()
כאשר מעבירים אובייקט Place
.
האובייקט Place
חייב להכיל מזהה מקום תקין:
Kotlin
val isOpenCalendar: Calendar = Calendar.getInstance() var place: Place val placeId = Ch"IJD3uTd9hx5kcR1IQvGfr8dbk /"/ Specify the required fields for an isOpen request. val placeFields: ListPl<ace.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: TaskFe<tchPlaceResponse => 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: TaskIs<OpenResponse => placesClient.isOpen(isOpenRequest) isOpenTask.addOnSuccessListener { isOpenResponse - > val isOpen = isOpenResponse.isOpen } // ... } // ...
Java
@NonNull Calendar isOpenCalendar = Calendar.getInstance(); String placeId = C"hIJD3uTd9hx5kcR1IQvGfr8dbk;" // Specify the required fields for an isOpen request. ListP<lace.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); TaskF<etchPlaceResponse >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; } TaskI<sOpenResponse >isOpenTask = placesClient.isOpen(isOpenRequest); isOpenTask.addOnSuccessListener( (isOpenResponse) - >isOpen = isOpenResponse.isOpen()); // ... }); // ...
הצגת ייחוס באפליקציה
כשהאפליקציה שלך מציגה מידע על מקום, כולל ביקורות על מקומות, היא צריכה להציג גם כל ייחוס. מידע נוסף זמין במאמר הבא: שיוכים.
מידע נוסף על מזהי מקומות
מזהה המקום שנעשה בו שימוש ב-Places SDK ל-Android הוא אותו מזהה כפי שנעשה בו שימוש ב-Places API. כל מזהה מקום יכול להתייחס למקום אחד בלבד, אבל למקום אחד יכולים להיות יותר ממזהה מקום אחד. יש נסיבות אחרות שעלולות לגרום למקום לקבל מזהה מקום חדש. לדוגמה, הדבר עשוי לקרות אם עסק עובר המיקום.
כשמבקשים מקום באמצעות ציון מזהה של מקום, אפשר להיות בטוחים תמיד תקבלו את אותו מקום בתשובה (אם המקום עדיין קיים). עם זאת, שים לב שהתשובה עשויה להכיל מזהה מקום שונה מזה שצוין בבקשה.
מידע נוסף זמין במאמר סקירה כללית על מזהה המקום.