کیت توسعه نرمافزاری مکانها برای اندروید (Legacy) اطلاعات غنی در مورد مکانها، از جمله نام و آدرس مکان، موقعیت جغرافیایی مشخص شده به صورت مختصات عرض/طول جغرافیایی، نوع مکان (مانند کلوپ شبانه، فروشگاه حیوانات خانگی، موزه) و موارد دیگر را در اختیار برنامه شما قرار میدهد. برای دسترسی به این اطلاعات برای یک مکان خاص، میتوانید از شناسه مکان، یک شناسه پایدار که به طور منحصر به فرد یک مکان را مشخص میکند، استفاده کنید.
جزئیات مکان
شیء Place اطلاعاتی در مورد یک مکان خاص ارائه میدهد. میتوانید با فراخوانی PlacesClient.fetchPlace() به یک شیء Place دسترسی پیدا کنید - به راهنمای دریافت یک مکان بر اساس ID مراجعه کنید.
وقتی مکانی را درخواست میکنید، باید مشخص کنید که کدام دادههای مکانی را میخواهید برگردانید. برای انجام این کار، لیستی از مقادیر Place.Field را که دادههایی را که باید برگردانید مشخص میکنند، ارسال کنید. این لیست یک ملاحظه مهم است زیرا بر هزینه هر درخواست تأثیر میگذارد.
از آنجا که نتایج داده مکان نمیتوانند خالی باشند، فقط نتایج مکان دارای داده بازگردانده میشوند. برای مثال، اگر مکان درخواستی هیچ عکسی نداشته باشد، فیلد photos در نتیجه وجود نخواهد داشت.
مثال زیر لیستی از سه مقدار Place.Field را برای مشخص کردن دادههای برگردانده شده توسط یک درخواست ارسال میکند:
کاتلین
// Specify the fields to return. val placeFields = listOf(Place.Field.DISPLAY_NAME, Place.Field.RATING)
جاوا
// Specify the fields to return. final List<Place.Field> placeFields = Arrays.asList(Place.Field.DISPLAY_NAME, Place.Field.RATING);
دسترسی به فیلدهای داده شیء Place
پس از دریافت شیء Place ، از متدهای شیء برای دسترسی به فیلدهای داده مشخص شده در درخواست استفاده کنید. اگر فیلد از شیء Place وجود نداشته باشد، متد مرتبط مقدار null را برمیگرداند. در زیر نمونههایی از چند متد موجود نشان داده شده است.
-
getAddress()– آدرس مکان، به فرمت قابل خواندن توسط انسان. -
getAddressComponents()–Listاز اجزای آدرس برای این مکان. این اجزا به منظور استخراج اطلاعات ساختاریافته در مورد آدرس یک مکان، به عنوان مثال یافتن شهری که یک مکان در آن واقع شده است، ارائه شدهاند. از این اجزا برای قالببندی آدرس استفاده نکنید؛ در عوض،getAddress()را فراخوانی کنید، که یک آدرس قالببندی شده محلی ارائه میدهد. -
getId()– شناسه متنی برای مکان. برای اطلاعات بیشتر در مورد شناسههای مکان به ادامه این صفحه مراجعه کنید. -
getLatLng()– موقعیت جغرافیایی مکان، که به صورت مختصات طول و عرض جغرافیایی مشخص شده است. -
getName()– نام مکان. getOpeningHours()–OpeningHoursمکان. برای برگرداندن لیستی از رشتهها که نشاندهنده ساعات باز و بسته شدن برای هر روز هفته هستند،OpeningHours.getWeekdayText()را فراخوانی کنید. برای برگرداندن لیستی از اشیاءperiodبا اطلاعات دقیقتر که معادل دادههای ارائه شده توسطgetWeekdayText()استOpeningHours.getPeriods()را فراخوانی کنید.شیء
Placeهمچنین شامل متدgetCurrentOpeningHours()است که ساعات کاری یک مکان را در هفت روز آینده برمیگرداند، وgetSecondaryOpeningHours()که ساعات کاری ثانویه یک مکان را در هفت روز آینده برمیگرداند.isOpen()– یک مقدار بولی که نشان میدهد آیا مکان در حال حاضر باز است یا خیر. اگر زمانی مشخص نشود، مقدار پیشفرض now است.isOpenفقط در صورتی برگردانده میشود که هر دوPlace.Field.UTC_OFFSETوPlace.Field.OPENING_HOURSدر دسترس باشند. برای اطمینان از نتایج دقیق، فیلدهایPlace.Field.BUSINESS_STATUSوPlace.Field.UTC_OFFSETرا در درخواست مکان اصلی خود درخواست کنید. در صورت عدم درخواست، فرض بر این است که کسب و کار فعال است. برای نحوه استفاده ازisOpenبا Place Details، به این ویدیو مراجعه کنید.
چند مثال:
کاتلین
val name = place.displayName val address = place.formattedAddress val location = place.location
جاوا
final CharSequence name = place.getDisplayName(); final CharSequence address = place.getFormattedAddress(); final LatLng location = place.getLocation();
با استفاده از شناسه، مکانی را دریافت کنید
شناسه مکان یک شناسه متنی است که به طور منحصر به فرد یک مکان را مشخص میکند. در Places SDK برای اندروید، میتوانید شناسه یک مکان را با فراخوانی Place.getId() بازیابی کنید. سرویس تکمیل خودکار مکان همچنین برای هر مکانی که با عبارت جستجو و فیلتر ارائه شده مطابقت دارد، یک شناسه مکان برمیگرداند. میتوانید شناسه مکان را ذخیره کرده و بعداً از آن برای بازیابی مجدد شیء Place استفاده کنید.
برای دریافت یک مکان بر اساس شناسه (ID)، تابع PlacesClient.fetchPlace() را فراخوانی کنید و یک FetchPlaceRequest ارسال کنید.
این API یک FetchPlaceResponse در یک Task برمیگرداند. FetchPlaceResponse شامل یک شیء Place است که با شناسه مکان ارائه شده مطابقت دارد.
مثال کد زیر فراخوانی تابع fetchPlace() را برای دریافت جزئیات مکان مشخص شده نشان میدهد.
کاتلین
// Define a Place ID. val placeId = PlaceIdProvider.getRandomPlaceId() // Specify the fields to return. val placeFields = listOf( Place.Field.ID, Place.Field.DISPLAY_NAME, Place.Field.FORMATTED_ADDRESS, Place.Field.LOCATION ) // Construct a request object, passing the place ID and fields array. val request = FetchPlaceRequest.newInstance(placeId, placeFields) placesClient.fetchPlace(request) .addOnSuccessListener { response: FetchPlaceResponse -> val place = response.place val name = place.displayName val address = place.formattedAddress val location = place.location binding.placeName.text = name binding.placeAddress.text = address if (location != null) { binding.placeLocation.text = getString( R.string.place_location, location.latitude, location.longitude ) } else { binding.placeLocation.text = null } Log.i(TAG, "Place found: ${place.displayName}") }.addOnFailureListener { exception: Exception -> if (exception is ApiException) { val message = getString(R.string.place_not_found, exception.message) binding.placeName.text = message Log.e(TAG, "Place not found: ${exception.message}") val statusCode = exception.statusCode TODO("Handle error with given status code") } }
جاوا
// Define a Place ID. final String placeId = PlaceIdProvider.getRandomPlaceId(); // Specify the fields to return. final List<Place.Field> placeFields = Arrays.asList( Place.Field.ID, Place.Field.DISPLAY_NAME, Place.Field.FORMATTED_ADDRESS, Place.Field.LOCATION ); // Construct a request object, passing the place ID and fields array. final FetchPlaceRequest request = FetchPlaceRequest.newInstance(placeId, placeFields); placesClient.fetchPlace(request).addOnSuccessListener((response) -> { Place place = response.getPlace(); final CharSequence name = place.getDisplayName(); final CharSequence address = place.getFormattedAddress(); final LatLng location = place.getLocation(); binding.placeName.setText(name); binding.placeAddress.setText(address); if (location != null) { binding.placeLocation.setText( getString(R.string.place_location, location.latitude, location.longitude) ); } else { binding.placeLocation.setText(null); } Log.i(TAG, "Place found: " + place.getDisplayName()); }).addOnFailureListener((exception) -> { if (exception instanceof ApiException apiException) { final String message = getString(R.string.place_not_found, apiException.getMessage()); binding.placeName.setText(message); Log.e(TAG, "Place not found: " + exception.getMessage()); final int statusCode = apiException.getStatusCode(); // TODO: Handle error with given status code. } });
دریافت وضعیت باز بودن
متد PlacesClient.isOpen(IsOpenRequest request) یک شیء IsOpenResponse را برمیگرداند که نشان میدهد آیا مکان مورد نظر بر اساس زمان مشخص شده در فراخوانی، در حال حاضر باز است یا خیر.
این متد یک آرگومان از نوع IsOpenRequest دریافت میکند که شامل موارد زیر است:
- یک شیء
Place، یا رشتهای که شناسه مکان را مشخص میکند. - یک مقدار زمانی اختیاری که زمان را بر حسب میلیثانیه از تاریخ 1970-01-01T00:00:00Z مشخص میکند. اگر زمانی مشخص نشود، مقدار پیشفرض «اکنون» است.
این روش مستلزم آن است که فیلدهای زیر در شیء Place وجود داشته باشند:
-
Place.Field.BUSINESS_STATUS -
Place.Field.CURRENT_OPENING_HOURS -
Place.Field.OPENING_HOURS -
Place.Field.UTC_OFFSET
اگر این فیلدها در شیء Place ارائه نشده باشند، یا اگر یک شناسه مکان ارسال کنید، متد PlacesClient.fetchPlace() برای واکشی آنها استفاده میکند. برای اطلاعات بیشتر در مورد ایجاد شیء Place با فیلدهای لازم، به Place details مراجعه کنید.
مثال زیر تعیین میکند که آیا یک مکان در حال حاضر باز است یا خیر. در این مثال، شما فقط شناسه مکان را به isOpen() ارسال میکنید:
کاتلین
val isOpenCalendar: Calendar = Calendar.getInstance() val placeId = PlaceIdProvider.getRandomPlaceId() val request: IsOpenRequest = try { IsOpenRequest.newInstance(placeId, isOpenCalendar.timeInMillis) } catch (e: IllegalArgumentException) { Log.e("PlaceIsOpen", "Error: " + e.message) return } val isOpenTask: Task<IsOpenResponse> = placesClient.isOpen(request) isOpenTask.addOnSuccessListener { response -> val isOpen = response.isOpen ?: false binding.isOpenByIdResult.text = getString(R.string.is_open_by_id, isOpen.toString()) Log.d("PlaceIsOpen", "Is open by ID: $isOpen") } // ...
جاوا
@NonNull Calendar isOpenCalendar = Calendar.getInstance(); String placeId = PlaceIdProvider.getRandomPlaceId(); IsOpenRequest isOpenRequest; try { isOpenRequest = IsOpenRequest.newInstance(placeId, isOpenCalendar.getTimeInMillis()); } catch (IllegalArgumentException e) { Log.e("PlaceIsOpen", "Error: " + e.getMessage()); return; } Task<IsOpenResponse> placeTask = placesClient.isOpen(isOpenRequest); placeTask.addOnSuccessListener( (response) -> { final boolean isOpen = Boolean.TRUE.equals(response.isOpen()); binding.isOpenByIdResult.setText(getString(R.string.is_open_by_id, String.valueOf(isOpen))); Log.d("PlaceIsOpen", "Is open by ID: " + isOpen); }); placeTask.addOnFailureListener((exception) -> { binding.isOpenByIdResult.setText(getString(R.string.is_open_by_id, "Error: " + exception.getMessage())); Log.e("PlaceIsOpen", "Error: " + exception.getMessage()); });
مثال بعدی فراخوانی isOpen() را در جایی که یک شیء Place ارسال میکنید، نشان میدهد. شیء Place باید حاوی یک شناسه مکان معتبر باشد:
کاتلین
val isOpenCalendar: Calendar = Calendar.getInstance() var place: Place val placeId = PlaceIdProvider.getRandomPlaceId() // Specify the required fields for an isOpen request. val placeFields: List<Place.Field> = listOf( Place.Field.BUSINESS_STATUS, Place.Field.CURRENT_OPENING_HOURS, Place.Field.ID, Place.Field.OPENING_HOURS, Place.Field.DISPLAY_NAME ) val placeRequest: FetchPlaceRequest = FetchPlaceRequest.newInstance(placeId, placeFields) val placeTask: Task<FetchPlaceResponse> = placesClient.fetchPlace(placeRequest) placeTask.addOnSuccessListener { placeResponse -> place = placeResponse.place val isOpenRequest: IsOpenRequest = try { IsOpenRequest.newInstance(place, isOpenCalendar.timeInMillis) } catch (e: IllegalArgumentException) { Log.e("PlaceIsOpen", "Error: " + e.message) return@addOnSuccessListener } val isOpenTask: Task<IsOpenResponse> = placesClient.isOpen(isOpenRequest) isOpenTask.addOnSuccessListener { isOpenResponse -> val isOpen = when (isOpenResponse.isOpen) { true -> getString(R.string.is_open) else -> getString(R.string.is_closed) } binding.isOpenByObjectResult.text = getString( R.string.is_open_by_object, place.displayName, isOpen ) Log.d("PlaceIsOpen", "Is open by object: $isOpen") } // ... } // ...
جاوا
@NonNull Calendar isOpenCalendar = Calendar.getInstance(); String placeId = PlaceIdProvider.getRandomPlaceId(); // Specify the required fields for an isOpen request. List<Place.Field> placeFields = new ArrayList<>(Arrays.asList( Place.Field.BUSINESS_STATUS, Place.Field.CURRENT_OPENING_HOURS, Place.Field.ID, Place.Field.OPENING_HOURS, Place.Field.DISPLAY_NAME )); FetchPlaceRequest request = FetchPlaceRequest.newInstance(placeId, placeFields); Task<FetchPlaceResponse> placeTask = placesClient.fetchPlace(request); placeTask.addOnSuccessListener( (placeResponse) -> { Place place = placeResponse.getPlace(); IsOpenRequest isOpenRequest; try { isOpenRequest = IsOpenRequest.newInstance(place, isOpenCalendar.getTimeInMillis()); } catch (IllegalArgumentException e) { Log.e("PlaceIsOpen", "Error: " + e.getMessage()); return; } Task<IsOpenResponse> isOpenTask = placesClient.isOpen(isOpenRequest); isOpenTask.addOnSuccessListener( (isOpenResponse) -> { final boolean isOpen = Boolean.TRUE.equals(isOpenResponse.isOpen()); binding.isOpenByObjectResult.setText(getString(R.string.is_open_by_object, place.getDisplayName(), String.valueOf(isOpen))); Log.d("PlaceIsOpen", "Is open by object: " + isOpen); }); isOpenTask.addOnFailureListener( (exception) -> { // also update the result text field binding.isOpenByObjectResult.setText(getString(R.string.is_open_by_object, place.getDisplayName(), "Error: " + exception.getMessage())); Log.e("PlaceIsOpen", "Error: " + exception.getMessage()); }); }); placeTask.addOnFailureListener( (exception) -> { binding.isOpenByObjectResult.setText("Error: " + exception.getMessage()); Log.e("PlaceIsOpen", "Error: " + exception.getMessage());
نمایش انتسابها در برنامه شما
وقتی برنامه شما اطلاعات مکان، از جمله نقد و بررسی مکان را نمایش میدهد، برنامه باید هرگونه انتساب را نیز نمایش دهد. برای اطلاعات بیشتر، به بخش انتسابها مراجعه کنید.
اطلاعات بیشتر در مورد شناسههای مکان
شناسه مکان مورد استفاده در Places SDK برای اندروید (Legacy) همان شناسهای است که در Places API (Legacy) استفاده میشود. هر شناسه مکان میتواند فقط به یک مکان اشاره کند، اما یک مکان میتواند بیش از یک شناسه مکان داشته باشد. شرایط دیگری نیز وجود دارد که ممکن است باعث شود یک مکان شناسه مکان جدیدی دریافت کند. به عنوان مثال، این اتفاق ممکن است در صورت نقل مکان یک کسب و کار به مکان جدید رخ دهد.
وقتی با مشخص کردن شناسه مکان، مکانی را درخواست میکنید، میتوانید مطمئن باشید که همیشه همان مکان را در پاسخ دریافت خواهید کرد (اگر آن مکان هنوز وجود داشته باشد). با این حال، توجه داشته باشید که پاسخ ممکن است حاوی شناسه مکانی باشد که با شناسه موجود در درخواست شما متفاوت است.
برای اطلاعات بیشتر، به نمای کلی شناسه مکان مراجعه کنید.