جزئیات جا (قدیمی)

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

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

جزئیات جا

شیء Place اطلاعاتی درباره مکانی خاص ارائه می‌دهد. می‌توانید با فراخوانی PlacesClient.fetchPlace() به شیء Place دسترسی پیدا کنید – راهنمای دریافت مکان با شناسه را ببینید.

وقتی مکانی را درخواست می‌کنید، باید مشخص کنید کدام داده‌های مکان برگردانده شود. برای انجام این کار، فهرستی از مقادیر Place.Field را که داده‌های موردنظر برای برگرداندن را مشخص می‌کند ارسال کنید. این فهرست ملاحظه مهمی است زیرا بر هزینه هر درخواست تأثیر می‌گذارد.

چون نتایج داده‌های مکان نمی‌تواند خالی باشد، فقط نتایج مکان دارای داده برگردانده می‌شود. برای مثال، اگر مکان درخواستی عکس نداشته باشد، فیلد photos در نتیجه وجود نخواهد داشت.

مثال زیر فهرستی از سه مقدار Place.Field را ارسال می‌کند تا داده‌های برگردانده‌شده توسط درخواست را مشخص کند:

Kotlin

// 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 وجود نداشته باشد، روش مربوطه مقدار null را برمی‌گرداند. در زیر نمونه‌هایی از چند روش دردسترس نشان داده شده است.

  • 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 با «جزئیات مکان»، این ویدیو را ببینید.

چند مثال:

Kotlin

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

دریافت مکان براساس شناسه

شناسه مکان شناسه‌ای متنی است که مکانی را به‌طور منحصربه‌فرد شناسایی می‌کند. در «کیت توسعه نرم‌افزار مکان‌ها، ویژه Android»، می‌توانید با فراخواندن Place.getId()، شناسه مکان را بازیابی کنید. سرویس تکمیل خودکار مکان همچنین شناسه مکانی را برای هر مکانی که با پُرسمان جستجوی ارائه‌شده و فیلتر مطابقت دارد برمی‌گرداند. می‌توانید شناسه مکان را ذخیره کنید و از آن برای بازیابی Place شیء در آینده استفاده کنید.

برای دریافت مکان با شناسه، PlacesClient.fetchPlace() را فراخوانی کنید، FetchPlaceRequest را ارسال کنید.

این API FetchPlaceResponse را در Task برمی‌گرداند. ‫ FetchPlaceResponse حاوی شیء Place مطابق با شناسه مکان ارائه‌شده است.

مثال کد زیر نشان می‌دهد که چگونه fetchPlace() را برای دریافت جزئیات مکان مشخص‌شده فراخوانی کنید.

Kotlin

// 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() برای واکشی آن‌ها استفاده می‌کند. برای کسب اطلاعات بیشتر درباره ایجاد کردن «شیء مکان» با فیلدهای ضروری، جزئیات مکان را ببینید.

مثال زیر تعیین می‌کند که آیا مکانی درحال‌حاضر باز است یا نه. در این مثال، فقط شناسه مکان را به isOpen() ارسال می‌کنید:

Kotlin

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 باید حاوی شناسه مکان معتبری باشد:

Kotlin

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

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

وقتی برنامه شما اطلاعات مکان، ازجمله مرورهای مکان، را نمایش می‌دهد، برنامه باید همه اسناد را نیز نمایش دهد. برای اطلاعات بیشتر، به ارجاع‌ها مراجعه کنید.

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

شناسه مکان استفاده‌شده در «کیت توسعه نرم‌افزار مکان‌ها ویژه Android (قدیمی)» همان شناسه استفاده‌شده در میانای برنامه‌سازی کاربردی مکان‌ها (قدیمی) است. هر شناسه مکان می‌تواند فقط به یک مکان اشاره کند، اما یک مکان می‌تواند بیش‌از یک شناسه مکان داشته باشد. شرایط دیگری نیز وجود دارد که ممکن است باعث شود مکان شناسه مکان جدیدی دریافت کند. برای مثال، این ممکن است زمانی اتفاق بیفتد که کسب‌وکاری به مکان جدیدی منتقل شود.

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

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