Places SDK برای Android اطلاعات غنی درباره مکانها، از جمله نام و آدرس مکان، موقعیت جغرافیایی مشخص شده به عنوان مختصات طول و عرض جغرافیایی، نوع مکان (مانند کلوپ شبانه، فروشگاه حیوانات خانگی، موزه) و غیره را در اختیار برنامه شما قرار میدهد. برای دسترسی به این اطلاعات برای یک مکان خاص، می توانید از شناسه مکان استفاده کنید، یک شناسه پایدار که به طور منحصر به فرد مکان را شناسایی می کند.
جزئیات مکان
شی Place
اطلاعاتی در مورد یک مکان خاص ارائه می دهد. شما می توانید یک شی Place
را به روش های زیر بدست آورید:
-
PlacesClient.fetchPlace()
فراخوانی کنید – راهنمای دریافت مکان با شناسه را ببینید. -
PlacesClient.findCurrentPlace()
فراخوانی کنید – راهنمای دریافت مکان فعلی را ببینید.
هنگامی که درخواست مکانی می کنید، باید مشخص کنید که کدام داده مکان را برگردانید. برای انجام این کار، لیستی از مقادیر Place.Field را ارسال کنید که دادههای مورد نظر را مشخص میکند. این لیست یک ملاحظه مهم است زیرا بر هزینه هر درخواست تأثیر می گذارد.
از آنجایی که نتایج دادههای مکان نمیتوانند خالی باشند، فقط نتایج مکان با داده برگردانده میشوند (مثلاً اگر مکان درخواستی عکس نداشته باشد، فیلد photos
در نتیجه وجود نخواهد داشت).
مثال زیر فهرستی از سه مقدار Place.Field را برای مشخص کردن دادههای بازگردانده شده توسط یک درخواست ارسال میکند:
کاتلین
// Specify the fields to return. val placeFields = listOf(Place.Field.NAME, Place.Field.RATING, Place.Field.OPENING_HOURS)
جاوا
// Specify the fields to return. final ListplaceFields = Arrays.asList(Place.Field.NAME, Place.Field.RATING, Place.Field.OPENING_HOURS);
به فیلدهای داده شی مکان دسترسی پیدا کنید
پس از به دست آوردن شیء Place
، از متدهای شی برای دسترسی به فیلدهای داده مشخص شده در درخواست استفاده کنید. اگر فیلد در شیء Place
وجود نداشته باشد، متد مربوطه null را برمیگرداند. در زیر نمونه هایی از چند روش موجود نشان داده شده است. برای فهرست کامل همه روشها، به مرجع Place
API مراجعه کنید.
-
getAddress()
– آدرس مکان، در قالب قابل خواندن توسط انسان. -
getAddressComponents()
–List
از اجزای آدرس برای این مکان. این اجزا به منظور استخراج اطلاعات ساختاریافته در مورد آدرس یک مکان، به عنوان مثال یافتن شهری که یک مکان در آن قرار دارد، ارائه شده است. از این مؤلفه ها برای قالب بندی آدرس استفاده نکنید. در عوض،getAddress()
را فراخوانی کنید، که یک آدرس فرمت شده محلی را ارائه می دهد. -
getId()
– شناسه متنی مکان. در ادامه این صفحه درباره شناسه مکان ها بیشتر بخوانید. -
getLatLng()
– موقعیت جغرافیایی مکان، مشخص شده به عنوان مختصات طول و عرض جغرافیایی. -
getName()
– نام مکان. getOpeningHours()
–OpeningHours
مکان. باOpeningHours.getWeekdayText()
تماس بگیرید تا لیستی از رشته هایی که ساعات باز و بسته شدن هر روز هفته را نشان می دهد، برگردانید.OpeningHours.getPeriods()
را فراخوانی کنید تا لیستی از اشیاءperiod
را با اطلاعات دقیق تری که معادل داده های ارائه شده توسطgetWeekdayText()
است، برگردانید.شی
Place
همچنین حاوی متدgetCurrentOpeningHours()
است که ساعات کار یک مکان را در هفت روز آینده برمی گرداند وgetSecondaryOpeningHours()
که ساعات ثانویه کار یک مکان را در هفت روز آینده برمی گرداند.isOpen()
- یک بولی که نشان می دهد آیا مکان در حال حاضر باز است یا خیر. اگر زمان مشخص نشده باشد، پیش فرض اکنون است.isOpen
فقط در صورتی برگردانده می شود که هر دوPlace.Field.UTC_OFFSET
وPlace.Field.OPENING_HOURS
موجود باشند. برای اطمینان از نتایج دقیق، فیلدهایPlace.Field.BUSINESS_STATUS
وPlace.Field.UTC_OFFSET
را در درخواست مکان اصلی خود درخواست کنید. در صورت عدم درخواست، فرض بر این است که کسب و کار عملیاتی است. برای نحوه استفاده ازisOpen
با جزئیات مکان، این ویدیو را ببینید.
چند مثال ساده:
کاتلین
val name = place.name val address = place.address val location = place.latLng
جاوا
final CharSequence name = place.getName(); final CharSequence address = place.getAddress(); final LatLng location = place.getLatLng();
دسترسی به داده های مکان اضافه شده در نسخه 3.3.0
Places SDK برای Android نسخه 3.3.0 داده های جدیدی را به Place
اضافه می کند:
- انواع مکان : مقادیر نوع جدید مرتبط با یک مکان.
- نظرات : حداکثر پنج نظر برای یک مکان.
- کد زبان نام : کد زبان برای نام مکان.
برای دسترسی به این داده ها باید Places SDK برای Android (جدید) را فعال کنید. برای یادگیری تفاوت های کلیدی بین دو نسخه SDK، به انتخاب نسخه SDK خود مراجعه کنید.
بخش های زیر نحوه دسترسی به این داده های جدید را شرح می دهد.
دسترسی به انواع مکان های جدید
هر مکان می تواند یک یا چند مقدار نوع مرتبط با خود داشته باشد. Places SDK برای اندروید نسخه 3.3.0 مقادیر نوع جدیدی را اضافه می کند. برای فهرست کامل، به انواع مکان های گسترده مراجعه کنید.
در Places SDK برای Android نسخه 3.2.0 و نسخه های قبلی، از متد Place.getTypes()
برای دسترسی به مقادیر نوع مرتبط با مکان استفاده کردید. Place.getTypes()
لیستی از انواع را به عنوان مقادیر enum تعریف شده توسط Place.Types
برمی گرداند.
متد Place.getPlaceTypes()
مقادیر نوع را به عنوان لیستی از مقادیر رشته برمی گرداند. مقادیر برگردانده شده به نسخه Places SDK برای Android شما بستگی دارد:
- Places SDK برای Android (جدید) : رشته های تعریف شده توسط جدول A و جدول B نشان داده شده در انواع مکان (جدید) را برمی گرداند، از جمله تمام انواع مکان های اضافه شده در نسخه 3.3.0.
- Places SDK برای Android : فهرست های تعریف شده توسط
Place.Types
را برمی گرداند، که شامل انواع جدید اضافه شده در نسخه 3.3.0 نمی شود.
برای یادگیری تفاوت های کلیدی بین دو نسخه SDK، به انتخاب نسخه SDK خود مراجعه کنید.
به نظرات مکان دسترسی داشته باشید
Places SDK for Android (جدید) کلاس Review
اضافه می کند که شامل بررسی یک مکان است. شیء Place
می تواند حداکثر پنج نظر داشته باشد.
کلاس Review
همچنین می تواند شامل یک منبع و یک منبع نویسنده باشد. اگر نظر را در برنامه خود نمایش دهید، باید هر گونه انتساب یا منبع نویسنده را نیز نمایش دهید. برای اطلاعات بیشتر، به نمایش مرور مراجعه کنید.
برای پر کردن شی Place
با نظرات، باید:
- وقتی پروژه Google Cloud خود را راهاندازی میکنید، SDK جدید را فعال کنید.
- SDK جدید را در یک فعالیت یا قطعه راهاندازی کنید .
-
Place.Field.REVIEWS
را در لیست فیلد درخواست جزئیات مکان قرار دهید. -
PlacesClient.fetchPlace()
را فراخوانی کنید. فیلد بررسی توسطPlacesClient.findCurrentPlace()
پشتیبانی نمی شود. - از متد
Place.getReviews()
برای دسترسی به فیلد دادههای بررسی در شیءPlace
استفاده کنید.
به کد زبان نام مکان دسترسی پیدا کنید
متد Place.getName()
یک رشته متنی حاوی نام مکان را برمی گرداند. برای پر کردن شی Place
با نام مکان، باید Place.Field.NAME
را در لیست فیلد درخواست جزئیات مکان قرار دهید.
شی Place
اکنون حاوی کد زبان رشته نام است. برای پر کردن شیء Place
با کد زبان، باید:
- وقتی پروژه Google Cloud خود را راهاندازی میکنید، SDK جدید را فعال کنید.
- SDK جدید را در یک فعالیت یا قطعه راهاندازی کنید .
-
Place.Field.NAME
را در لیست فیلد درخواست قرار دهید. این مقدار پاسخ را به گونه ای پیکربندی می کند که نام مکان و کد زبان را در شیءPlace
شامل شود. -
PlacesClient.fetchPlace()
را فراخوانی کنید.PlacesClient.findCurrentPlace()
از فیلد کد زبان پشتیبانی نمی کند. - از متد
Place.getNameLanguageCode()
برای دسترسی به فیلد کد زبان در شیءPlace
استفاده کنید.
کد منطقه را در نسخه 3.3.0 تنظیم کنید
Places SDK for Android (جدید) پارامتر درخواست کد منطقه را به جزئیات مکان اضافه می کند. کد منطقه برای قالب بندی پاسخ استفاده می شود که به عنوان مقدار کد CLDR دو کاراکتری مشخص شده است. این پارامتر همچنین می تواند یک اثر سوگیری در نتایج جستجو داشته باشد. هیچ مقدار پیش فرضی وجود ندارد. برای تنظیم کد منطقه باید SDK جدید را فعال کنید.
اگر نام کشور فیلد آدرس در پاسخ با کد منطقه مطابقت داشته باشد، کد کشور از آدرس حذف می شود.
اکثر کدهای CLDR با کدهای ISO 3166-1 یکسان هستند، با برخی استثناهای قابل توجه. برای مثال، ccTLD بریتانیا "uk" (.co.uk) است در حالی که کد ISO 3166-1 آن "gb" است (از لحاظ فنی برای نهاد "پادشاهی متحده بریتانیای کبیر و ایرلند شمالی"). این پارامتر می تواند بر نتایج بر اساس قانون قابل اجرا تأثیر بگذارد.
با شناسه مکان بگیرید
شناسه مکان یک شناسه متنی است که به طور منحصر به فرد مکان را شناسایی می کند. در Places SDK برای Android، میتوانید شناسه یک مکان را با فراخوانی Place.getId()
بازیابی کنید. سرویس تکمیل خودکار مکان همچنین برای هر مکان یک شناسه مکان برمیگرداند که با عبارت جستجو و فیلتر ارائه شده مطابقت دارد. میتوانید شناسه مکان را ذخیره کنید و بعداً از آن برای بازیابی مجدد شیء Place
استفاده کنید.
برای دریافت مکان با شناسه، با ارسال یک FetchPlaceRequest
با PlacesClient.fetchPlace()
تماس بگیرید.
API یک FetchPlaceResponse
را در یک Task
برمی گرداند. FetchPlaceResponse
حاوی یک شی Place
است که با شناسه مکان ارائه شده مطابقت دارد.
مثال کد زیر فراخوانی fetchPlace()
برای دریافت جزئیات مکان مشخص شده نشان می دهد.
کاتلین
// Define a Place ID. val placeId = "INSERT_PLACE_ID_HERE" // Specify the fields to return. val placeFields = listOf(Place.Field.ID, Place.Field.NAME) // 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 Log.i(PlaceDetailsActivity.TAG, "Place found: ${place.name}") }.addOnFailureListener { exception: Exception -> if (exception is ApiException) { 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 = "INSERT_PLACE_ID_HERE"; // Specify the fields to return. final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.NAME); // 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(); Log.i(TAG, "Place found: " + place.getName()); }).addOnFailureListener((exception) -> { if (exception instanceof ApiException) { final ApiException apiException = (ApiException) exception; 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 با فیلدهای لازم، جزئیات مکان را ببینید.
مثال زیر تعیین می کند که آیا مکانی در حال حاضر باز است یا خیر. در این مثال، شما فقط شناسه مکان را به isOpen()
میدهید:
کاتلین
val isOpenCalendar: Calendar = Calendar.getInstance() val placeId = "ChIJD3uTd9hx5kcR1IQvGfr8dbk" val request: IsOpenRequest = try { IsOpenRequest.newInstance(placeId, isOpenCalendar.timeInMillis) } catch (e: IllegalArgumentException) { e.printStackTrace() return } val isOpenTask: Task<IsOpenResponse> = placesClient.isOpen(request) isOpenTask.addOnSuccessListener { response -> val isOpen = response.isOpen } // ...
جاوا
@NonNull Calendar isOpenCalendar = Calendar.getInstance(); String placeId = "ChIJD3uTd9hx5kcR1IQvGfr8dbk"; IsOpenRequest isOpenRequest; try { isOpenRequest = IsOpenRequest.newInstance(placeId, isOpenCalendar.getTimeInMillis()); } catch (IllegalArgumentException e) { e.printStackTrace(); return; } Task<IsOpenResponse> placeTask = placesClient.isOpen(isOpenRequest); placeTask.addOnSuccessListener( (response) -> isOpen = response.isOpen()); // ...
مثال بعدی فراخوانی isOpen()
را نشان می دهد که در آن یک شی Place
ارسال می کنید. شی Place
باید دارای شناسه مکان معتبر باشد:
کاتلین
val isOpenCalendar: Calendar = Calendar.getInstance() var place: Place val placeId = "ChIJD3uTd9hx5kcR1IQvGfr8dbk" // 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.UTC_OFFSET ) 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) { e.printStackTrace() return@addOnSuccessListener } val isOpenTask: Task<IsOpenResponse> = placesClient.isOpen(isOpenRequest) isOpenTask.addOnSuccessListener { isOpenResponse -> val isOpen = isOpenResponse.isOpen } // ... } // ...
جاوا
@NonNull Calendar isOpenCalendar = Calendar.getInstance(); String placeId = "ChIJD3uTd9hx5kcR1IQvGfr8dbk"; // 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.UTC_OFFSET )); 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) { e.printStackTrace(); return; } Task<IsOpenResponse> isOpenTask = placesClient.isOpen(isOpenRequest); isOpenTask.addOnSuccessListener( (isOpenResponse) -> isOpen = isOpenResponse.isOpen()); // ... }); // ...
اسناد را در برنامه خود نمایش دهید
هنگامی که برنامه شما اطلاعات مکان، از جمله بررسی مکان را نمایش می دهد، برنامه باید هر گونه اسناد را نیز نمایش دهد. برای اطلاعات بیشتر، ارجاعات را ببینید.
اطلاعات بیشتر درباره شناسه مکان
شناسه مکان مورد استفاده در Places SDK برای Android همان شناسه مورد استفاده در Places API است. هر شناسه مکان می تواند تنها به یک مکان اشاره داشته باشد، اما یک مکان واحد می تواند بیش از یک شناسه مکان داشته باشد. شرایط دیگری وجود دارد که ممکن است باعث شود یک مکان شناسه مکان جدیدی دریافت کند. برای مثال، اگر یک کسب و کار به مکان جدیدی نقل مکان کند، ممکن است این اتفاق بیفتد.
وقتی با تعیین شناسه مکان درخواست مکانی میکنید، میتوانید مطمئن باشید که همیشه همان مکان را در پاسخ دریافت خواهید کرد (اگر مکان هنوز وجود دارد). با این حال، توجه داشته باشید که پاسخ ممکن است حاوی شناسه مکانی متفاوت از شناسه درخواست شما باشد.
برای اطلاعات بیشتر، نمای کلی شناسه مکان را ببینید.