פרטי מקום

בחירת פלטפורמה: Android iOS JavaScript Web Service

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

פרטי המקום

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

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

לשיטה הזו יש ארגומנטים יחידים מסוג 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():

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

      

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

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

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

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

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

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