تفاصيل المكان (الإصدار القديم)

المطوّرون في المنطقة الاقتصادية الأوروبية

توفّر حزمة تطوير البرامج (SDK) للأماكن على Android (الإصدار القديم) لتطبيقك معلومات غنية عن الأماكن، بما في ذلك اسم المكان وعنوانه والموقع الجغرافي المحدّد كإحداثيات خطوط العرض/الطول ونوع المكان (مثل ملهى ليلي ومتجر حيوانات أليفة ومتحف) وغير ذلك. للوصول إلى هذه المعلومات لمكان معيّن، يمكنك استخدام رقم تعريف المكان، وهو معرّف ثابت يحدّد مكانًا بشكل فريد.

تفاصيل المكان

يوفّر الكائن Place معلومات عن مكان معيّن. يمكنك الحصول على عنصر Place من خلال استدعاء PlacesClient.fetchPlace() – راجِع دليل الحصول على مكان باستخدام رقم التعريف.

عند طلب مكان، يجب تحديد بيانات المكان المطلوب عرضها. ولإجراء ذلك، عليك تمرير قائمة بقيم 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، يعرض الإجراء المرتبط قيمة فارغة. في ما يلي أمثلة على بعض الطرق المتاحة.

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

الحصول على مكان حسب رقم التعريف

رقم تعريف المكان هو معرّف نصي يحدّد مكانًا بشكل فريد. في "حزمة تطوير البرامج (SDK) للأماكن على Android"، يمكنك استرداد معرّف مكان من خلال طلب Place.getId(). تعرض خدمة الإكمال التلقائي للأماكن أيضًا رقم تعريف المكان لكل مكان يتطابق مع طلب البحث والفلتر المقدَّمَين. يمكنك تخزين رقم تعريف المكان واستخدامه لاسترداد عنصر Place مرة أخرى لاحقًا.

للحصول على مكان باستخدام المعرّف، يمكنك استدعاء PlacesClient.fetchPlace()، وتمرير FetchPlaceRequest.

تعرض واجهة برمجة التطبيقات 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 (الإصدار القديم). يمكن أن يشير كل رقم تعريف مكان إلى مكان واحد فقط، ولكن يمكن أن يكون لمكان واحد أكثر من رقم تعريف مكان واحد. هناك ظروف أخرى قد تؤدي إلى حصول مكان على رقم تعريف مكان جديد. على سبيل المثال، قد يحدث ذلك إذا انتقلت مؤسسة إلى موقع جغرافي جديد.

عند طلب مكان من خلال تحديد رقم تعريف المكان، يمكنك التأكّد من أنّك ستتلقّى دائمًا المكان نفسه في الردّ (إذا كان المكان لا يزال موجودًا). ومع ذلك، يُرجى العِلم أنّ الردّ قد يحتوي على رقم تعريف مكان مختلف عن الرقم الوارد في طلبك.

لمزيد من المعلومات، يُرجى الاطّلاع على نظرة عامة على رقم تعريف المكان.