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 ListplaceFields = Arrays.asList(Place.Field.NAME, Place.Field.RATING, Place.Field.OPENING_HOURS);
גישה לשדות הנתונים של אובייקט Place
אחרי שמקבלים את האובייקט Place
, משתמשים בשיטות של האובייקט כדי לגשת לשדות הנתונים שצוינו בבקשה. אם השדה חסר באובייקט Place
, השיטה הקשורה מחזירה null. ריכזנו כאן דוגמאות לכמה מהשיטות הזמינות.
רשימה מלאה של כל השיטות מופיעה בהפניית API של Place
.
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();
גישה לנתוני מקום שנוספו בגרסה 3.3.0
Places SDK ל-Android בגרסה 3.3.0 מוסיף נתונים חדשים ל-Place
:
- סוגי מקומות: ערכים חדשים של סוגים שמשויכים למקום.
- ביקורות: עד חמש ביקורות על מקום.
- קוד השפה של השם: קוד השפה של השם של המקום.
עליך להפעיל את Places SDK עבור Android (חדש) כדי לגשת לנתונים האלה. במאמר בחירת גרסת ה-SDK מוסבר על ההבדלים העיקריים בין שתי גרסאות ה-SDK.
בקטעים הבאים מתואר איך לגשת לנתונים החדשים האלה.
גישה לסוגי מקומות חדשים
לכל מקום ניתן לשייך ערך אחד או יותר של סוג. SDK של מקומות ל-Android בגרסה 3.3.0 מוסיף ערכי סוגים חדשים רבים. לרשימה המלאה, ראו סוגי מקומות מורחבים.
ב- Places SDK ל-Android בגרסה 3.2.0 ובגרסאות קודמות, השתמשתם בשיטה Place.getTypes()
כדי לגשת לערכי הסוגים שמשויכים למקום מסוים. הפונקציה Place.getTypes()
מחזירה רשימה של סוגים כערכי 'טיפוסים בני מנייה (enum)' שהוגדרה על ידי Place.Types
.
השיטה Place.getPlaceTypes()
מחזירה את ערכי הסוג כרשימה של ערכי מחרוזת. הערכים שמוחזרים תלויים בגרסה של Places SDK ל-Android:
- Places SDK ל-Android (חדש): מחזירה את המחרוזות שהוגדרו על ידי טבלה א' וטבלה ב' ומוצגות בסוגי מקומות (חדש), כולל כל סוגי המקומות שנוספו בגרסה 3.3.0.
- Places SDK for Android: מחזירה את ה-enums שהוגדר על ידי
Place.Types
, לא כולל את הסוגים החדשים שנוספו בגרסה 3.3.0.
במאמר בחירת גרסת ה-SDK מוסבר מה ההבדלים העיקריים בין שתי גרסאות ה-SDK.
גישה לביקורות על מקומות
Places SDK ל-Android (חדש) מוסיף את המחלקה Review
, שמכילה ביקורת על מקום. האובייקט Place
יכול להכיל עד חמש ביקורות.
המחלקה Review
יכולה גם לכלול שיוך (Attribution) ושיוך מחבר. אם הביקורת שלך מוצגת באפליקציה, עליך להציג גם ייחוס או ייחוס למחבר.
מידע נוסף זמין במאמר הצגת ביקורת.
כדי לאכלס את האובייקט Place
בביקורות, צריך:
- מפעילים את ה-SDK החדש בזמן הגדרת הפרויקט ב-Google Cloud.
- מפעילים את ה-SDK החדש בתוך פעילות או מקטע.
- כוללים את
Place.Field.REVIEWS
בשדה הבקשה של פרטי המקום. - קוראים לפונקציה
PlacesClient.fetchPlace()
. השדה 'ביקורות' לא נתמך על ידיPlacesClient.findCurrentPlace()
. - משתמשים בשיטה
Place.getReviews()
כדי לגשת לשדה של נתוני הביקורות באובייקטPlace
.
גישה לקוד השפה של שם המקום
השיטה הקיימת Place.getName()
מחזירה מחרוזת טקסט שמכילה את שם המקום. כדי לאכלס את האובייקט Place
עם שם המקום, צריך לכלול את Place.Field.NAME
ברשימת השדות של הבקשה לפרטי המקום.
האובייקט Place
מכיל עכשיו את קוד השפה של מחרוזת השם. כדי לאכלס את האובייקט Place
בקוד שפה, צריך:
- מפעילים את ה-SDK החדש בזמן הגדרת הפרויקט ב-Google Cloud.
- מפעילים את ה-SDK החדש בתוך פעילות או מקטע.
- כוללים את
Place.Field.NAME
ברשימת השדות של הבקשה. הערך הזה מגדיר את התגובה כך שתכלול גם את שם המקום וגם את קוד השפה באובייקטPlace
. - קוראים לפונקציה
PlacesClient.fetchPlace()
. הפונקציהPlacesClient.findCurrentPlace()
לא תומכת בשדה של קוד השפה. - משתמשים ב-method
Place.getNameLanguageCode()
כדי לגשת לשדה של קוד השפה באובייקטPlace
.
הגדרת קוד האזור בגרסה 3.3.0
Places SDK ל-Android (חדש) מוסיף את הפרמטר של הבקשה לקוד אזור ל'פרטי מקום'. קוד האזור משמש לעיצוב התשובה, שמצוינת כערך קוד CLDR בן שני תווים. לפרמטר הזה יכולה להיות גם השפעה של הטיה על תוצאות החיפוש. אין ערך ברירת מחדל. עליך להפעיל את ה-SDK החדש כדי להגדיר את קוד האזור.
אם שם המדינה בשדה הכתובת בתשובה תואם לקוד האזור, קוד המדינה לא יופיע בכתובת.
רוב קודי ה-CLDR זהים לקודי ISO 3166-1, למעט כמה יוצאים מן הכלל. לדוגמה, שם הדומיין ברמה העליונה של בריטניה הוא "uk" (co.uk). קוד ISO 3166-1 הוא "gb" (המונח הטכני הוא "בריטניה" וצפון אירלנד). הפרמטר יכול להשפיע על התוצאות בהתאם לדין החל.
קבלת מקום לפי מזהה
מזהה מקום הוא מזהה טקסט שמזהה מקום באופן ייחודי. ב-Place 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()
כדי לאחזר אותם. למידע נוסף על יצירת האובייקט Place עם השדות הנחוצים, ראו Place details (פרטי מקום).
הדוגמה הבאה קובעת אם המקום פתוח עכשיו. בדוגמה הזו מעבירים רק את מזהה המקום אל 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. כל מזהה מקום יכול להתייחס רק למקום אחד, אבל למקום אחד יכול להיות יותר ממזהה אחד של מקום. יש נסיבות אחרות שעלולות לגרום למקום לקבל מזהה מקום חדש. לדוגמה, זה יכול לקרות אם עסק עובר למיקום חדש.
כשמבקשים מקום על ידי ציון מזהה מקום, אפשר להיות בטוחים שתמיד תקבלו את אותו המקום בתגובה (אם המקום עדיין קיים). עם זאת, חשוב לשים לב שהתשובה עשויה להכיל מזהה מקום שונה מהמזהה שצוין בבקשה.
מידע נוסף זמין בסקירה הכללית על מזהה מקום.