توفر حزمة تطوير البرامج (SDK) للأماكن في Android معلومات غنية حول الأماكن، بما في ذلك اسم المكان وعنوانه والموقع الجغرافي المحدد كإحداثيات خطوط الطول ودوائر العرض ونوع المكان (مثل النادي الليلي ومتجر الحيوانات الأليفة والمتحف) وغير ذلك الكثير. للوصول إلى هذه المعلومات لمكان محدّد، يمكنك استخدام رقم تعريف المكان، وهو معرّف ثابت يحدّد مكانًا بشكل فريد.
تفاصيل المكان
يوفّر الكائن
Place
معلومات حول مكان محدّد. يمكنك الحصول على كائن
Place
بالطرق التالية:
- الاتصال بـ
PlacesClient.findCurrentPlace()
– راجع دليل الحصول على المكان الحالي. - الاتصال بالرقم
PlacesClient.fetchPlace()
– اطّلع على دليل الحصول على مكان باستخدام رقم التعريف.
عند طلب مكان، عليك تحديد بيانات المكان المطلوب عرضها. للقيام بذلك، يجب تمرير قائمة قيم Place.Field التي تحدِّد البيانات المُراد عرضها. تُعدّ هذه القائمة من الاعتبارات المهمة لأنها تؤثر في تكلفة كل طلب.
نظرًا لأن نتائج بيانات الأماكن لا يمكن أن تكون فارغة، يتم عرض نتائج الأماكن التي تتضمن بيانات فقط (على سبيل المثال، إذا كان المكان المطلوب لا يحتوي على صور، فإن الحقل photos
لن يكون موجودًا في النتيجة).
يوضّح المثال التالي قائمة بثلاثة قيم Place.Field لتحديد البيانات التي يعرضها الطلب:
لغة Java
// Specify the fields to return. final ListplaceFields = Arrays.asList(Place.Field.NAME, Place.Field.RATING, Place.Field.OPENING_HOURS);
Kotlin
// 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
مع تفاصيل المكان.
في ما يلي بعض الأمثلة البسيطة:
لغة Java
final CharSequence name = place.getName(); final CharSequence address = place.getAddress(); final LatLng location = place.getLatLng();
Kotlin
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()
للحصول على تفاصيل للمكان المحدد.
لغة Java
// 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. } });
Kotlin
// 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 هو نفسه المعرّف المستخدم في واجهة برمجة تطبيقات الأماكن. يمكن أن يشير معرّف المكان إلى مكان واحد فقط، ولكن يمكن أن يكون لمكان واحد أكثر من معرّف مكان واحد. هناك حالات أخرى قد تؤدي إلى حصول مكان على رقم تعريف مكان جديد. على سبيل المثال، قد يحدث ذلك إذا انتقل نشاط تجاري إلى موقع جغرافي جديد.
عندما تطلب مكانًا من خلال تحديد معرّف مكان، يمكنك أن تكون واثقًا من أنك ستتلقى دائمًا نفس المكان في الاستجابة (إذا كان المكان لا يزال موجودًا). يُرجى العِلم بأن الاستجابة قد تحتوي على رقم تعريف مكان مختلف عن المعرّف الوارد في طلبك.
ولمزيد من المعلومات، يمكنك الاطّلاع على نظرة عامة على رقم تعريف المكان.