‫Google משתמשת בטכנולוגיית AI כדי לתרגם תוכן לשפה המועדפת עליך. בתרגומים כאלו עשויות להיות שגיאות.

פרטי המקום (דור קודם)

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

‫getAddress() – הכתובת של המקום, בפורמט קריא לאנשים.
‫getAddressComponents() – List של רכיבי הכתובת של המקום הזה. הרכיבים האלה מסופקים כדי לחלץ מידע מובנה על הכתובת של המקום, למשל כדי למצוא את העיר שבה המקום נמצא. אל תשתמשו ברכיבים האלה כדי לעצב את הכתובת. במקום זאת, קראו ל-getAddress(), שמספק כתובת בפורמט מקומי.
‫getId() – המזהה הטקסטואלי של המקום. בהמשך הדף הזה מפורט מידע נוסף על מזהי מקומות.
‫getLatLng() – המיקום הגיאוגרפי של המקום, שמצוין כקואורדינטות של קו רוחב וקו אורך.
‫getName() – שם המקום.
getOpeningHours() – OpeningHours של המקום. מפעילים את OpeningHours.getWeekdayText() כדי להחזיר רשימה של מחרוזות שמייצגות את שעות הפתיחה והסגירה בכל יום בשבוע. מפעילים את OpeningHours.getPeriods() כדי להחזיר רשימה של אובייקטים מסוג period עם מידע מפורט יותר, ששווה ערך לנתונים שסופקו על ידי getWeekdayText().

הערה: אם המקום פתוח תמיד, פרק הזמן מיוצג כיום ראשון בחצות, והערך של closeEvent הוא null.

האובייקט Place מכיל גם את השיטה getCurrentOpeningHours(), שמחזירה את שעות הפעילות של המקום בשבעת הימים הבאים, ואת השיטה getSecondaryOpeningHours(), שמחזירה את שעות הפעילות המשניות של המקום בשבעת הימים הבאים.
‫isOpen() – ערך בוליאני שמציין אם המקום פתוח כרגע. אם לא מציינים שעה, ברירת המחדל היא עכשיו. ‫isOpen יוחזר רק אם גם Place.Field.UTC_OFFSET וגם Place.Field.OPENING_HOURS זמינים. כדי לקבל תוצאות מדויקות, צריך לבקש את השדות Place.Field.BUSINESS_STATUS ו-Place.Field.UTC_OFFSET בבקשה המקורית של המקום. אם לא נשלחה בקשה, ההנחה היא שהעסק פעיל. בסרטון הזה מוסבר איך להשתמש ב-isOpen עם Place Details.

הערה: השיטה הזו הוצאה משימוש. במקום זאת, צריך להשתמש ב-PlacesClient.isOpen(IsOpenRequest request). מידע נוסף זמין במאמר קבלת סטטוס פתוח.

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

Kotlin

        val name = place.displayName
        val address = place.formattedAddress
        val location = place.location

Java

                    final CharSequence name = place.getDisplayName();
                    final CharSequence address = place.getFormattedAddress();
                    final LatLng location = place.getLocation();

אחזור מקום לפי מזהה

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

כדי לקבל מקום לפי מזהה, צריך להפעיל את השיטה PlacesClient.fetchPlace() ולהעביר את הפרמטר FetchPlaceRequest.

ה-API מחזיר FetchPlaceResponse ב- Task. האובייקט FetchPlaceResponse מכיל אובייקט Place שתואם למזהה המקום שצוין.

בדוגמת הקוד הבאה אפשר לראות איך קוראים ל-fetchPlace() כדי לקבל פרטים על המקום שצוין.

Kotlin

// Define a Place ID.
val placeId = PlaceIdProvider.getRandomPlaceId()

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

// 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

        val name = place.displayName
        val address = place.formattedAddress
        val location = place.location

        binding.placeName.text = name
        binding.placeAddress.text = address
        if (location != null) {
            binding.placeLocation.text = getString(
                R.string.place_location,
                location.latitude,
                location.longitude,
            )
        } else {
            binding.placeLocation.text = null
        }
        Log.i(TAG, "Place found: ${place.displayName}")
    }.addOnFailureListener { exception: Exception ->
        if (exception is ApiException) {
            val message = getString(R.string.place_not_found, exception.message)
            binding.placeName.text = message
            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 = PlaceIdProvider.getRandomPlaceId();

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

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

                    final CharSequence name = place.getDisplayName();
                    final CharSequence address = place.getFormattedAddress();
                    final LatLng location = place.getLocation();

                    binding.placeName.setText(name);
                    binding.placeAddress.setText(address);
                    if (location != null) {
                        binding.placeLocation.setText(
                                getString(
                                        R.string.place_location,
                                        location.latitude,
                                        location.longitude));
                    } else {
                        binding.placeLocation.setText(null);
                    }

                    Log.i(TAG, "Place found: " + place.getDisplayName());
                })
        .addOnFailureListener(
                (exception) -> {
                    if (exception instanceof ApiException apiException) {
                        final String message =
                                getString(
                                        R.string.place_not_found,
                                        apiException.getMessage());
                        binding.placeName.setText(message);
                        Log.e(TAG, "Place not found: " + exception.getMessage());
                        final int statusCode = apiException.getStatusCode();
                        // TODO: Handle error with given status code.
                    }
                });

הערה: מידע נוסף על הפעלת PlacesClient זמין במאמר הפעלת לקוח Places API.

קבלת סטטוס פתוח

ה-method‏ PlacesClient.isOpen(IsOpenRequest request) מחזירה אובייקט IsOpenResponse שמציין אם המקום פתוח כרגע, על סמך השעה שצוינה בקריאה.

ה-method הזו מקבלת ארגומנט אחד מסוג IsOpenRequest שמכיל:

אובייקט Place או מחרוזת שמציינת מזהה מקום.
הערה: האובייקט 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 עם השדות הנדרשים זמין במאמר פרטי מקום.

הערה: מק"ט הנתונים הבסיסיים של Places מחויב על קריאות ל-fetchPlace() עבור Place.Field.UTC_OFFSET ו-Place.Field.BUSINESS_STATUS. המק"ט Contact Data של Places מחויב על קריאות ל-fetchPlace() עבור Place.Field.CURRENT_OPENING_HOURS ו-Place.Field.OPENING_HOURS.

בדוגמה הבאה נבדק אם מקום מסוים פתוח כרגע. בדוגמה הזו, אתם מעבירים רק את מזהה המקום אל isOpen():

Kotlin

val isOpenCalendar: Calendar = Calendar.getInstance()
val placeId = PlaceIdProvider.getRandomPlaceId()

val request: IsOpenRequest = try {
    IsOpenRequest.newInstance(placeId, isOpenCalendar.timeInMillis)
} catch (e: IllegalArgumentException) {
    Log.e("PlaceIsOpen", "Error: " + e.message)
    return
}
val isOpenTask: Task<IsOpenResponse> = placesClient.isOpen(request)
isOpenTask.addOnSuccessListener { response ->
    val isOpen = response.isOpen ?: false
    binding.isOpenByIdResult.text = getString(R.string.is_open_by_id, isOpen.toString())
    Log.d("PlaceIsOpen", "Is open by ID: $isOpen")
}
// ...

Java

@NonNull Calendar isOpenCalendar = Calendar.getInstance();
String placeId = PlaceIdProvider.getRandomPlaceId();
IsOpenRequest isOpenRequest;

try {
    isOpenRequest = IsOpenRequest.newInstance(placeId, isOpenCalendar.getTimeInMillis());
} catch (IllegalArgumentException e) {
    Log.e("PlaceIsOpen", "Error: " + e.getMessage());
    return;
}

Task<IsOpenResponse> placeTask = placesClient.isOpen(isOpenRequest);

placeTask.addOnSuccessListener(
        (response) -> {
            final boolean isOpen = Boolean.TRUE.equals(response.isOpen());
            binding.isOpenByIdResult.setText(
                    getString(R.string.is_open_by_id, String.valueOf(isOpen)));
            Log.d("PlaceIsOpen", "Is open by ID: " + isOpen);
        });
placeTask.addOnFailureListener(
        (exception) -> {
            binding.isOpenByIdResult.setText(
                    getString(R.string.is_open_by_id, "Error: " + exception.getMessage()));
            Log.e("PlaceIsOpen", "Error: " + exception.getMessage());
        });

בדוגמה הבאה מוצגת קריאה ל-isOpen() שבה מעבירים אובייקט Place. האובייקט Place חייב להכיל מזהה מקום תקין:

Kotlin

val isOpenCalendar: Calendar = Calendar.getInstance()
var place: Place
val placeId = PlaceIdProvider.getRandomPlaceId()
// 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.DISPLAY_NAME,
)

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) {
        Log.e("PlaceIsOpen", "Error: " + e.message)
        return@addOnSuccessListener
    }
    val isOpenTask: Task<IsOpenResponse> = placesClient.isOpen(isOpenRequest)
    isOpenTask.addOnSuccessListener { isOpenResponse ->
        val isOpen = when (isOpenResponse.isOpen) {
            true -> getString(R.string.is_open)
            else -> getString(R.string.is_closed)
        }
        binding.isOpenByObjectResult.text = getString(
            R.string.is_open_by_object,
            place.displayName,
            isOpen,
        )
        Log.d("PlaceIsOpen", "Is open by object: $isOpen")
    }
    // ...
}
// ...

Java

@NonNull Calendar isOpenCalendar = Calendar.getInstance();
String placeId = PlaceIdProvider.getRandomPlaceId();
// 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.DISPLAY_NAME));

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) {
                Log.e("PlaceIsOpen", "Error: " + e.getMessage());
                return;
            }
            Task<IsOpenResponse> isOpenTask = placesClient.isOpen(isOpenRequest);

            isOpenTask.addOnSuccessListener(
                    (isOpenResponse) -> {
                        final boolean isOpen = Boolean.TRUE.equals(isOpenResponse.isOpen());
                        binding.isOpenByObjectResult.setText(
                                getString(
                                        R.string.is_open_by_object,
                                        place.getDisplayName(),
                                        String.valueOf(isOpen)));
                        Log.d("PlaceIsOpen", "Is open by object: " + isOpen);
                    });
            isOpenTask.addOnFailureListener(
                    (exception) -> { // also update the result text field
                        binding.isOpenByObjectResult.setText(
                                getString(
                                        R.string.is_open_by_object,
                                        place.getDisplayName(),
                                        "Error: " + exception.getMessage()));
                        Log.e("PlaceIsOpen", "Error: " + exception.getMessage());
                    });
        });
placeTask.addOnFailureListener(
        (exception) -> {
            binding.isOpenByObjectResult.setText("Error: " + exception.getMessage());
            Log.e("PlaceIsOpen", "Error: " + exception.getMessage());

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

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

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

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

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

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

פרטי המקום (דור קודם) קל לארגן דפים בעזרת אוספים אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.

פרטי המקום

Kotlin

Java

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

Kotlin

Java

אחזור מקום לפי מזהה

Kotlin

Java

קבלת סטטוס פתוח

Kotlin

Java

Kotlin

Java

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

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

פרטי המקום (דור קודם)