הדור הבא של Places SDK עבור Android זמין עכשיו עם המהדורה של Places SDK ל-Android (חדש).

דף זה תורגם על ידי Cloud Translation API.

פרטי מקומות

בחירת פלטפורמה: Android iOS JavaScript שירות אינטרנט

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

פרטי המקום

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

התקשרות PlacesClient.fetchPlace() – אפשר לעיין במדריך לקבלת מקום לפי תעודה מזהה.
התקשרות PlacesClient.findCurrentPlace() – אפשר לעיין במדריך איך מוצאים את המקום הנוכחי.
PlacesClient.fetchPlace() תומך בכל השדות של נתוני מקומות, אבל PlacesClient.findCurrentPlace() תומך רק בקבוצת משנה של שדות של נתוני מקומות. רשימת השדות שלא נתמכים על ידי findCurrentPlace() מופיעה במאמר תמיכה בשדות של SDK של מקומות ב-Android.

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

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

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

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

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

כמה דוגמאות פשוטות:

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, תוכלו לקרוא את המאמר הפעלת לקוח ה-API של המקומות.

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

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

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

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

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

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

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