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

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

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

يقدّم كائن Place معلومات عن مكان محدّد. يمكنك تجميد عنصر Place بالطرق التالية:

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

عند طلب مكان، عليك تحديد بيانات المكان التي تريد عرضها. ولإجراء ذلك، مرِّر قائمة قيم Place.Field تحدد البيانات المراد عرضها. تُعدّ هذه القائمة عاملاً مهمًا لأنها تؤثر في تكلفة كل طلب.

بما أنّ نتائج بيانات المكان لا يمكن أن تكون فارغة، يتم عرض نتائج المكان التي تتضمّن بيانات فقط (على سبيل المثال، إذا لم يكن المكان المطلوب يتضمّن صورًا، لن يظهر الحقل photos في النتيجة).

في المثال التالي، تمرّر قائمة بثلاث قيم من Place.Field لتحديد البيانات التي تم عرضها في الطلب:

// Specify the fields to return.
final List placeFields = Arrays.asList(Place.Field.NAME, Place.Field.RATING, Place.Field.OPENING_HOURS);

// Specify the fields to return.
val placeFields = listOf(Place.Field.NAME, Place.Field.RATING, Place.Field.OPENING_HOURS)

بعد الحصول على العنصر Place، استخدِم طرق الوصول إلى حقول البيانات المحدّدة في الطلب. إذا كان الحقل غير متوفّر في الكائن 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 مع تفاصيل المكان.

في ما يلي بعض الأمثلة البسيطة:

final CharSequence name = place.getName();
final CharSequence address = place.getAddress();
final LatLng location = place.getLatLng();

      

val name = place.name
val address = place.address
val location = place.latLng

      

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

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

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

تعرض واجهة برمجة التطبيقات السمة FetchPlaceResponse في Task. يتضمّن FetchPlaceResponse عنصر Place مطابقًا لرقم تعريف المكان المقدَّم.

يوضّح مثال الرمز التالي الاتصال بالرقم fetchPlace() للحصول على تفاصيل عن المكان المحدّد.

// 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.
    }
});

      

// 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")
        }
    }

      

الحصول على حالة "مفتوح"

تعرض الطريقة 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():

@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());
// ...

      

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
}
// ...

      

يوضّح المثال التالي طلب isOpen() حيث يتم تمرير عنصر Place. يجب أن يحتوي الكائن Place على معرّف مكان صالح:

@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());
            // ...
        });
// ...

      

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
    }
    // ...
}
// ...

      

عرض الإحالات في تطبيقك

عندما يعرض تطبيقك معلومات عن المكان، يجب أن يعرض التطبيق أيضًا معلومات تحديد المصدر. راجِع المواد المتعلّقة بالإحالات.

مزيد من المعلومات حول أرقام تعريف الأماكن

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

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

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