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

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