‫Google برای ترجمه محتوا به زبان ترجیحی شما از فناوری هوشواره استفاده می‌کند. ترجمه‌های هوشواره‌ای ممکن است اشتباه داشته باشند.

مکان کنونی (قدیمی)

توسعه‌دهندگان منطقه اقتصادی اروپا (EEA)

منسوخ‌شده: روش PlacesClient.findCurrentPlace() منسوخ شده است. درعوض از PlacesClient.searchNearby() استفاده کنید. توجه داشته باشید که برای استفاده از PlacesClient.searchNearby()، باید Places API (جدید) را در کلید میانای برنامه‌سازی کاربردی خود در کنسول Google Cloud فعال کنید.

بااستفاده از Places SDK for 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 را مدنظر قرار دهید.

دریافت مکان کنونی

برای پیدا کردن کسب‌وکار محلی یا مکان دیگری که دستگاه درحال‌حاضر در آنجا قرار دارد، این مراحل را دنبال کنید:

ContextCompat.checkSelfPermission را فراخوانی کنید تا بررسی کنید آیا کاربر اجازه دسترسی به مکان دستگاهش را اعطا کرده است یا نه. برنامه شما باید حاوی کدی باشد که از کاربر درخواست اجازه کند و نتیجه را مدیریت کند. برای جزئیات، به درخواست اجازه‌های برنامه مراجعه کنید.
FindCurrentPlaceRequest ایجاد کنید، List از Place.Field را ارسال کنید، و انواع داده‌های مکانی را که برنامه‌تان باید درخواست کند مشخص کنید.
PlacesClient.findCurrentPlace() را فراخوانی کنید، FindCurrentPlaceRequest را که در مرحله قبلی ایجاد کردید ارسال کنید.
فهرست PlaceLikelihood را از FindCurrentPlaceResponse دریافت کنید.

توجه: درحالی‌که PlacesClient.fetchPlace() از همه جزئیات مکان پشتیبانی می‌کند، PlacesClient.findCurrentPlace() فقط از زیرمجموعه‌ای از جزئیات مکان پشتیبانی می‌کند. برای مشاهده فهرست فیلدهایی که findCurrentPlace() از آن‌ها پشتیبانی نمی‌کند، پشتیبانی فیلدهای کیت توسعه نرم‌افزار مکان‌ها برای Android را ببینید.

فیلدها با نتایج «جستجوی جاها» مطابقت دارند و به سه دسته صورت‌حساب تقسیم می‌شوند: «پایه»، «مخاطب»، و «جو». فیلدهای پایه با نرخ پایه صورت‌حساب می‌شوند و هزینه اضافی ندارند. فیلدهای «تماس» و «جو» با نرخ بالاتری صورت‌حساب می‌شوند. برای اطلاعات بیشتر درباره نحوه صدور صورت‌حساب برای درخواست‌های داده‌های «مکان»، به استفاده و صدور صورت‌حساب مراجعه کنید.

این 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()
}

جاوا

// 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();
}

نکاتی درباره مقادیر احتمال:

احتمال، احتمال نسبی بهترین مطابقت بودن مکان را در فهرست مکان‌های برگردانده‌شده برای یک درخواست ارائه می‌دهد. نمی‌توانید احتمال‌ها را در درخواست‌های مختلف مقایسه کنید.
مقدار احتمال بین ۰٫۰ و ۱٫۰ خواهد بود.

برای مثال، برای نشان دادن احتمال ۵۵٪ برای اینکه مکان صحیح «مکان الف» است، و احتمال ۳۵٪ برای اینکه «مکان ب» است، پاسخ دو عضو دارد: «مکان الف» با احتمال ۰٫۵۵ و «مکان ب» با احتمال ۰٫۳۵.

توجه: برای اطلاعات بیشتر درباره مقداردهی اولیه PlacesClient، به مقداردهی اولیه کارخواه Places API مراجعه کنید.

نمایش ارجاع‌ها در برنامه

وقتی برنامه‌تان اطلاعات به‌دست‌آمده از PlacesClient.findCurrentPlace() را نمایش می‌دهد، برنامه باید ارجاع‌ها را نیز نمایش دهد. مستندات مربوط به ارجاع‌ها را ببینید.