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

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

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

קבלת המיקום הנוכחי

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

  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). אפשר לעיין במסמכי התיעוד בנושא שיוך (Attribution).