המיקום הנוכחי

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

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

הרשאות

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

אם באפליקציה לא נעשה שימוש ב-PlacesClient.findCurrentPlace(), צריך להסיר באופן מפורש את ההרשאות ACCESS_FINE_LOCATION ו-ACCESS_COARSE_LOCATION שנוספו על ידי הספרייה, על ידי הוספת הפרטים הבאים למניפסט: 

<manifest ... xmlns:tools="http://schemas.android.com/tools">
    ...
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" tools:node="remove"/>
    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" tools:node="remove"/>
    ...
</manifest>

אפשר לקרוא מידע נוסף על הרשאות ולשקול להשתמש ב הרשאות קלות כדי להתחיל.

הצגת המיקום הנוכחי

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

  1. אפשר להתקשר אל ContextCompat.checkSelfPermission כדי לבדוק אם המשתמש העניק הרשאה לגשת למיקום של המכשיר. האפליקציה צריכה לכלול גם קוד שיבקש מהמשתמש הרשאה ולטפל בתוצאה. לפרטים נוספים, ראו בקשת הרשאות לאפליקציה.
  2. יוצרים FindCurrentPlaceRequest, ומעבירים List של Place.Field, כדי לציין את סוגי נתוני המקום שהאפליקציה צריכה לבקש.
  3. קוראים לפונקציה PlacesClient.findCurrentPlace() ומעבירים את הערך FindCurrentPlaceRequest שיצרתם בשלב הקודם.
  4. אפשר לקבל את הרשימה של PlaceLikelihood ב-FindCurrentPlaceResponse.

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

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

אפשר להפעיל את הפונקציה PlaceLikelihood.getPlace() כדי לאחזר אובייקט Place, וגם PlaceLikelihood.getLikelihood() כדי לקבל את דירוג הסבירות של המקום. ערך גבוה יותר פירושו יותר סבירות שהמקום הוא ההתאמה הטובה ביותר.

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

Kotlin



// Use fields to define the data types to return.
val placeFields: List<Place.Field> = listOf(Place.Field.NAME)

// Use the builder to create a FindCurrentPlaceRequest.
val request: FindCurrentPlaceRequest = FindCurrentPlaceRequest.newInstance(placeFields)

// Call findCurrentPlace and handle the response (first check that the user has granted permission).
if (ContextCompat.checkSelfPermission(this, permission.ACCESS_FINE_LOCATION) ==
    PackageManager.PERMISSION_GRANTED) {

    val placeResponse = placesClient.findCurrentPlace(request)
    placeResponse.addOnCompleteListener { task ->
        if (task.isSuccessful) {
            val response = task.result
            for (placeLikelihood: PlaceLikelihood in response?.placeLikelihoods ?: emptyList()) {
                Log.i(
                    TAG,
                    "Place '${placeLikelihood.place.name}' has likelihood: ${placeLikelihood.likelihood}"
                )
            }
        } else {
            val exception = task.exception
            if (exception is ApiException) {
                Log.e(TAG, "Place not found: ${exception.statusCode}")
            }
        }
    }
} else {
    // A local method to request required permissions;
    // See https://developer.android.com/training/permissions/requesting
    getLocationPermission()
}

Java


// Use fields to define the data types to return.
List<Place.Field> placeFields = Collections.singletonList(Place.Field.NAME);

// Use the builder to create a FindCurrentPlaceRequest.
FindCurrentPlaceRequest request = FindCurrentPlaceRequest.newInstance(placeFields);

// Call findCurrentPlace and handle the response (first check that the user has granted permission).
if (ContextCompat.checkSelfPermission(this, ACCESS_FINE_LOCATION) == PackageManager.PERMISSION_GRANTED) {
    Task<FindCurrentPlaceResponse> placeResponse = placesClient.findCurrentPlace(request);
    placeResponse.addOnCompleteListener(task -> {
        if (task.isSuccessful()){
            FindCurrentPlaceResponse response = task.getResult();
            for (PlaceLikelihood placeLikelihood : response.getPlaceLikelihoods()) {
                Log.i(TAG, String.format("Place '%s' has likelihood: %f",
                    placeLikelihood.getPlace().getName(),
                    placeLikelihood.getLikelihood()));
            }
        } else {
            Exception exception = task.getException();
            if (exception instanceof ApiException) {
                ApiException apiException = (ApiException) exception;
                Log.e(TAG, "Place not found: " + apiException.getStatusCode());
            }
        }
    });
} else {
    // A local method to request required permissions;
    // See https://developer.android.com/training/permissions/requesting
    getLocationPermission();
}

הערות לגבי ערכי הסבירות:

  • הסבירות מספקת את ההסתברות היחסית שהמקום הוא ההתאמה הטובה ביותר ברשימת המקומות שהוחזרו לבקשה אחת. לא ניתן להשוות בין הסבירות של בקשות שונות.
  • ערך הסבירות יהיה בין 0.0 ל-1.0.

לדוגמה, כדי לייצג סבירות של 55% שהמקום הנכון הוא מקום א' וסבירות של 35% שהוא מקום ב', התשובה מכילה שני חברים, מקום א' עם הסבירות 0.55 ומקום ב' עם הסבירות 0.35.

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

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