פרטי מקומות

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

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

פרטי המקום

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

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

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

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

Java

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

Kotlin

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

אחרי שמקבלים את האובייקט Place, משתמשים בשיטות של האובייקט כדי לגשת לשדות הנתונים שצוינו בבקשה. אם השדה חסר באובייקט Place, השיטה הקשורה תחזיר את הערך null. בהמשך ריכזנו כמה דוגמאות לכמה מהשיטות הזמינות. לרשימה המלאה של כל השיטות, קראו את Place ממשק ה-API.

  • 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 עם פרטי המקום.

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

Java


final CharSequence name = place.getName();
final CharSequence address = place.getAddress();
final LatLng location = place.getLatLng();

Kotlin


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

מציאת מקום לפי מזהה

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

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

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

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

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

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

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

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

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

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

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

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

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

הצגת ייחוסים באפליקציה

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

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

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

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

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