המיקום הנוכחי (דור קודם)

מפתחים באזור הכלכלי האירופי (EEA)

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

השדות תואמים לתוצאות של חיפוש מקומות, והם מחולקים לשלוש קטגוריות חיוב: Basic,‏ Contact ו-Atmosphere. שדות בסיסיים מחויבים בתעריף הבסיס, ללא חיובים נוספים. השדות "פרטים ליצירת קשר" ו"אווירה" מחויבים בתעריף גבוה יותר. למידע נוסף על החיוב של בקשות נתונים של Place, קראו את המאמר שימוש וחיוב.

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

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

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

Kotlin

// Use fields to define the data types to return.
val placeFields = listOf(Place.Field.DISPLAY_NAME, Place.Field.FORMATTED_ADDRESS, Place.Field.LOCATION)

// Define the search area around the current location (500m radius).
val currentLocation = LatLng(37.4220, -122.0841)
val circle = CircularBounds.newInstance(currentLocation, 500.0)
val request = SearchNearbyRequest.builder(circle, placeFields)
    .setMaxResultCount(20)
    .build()

// Call searchNearby and handle the response (first check that the user has granted permission).
if (ContextCompat.checkSelfPermission(this, permission.ACCESS_FINE_LOCATION) ==
    PackageManager.PERMISSION_GRANTED
) {
    placesClient.searchNearby(request).addOnSuccessListener { response ->
        binding.progressBar.visibility = View.GONE
        adapter.setPlaces(response.places)
    }.addOnFailureListener { exception ->
        binding.progressBar.visibility = View.GONE
        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 =
        Arrays.asList(
                Place.Field.DISPLAY_NAME,
                Place.Field.FORMATTED_ADDRESS,
                Place.Field.LOCATION);

// Define the search area around the current location.
LatLng currentLocation = new LatLng(37.4220, -122.0841);
LocationRestriction circle =
        CircularBounds.newInstance(currentLocation, /* radius= */ 500.0);

// Use the builder to create a SearchNearbyRequest.
SearchNearbyRequest request =
        SearchNearbyRequest.builder(circle, placeFields).setMaxResultCount(20).build();

// Call searchNearby and handle the response (first check that the user has granted
// permission).
if (ContextCompat.checkSelfPermission(this, ACCESS_FINE_LOCATION)
        == PackageManager.PERMISSION_GRANTED) {
    Task<SearchNearbyResponse> placeResponse = placesClient.searchNearby(request);
    placeResponse.addOnCompleteListener(
            task -> {
                binding.progressBar.setVisibility(View.GONE);
                if (task.isSuccessful()) {
                    SearchNearbyResponse response = task.getResult();
                    adapter.setPlaces(response.getPlaces());
                } else {
                    Exception exception = task.getException();
                    if (exception instanceof ApiException apiException) {
                        Log.e(
                                "CurrentPlace",
                                "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). למידע נוסף על מאפיינים