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

פרטי מקומות

בחירת פלטפורמה: 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);

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

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

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

הערה : השיטה הזו הוצאה משימוש. במקום זאת, יש להשתמש ב- 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:

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

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

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

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

לכל מקום אפשר לשייך ערך type אחד או יותר. Places SDK עבור Android בגרסה 3.3.0 מוסיף ערכי סוגים חדשים רבים. הרשימה המלאה מופיעה במאמר סוגי מקומות מורחבים.

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

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

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

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

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

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

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

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

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

מפעילים את ה-SDK החדש כשמגדירים את הפרויקט ב-Google Cloud.
מפעילים את ה-SDK החדש בתוך פעילות או מקטע (fragment).
יש לכלול את Place.Field.REVIEWS ברשימת השדות של הבקשה לפרטי המקום.
התקשרות אל PlacesClient.fetchPlace(). השדה של הביקורות לא נתמך על ידי PlacesClient.findCurrentPlace().
משתמשים בשיטה Place.getReviews() כדי לגשת לשדה של נתוני הביקורות באובייקט Place.

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

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

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

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

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

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

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

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

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

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

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

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