פרטי מקום

מפתחים באזור הכלכלי האירופי (EEA)

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

פרטי המקום

אובייקט Place מספק מידע על מקום ספציפי. אפשר לקבל אובייקט Place באמצעות קריאה אל PlacesClient.fetchPlace(). אפשר לעיין במדריך בנושא קבלת מקום לפי מזהה.

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

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

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

Kotlin

// Specify the fields to return.
val placeFields = listOf(Place.Field.DISPLAY_NAME, Place.Field.RATING)

Java

// Specify the fields to return.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.DISPLAY_NAME, Place.Field.RATING);

גישה לשדות נתונים של אובייקט Place

אחרי שמקבלים את האובייקט 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 שמציין אם המקום פתוח כרגע על סמך השעה שצוינה בקריאה.

ה-method הזו מקבלת ארגומנט יחיד מסוג 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());
            // ...
        });
// ...

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

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

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

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

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

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