פרטי מקום

Places SDK ל-Android מספק לאפליקציה מידע עשיר על מקומות, כולל השם והכתובת של המקום, המיקום הגיאוגרפי שצוין כקואורדינטות של קו הרוחב/קו האורך, סוג המקום (למשל מועדון לילה, חנות לחיות מחמד, מוזיאון) ועוד. כדי לגשת למידע הזה לגבי מקום ספציפי, אפשר להשתמש במזהה המקום – מזהה יציב שמזהה באופן ייחודי מקום מסוים.

פרטי המקום

האובייקט Place מספק מידע על מקום ספציפי. אפשר לקבל אובייקט Place בדרכים הבאות:

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

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

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

KotlinJava
// Specify the fields to return.
val placeFields = listOf(Place.Field.NAME, Place.Field.RATING, Place.Field.OPENING_HOURS)
 
// 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 עם פרטי המקום.

מספר דוגמאות:

KotlinJava
val name = place.name
val address = place.address
val location = place.latLng

      
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() כדי לקבל פרטים על המקום שצוין.

KotlinJava
// 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")
        }
    }

      
// 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():

KotlinJava
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
}
// ...

      
@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 חייב לכלול מזהה מקום תקין:

KotlinJava
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
    }
    // ...
}
// ...

      
@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());
            // ...
        });
// ...

הצגת שיוך באפליקציה

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

מידע נוסף על מזהי מקומות

מזהה המקום שמשמש ב-Places SDK ל-Android הוא אותו מזהה שמופיע ב-Places API. כל מזהה מקום יכול להתייחס רק למקום אחד, אבל למקום אחד יכולים להיות כמה מזהי מקומות. יש גם מצבים אחרים שבהם יכול להיות שמיקום יקבל מזהה חדש. לדוגמה, זה יכול לקרות אם עסק עובר למיקום חדש.

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

מידע נוסף זמין במאמר סקירה כללית על מזהי מקומות.