פרטי מקומות

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

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

פרטי המקום

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

• התקשרות PlacesClient.fetchPlace() – אפשר לעיין במדריך לקבלת מקום לפי מזהה.
• התקשרות PlacesClient.findCurrentPlace() – כדאי לעיין במדריך לאיתור המקום הנוכחי.
  בעוד שב-PlacesClient.fetchPlace() יש תמיכה בכל השדות של נתוני מקום, PlacesClient.findCurrentPlace() תומך רק בקבוצת משנה של שדות של נתוני מקום. לרשימת השדות שלא נתמכים ב-findCurrentPlace(), ראו תמיכה בשדות Places SDK for 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 placeFields = Arrays.asList(Place.Field.NAME, Place.Field.RATING, Place.Field.OPENING_HOURS);

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

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

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

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

• getOpeningHours() – OpeningHours של המקום. הפונקציה OpeningHours.getWeekdayText() מחזירה רשימה של מחרוזות שמייצגות שעות פתיחה וסגירה בכל יום בשבוע. קריאה ל-OpeningHours.getPeriods() כדי להחזיר רשימה של אובייקטים מסוג period עם מידע מפורט יותר התואם לנתונים שסופקו על ידי getWeekdayText().

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

  האובייקט Place מכיל גם את השיטה getCurrentOpeningHours() שמחזירה את שעות הפעילות של מקום מסוים במהלך שבעת הימים הבאים, ואת השיטה 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();

      

גישה לנתוני מקום שנוספו בגרסה 3.3.0

Places SDK ל-Android בגרסה 3.3.0 מוסיף נתונים חדשים ל-Place:

• סוגי מקומות: ערכים חדשים של סוגים שמשויכים למקום.
• ביקורות: עד חמש ביקורות על מקום.
• קוד השפה של השם: קוד השפה של השם של המקום.

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

בקטעים הבאים מתואר איך לגשת לנתונים החדשים האלה.

הערה: ה-SDK החדש תומך רק בנתונים החדשים של Place ב-Java.

גישה לסוגי מקומות חדשים

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

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

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

השיטה Place.getPlaceTypes() מחזירה את ערכי הסוג כרשימה של ערכי מחרוזת. הערכים שמוחזרים תלויים בגרסה של Places SDK ל-Android:

• Places SDK ל-Android (חדש): מחזירה את המחרוזות שהוגדרו על ידי טבלה א' וטבלה ב' ומוצגות בסוגי מקומות (חדש), כולל כל סוגי המקומות שנוספו בגרסה 3.3.0.
• Places SDK for Android: מחזירה את ה-enums שהוגדר על ידי Place.Types, לא כולל את הסוגים החדשים שנוספו בגרסה 3.3.0.

במאמר בחירת גרסת ה-SDK מוסבר מה ההבדלים העיקריים בין שתי גרסאות ה-SDK.

גישה לביקורות על מקומות

Places SDK ל-Android (חדש) מוסיף את המחלקה Review, שמכילה ביקורת על מקום. האובייקט Place יכול להכיל עד חמש ביקורות.

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

כדי לאכלס את האובייקט Place בביקורות, צריך:

1. מפעילים את ה-SDK החדש בזמן הגדרת הפרויקט ב-Google Cloud.
2. מפעילים את ה-SDK החדש בתוך פעילות או מקטע.
3. כוללים את Place.Field.REVIEWS בשדה הבקשה של פרטי המקום.
4. קוראים לפונקציה PlacesClient.fetchPlace(). השדה 'ביקורות' לא נתמך על ידי PlacesClient.findCurrentPlace().
5. משתמשים בשיטה Place.getReviews() כדי לגשת לשדה של נתוני הביקורות באובייקט Place.

גישה לקוד השפה של שם המקום

השיטה הקיימת Place.getName() מחזירה מחרוזת טקסט שמכילה את שם המקום. כדי לאכלס את האובייקט Place עם שם המקום, צריך לכלול את Place.Field.NAME ברשימת השדות של הבקשה לפרטי המקום.

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

1. מפעילים את ה-SDK החדש בזמן הגדרת הפרויקט ב-Google Cloud.
2. מפעילים את ה-SDK החדש בתוך פעילות או מקטע.
3. כוללים את Place.Field.NAME ברשימת השדות של הבקשה. הערך הזה מגדיר את התגובה כך שתכלול גם את שם המקום וגם את קוד השפה באובייקט Place.
4. קוראים לפונקציה PlacesClient.fetchPlace(). הפונקציה PlacesClient.findCurrentPlace() לא תומכת בשדה של קוד השפה.
5. משתמשים ב-method Place.getNameLanguageCode() כדי לגשת לשדה של קוד השפה באובייקט Place.

הגדרת קוד האזור בגרסה 3.3.0

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

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

רוב קודי ה-CLDR זהים לקודי ISO 3166-1, למעט כמה יוצאים מן הכלל. לדוגמה, שם הדומיין ברמה העליונה של בריטניה הוא "uk" (co.uk). קוד ISO 3166-1 הוא "gb" (המונח הטכני הוא "בריטניה" וצפון אירלנד). הפרמטר יכול להשפיע על התוצאות בהתאם לדין החל.

קבלת מקום לפי מזהה

מזהה מקום הוא מזהה טקסט שמזהה מקום באופן ייחודי. ב-Place 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.
    }
});

      

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

הצגת הסטטוס 'פתוח'

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

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

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

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