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

באמצעות 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>

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

אחזור המיקום הנוכחי

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

  1. קוראים לפונקציה ContextCompat.checkSelfPermission כדי לבדוק אם המשתמש העניק הרשאה לגשת למיקום שלו במכשיר. האפליקציה צריכה לכלול גם קוד לבקשת הרשאה מהמשתמש ולטיפול בתוצאה. פרטים נוספים זמינים במאמר בקשת הרשאות לאפליקציה.
  2. יוצרים FindCurrentPlaceRequest, מעבירים List של Place.Fields ומציינים את סוגי נתוני המיקום שהאפליקציה צריכה לבקש.
  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). מידע נוסף זמין במאמר בנושא שיוך.