مکان فعلی

پلتفرم را انتخاب کنید: 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 دریافت کنید.

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

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

API یک FindCurrentPlaceResponse را در یک Task برمی گرداند. FindCurrentPlaceResponse حاوی لیستی از اشیاء PlaceLikelihood است که نشان دهنده مکان هایی است که احتمالاً دستگاه در آنجا قرار دارد. برای هر مکان، نتیجه شامل نشانه ای از احتمال درست بودن مکان است. اگر مکان شناخته شده ای مطابق با مکان دستگاه داده شده وجود نداشته باشد، ممکن است لیست خالی باشد.

برای بازیابی یک شی Place می توانید PlaceLikelihood.getPlace() و برای دریافت رتبه احتمال مکان PlaceLikelihood.getLikelihood() را فراخوانی کنید. مقدار بالاتر به معنای احتمال بیشتر است که مکان بهترین تطابق است.

نمونه کد زیر فهرستی از مکان‌هایی را بازیابی می‌کند که احتمالاً دستگاه در آن‌ها قرار دارد، و نام و احتمال هر مکان را ثبت می‌کند.

کاتلین

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

      

جاوا

// 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٪ که مکان صحیح مکان A است، و احتمال 35٪ که مکان B است، پاسخ دارای دو عضو است، مکان A با احتمال 0.55 و مکان B با احتمال 0.35.

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

می‌توانید از CancellationToken برای لغو درخواست برای هر یک از کلاس‌های درخواست (مثلا FetchPlaceRequest ) استفاده کنید. لغو بر اساس بهترین تلاش انجام می شود. پس از صدور درخواست لغو، هیچ پاسخی عودت داده نخواهد شد. صدور رمز لغو تضمین نمی کند که یک درخواست خاص لغو شود، و حتی اگر پاسخی برگردانده نشود، همچنان ممکن است برای درخواست هزینه از شما کسر شود .

اسناد را در برنامه خود نمایش دهید

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