جزئیات مکان

Places SDK برای Android اطلاعات غنی درباره مکان‌ها، از جمله نام و آدرس مکان، موقعیت جغرافیایی مشخص شده به عنوان مختصات طول و عرض جغرافیایی، نوع مکان (مانند کلوپ شبانه، فروشگاه حیوانات خانگی، موزه) و غیره را در اختیار برنامه شما قرار می‌دهد. برای دسترسی به این اطلاعات برای یک مکان خاص، می توانید از شناسه مکان استفاده کنید، یک شناسه پایدار که به طور منحصر به فرد مکان را شناسایی می کند.

جزئیات مکان

شی Place اطلاعاتی در مورد یک مکان خاص ارائه می دهد. شما می توانید یک شی Place را به روش های زیر بدست آورید:

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

هنگامی که درخواست مکانی می کنید، باید مشخص کنید که کدام داده مکان را برگردانید. برای انجام این کار، لیستی از مقادیر 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 List<Place.Field> placeFields = 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() است، برگردانید.

  توجه: اگر مکانی همیشه باز باشد، دوره زمانی یکشنبه در نیمه شب نمایش داده می‌شود و closeEvent پوچ است.

  شی Place همچنین حاوی متد getCurrentOpeningHours() است که ساعات کار یک مکان را در هفت روز آینده برمی گرداند و getSecondaryOpeningHours() که ساعات ثانویه کار یک مکان را در هفت روز آینده برمی گرداند.

• isOpen() - یک بولی که نشان می دهد آیا مکان در حال حاضر باز است یا خیر. اگر زمان مشخص نشده باشد، پیش فرض اکنون است. isOpen فقط در صورتی برگردانده می شود که هر دو Place.Field.UTC_OFFSET و Place.Field.OPENING_HOURS موجود باشند. برای اطمینان از نتایج دقیق، فیلدهای Place.Field.BUSINESS_STATUS و Place.Field.UTC_OFFSET را در درخواست مکان اصلی خود درخواست کنید. در صورت عدم درخواست، فرض بر این است که کسب و کار عملیاتی است. برای نحوه استفاده از isOpen با جزئیات مکان، این ویدیو را ببینید.

  توجه: این روش منسوخ شده است. در عوض از PlacesClient.isOpen(IsOpenRequest request) استفاده کنید. برای اطلاعات بیشتر، به دریافت وضعیت باز مراجعه کنید.

چند نمونه:

کاتلین

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

      

با شناسه مکان بگیرید

شناسه مکان یک شناسه متنی است که به طور منحصر به فرد مکان را شناسایی می کند. در 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 ، به Initialize the Places API Client مراجعه کنید.

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

وضعیت باز را دریافت کنید

متد PlacesClient.isOpen(IsOpenRequest request) یک شی IsOpenResponse برمی گرداند که نشان می دهد آیا مکان در حال حاضر بر اساس زمان مشخص شده در تماس باز است یا خیر.

این متد یک آرگومان واحد از نوع IsOpenRequest می گیرد که شامل:

• یک شی Place یا رشته ای که شناسه مکان را مشخص می کند.
  توجه: شی 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 با فیلدهای لازم، جزئیات مکان را ببینید.

توجه: SKU داده های پایه Places برای تماس با fetchPlace() برای Place.Field.UTC_OFFSET و Place.Field.BUSINESS_STATUS هزینه دریافت می کند. SKU Data Contact Places برای تماس‌های fetchPlace() برای Place.Field.CURRENT_OPENING_HOURS و Place.Field.OPENING_HOURS هزینه می‌شود.

مثال زیر تعیین می کند که آیا مکانی در حال حاضر باز است یا خیر. در این مثال، شما فقط شناسه مکان را به 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 است. هر شناسه مکان می تواند تنها به یک مکان اشاره داشته باشد، اما یک مکان واحد می تواند بیش از یک شناسه مکان داشته باشد. شرایط دیگری وجود دارد که ممکن است باعث شود یک مکان شناسه مکان جدیدی دریافت کند. برای مثال، اگر یک کسب و کار به مکان جدیدی نقل مکان کند، ممکن است این اتفاق بیفتد.

هنگامی که با تعیین شناسه مکان درخواست مکانی می کنید، می توانید مطمئن باشید که همیشه همان مکان را در پاسخ دریافت خواهید کرد (اگر مکان هنوز وجود دارد). با این حال، توجه داشته باشید که پاسخ ممکن است حاوی شناسه مکانی متفاوت از شناسه درخواست شما باشد.

برای اطلاعات بیشتر، نمای کلی شناسه مکان را ببینید.