פרטי מקומות

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

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

פרטי המקום

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

• שיחת טלפון PlacesClient.fetchPlace() – יש לעיין במדריך כדי קבלת מקום לפי מזהה.
• שיחת טלפון PlacesClient.findCurrentPlace() – יש לעיין במדריך כדי לקבל את המקום הנוכחי.
  בזמן PlacesClient.fetchPlace() תומך בכל השדות של נתוני המקום, PlacesClient.findCurrentPlace() תומכת רק בקבוצת משנה של שדות נתוני מקום. לרשימת השדות שלא שנתמך על ידי findCurrentPlace(): תמיכה בשדות של Places 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. ריכזנו כאן דוגמאות לכמה מהשיטות הזמינות. לרשימה מלאה של כל השיטות אפשר לעיין Place הפניית API.

• 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();

      

חיפוש מקום לפי תעודה מזהה

מזהה מקום הוא מזהה טקסטואלי שמזהה מקום באופן ייחודי. לחשבון 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 זמין כאן מפעילים את לקוח Places API.

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

הערה: מקומות מק"ט נתונים בסיסי מחויב על שיחות אל 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());
            // ...
        });
// ...

      

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

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

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

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

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

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