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

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

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

جزئیات جا

شیء 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() را فراخوانی کنید تا فهرستی از رشته‌ها را که نشان‌دهنده ساعت‌های باز و بسته شدن برای هر روز هفته است برگرداند. برای برگرداندن فهرستی از اشیاء period با اطلاعات دقیق‌تر که معادل داده‌های ارائه‌شده توسط getWeekdayText() است، OpeningHours.getPeriods() را فراخوانی کنید.

    شیء 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();

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

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

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

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