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

توفر حزمة تطوير البرامج (SDK) للأماكن في 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.

• getAddress() – عنوان المكان، بتنسيق يمكن للإنسان قراءته.
• getAddressComponents() – List من مكوّنات العنوان لهذا المكان. يتم تقديم هذه المكوّنات بغرض استخراج المعلومات المنظَّمة حول عنوان المكان، مثلاً للعثور على المدينة التي يقع فيها المكان. لا تستخدم هذه المكوّنات لتنسيق العنوان، وبدلاً من ذلك، يمكنك استدعاء getAddress() لتوفير عنوان منسق باللغة المحلية.
• getID() – معرّف النص للمكان. يمكنك الاطّلاع على مزيد من المعلومات حول معرّفات الأماكن في بقية هذه الصفحة.
• getLatLng() – الموقع الجغرافي للمكان، ويتم تحديده على أنه إحداثيات خطوط الطول والعرض.
• getName() – اسم المكان.
• getOpeningHours() – OpeningHours للمكان اتصل بـ OpeningHours.getWeekdayText() لعرض قائمة بالسلاسل التي تمثل ساعات العمل والإغلاق لكل يوم من الأسبوع. اتصل بـ OpeningHours.getPeriods() لعرض قائمة من period من الكائنات مع معلومات أكثر تفصيلاً تعادل البيانات التي يوفرها getWeekdayText(). ملاحظة: إذا كان أحد الأماكن مفتوحًا دائمًا، يتم تمثيل الفترة الزمنية على أنها الأحد في منتصف الليل، وتكون closeEvent فارغة.
• 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")
        }
    }

      

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

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

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

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

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

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