يمكنك طلب المزيد من التفاصيل حول منشأة أو نقطة اهتمام معيّنة باستخدام رقم تعريف المكان وتقديم طلب تفاصيل المكان (جديد). تعرض تفاصيل المكان (جديد) معلومات أكثر شمولاً حول المكان المشار إليه، مثل العنوان الكامل ورقم الهاتف وتقييم المستخدم والمراجعات.
هناك العديد من الطرق للحصول على رقم تعريف مكان. يمكنك استخدام:
طلبات تفاصيل المكان (جديدة)
يمكنك طلب تفاصيل المكان من خلال استدعاء
PlacesClient.fetchPlace()
وتمرير عنصر
FetchPlaceRequest
يحتوي على رقم تعريف مكان وقائمة حقول، بالإضافة إلى
أي مَعلمات اختيارية:
// Define a place ID.
final String placeId = "INSERT_PLACE_ID_HERE";
// Specify the list of fields to return.
final List<Place.Field> placeFields = Arrays.asList("INSERT_PLACE_FIELDS_HERE");
// Construct a request object, passing the place ID and field list.
final FetchPlaceRequest request = FetchPlaceRequest.newInstance(placeId, placeFields);
// Pass the request object and make the request
Task<FetchPlaceResponse> placeTask = placesClient.fetchPlace(request);
ردود تفاصيل المكان (جديد)
تعرض تفاصيل المكان (جديد) البيانات على شكل كائن
Place،
لا يتضمن سوى الحقول التي طلبتها باستخدام قائمة
الحقول. لا يمكن أن تكون نتائج بيانات الأماكن فارغة، لذلك لا يتم عرض سوى نتائج الأماكن التي تحتوي على بيانات (على سبيل المثال، إذا لم يكن المكان المطلوب يحتوي على أي صور، لن يظهر حقل الصور في النتيجة).
للوصول إلى حقول البيانات، يمكنك استدعاء
الطريقة المقابلة.
على سبيل المثال، للوصول إلى اسم المكان، اتصل بالرقم getName().
المعلمات المطلوبة
المعلمات المطلوبة لـ
FetchPlaceRequest هي:
-
معرّف المكان
معرّف نصي يُعرِّف مكانًا بشكل فريد، ويتم عرضه من بحث نصي (جديد) أو بحث عن قرب (جديد) أو الإكمال التلقائي (جديد). للحصول على مزيد من المعلومات عن أرقام تعريف الأماكن، اطّلِع على نظرة عامة على رقم تعريف المكان.
-
قائمة الحقول
عندما تطلب مكانًا، يجب تحديد بيانات المكان التي تريد عرضها. ولإجراء ذلك، مرِّر قائمة بقيم
Place.Fieldتحدِّد البيانات المطلوب عرضها. لا تتوفر قائمة تلقائية للحقول التي تم إرجاعها في الردّ.تُعدّ قوائم الحقول من الممارسات الجيدة المتعلقة بالتصميم لضمان عدم طلب بيانات غير ضرورية، ما يساعد في تجنّب وقت المعالجة ورسوم الفوترة غير الضرورية.تشكّل هذه القائمة الاعتبار المهم لأنّها تؤثر في تكلفة كل طلب. للحصول على مزيد من المعلومات، يُرجى الاطّلاع على الاستخدام والفوترة.
حدِّد حقلاً واحدًا أو أكثر من الحقول التالية:
تؤدي الحقول التالية إلى تشغيل رمز التخزين التعريفي لتفاصيل المكان (المعرّفات فقط):
Place.Field.ID،Place.Field.NAME،Place.Field.PHOTO_METADATASتؤدّي الحقول التالية إلى تشغيل رمز التخزين التعريفي لتفاصيل المكان (الموقع الجغرافي فقط):
Place.Field.ADDRESS_COMPONENTS،Place.Field.ADDRESS،Place.Field.LAT_LNG،Place.Field.PLUS_CODE،Place.Field.TYPES،Place.Field.VIEWPORTتؤدي الحقول التالية إلى تشغيل رمز التخزين التعريفي لتفاصيل المكان (الأساسي):
Place.Field.BUSINESS_STATUS،Place.Field.ICON_BACKGROUND_COLOR،Place.Field.ICON_URL،Place.Field.UTC_OFFSET،Place.Field.WHEELCHAIR_ACCESSIBLE_ENTRANCEتؤدي الحقول التالية إلى تشغيل رمز التخزين التعريفي لتفاصيل المكان (المتقدّمة):
Place.Field.CURRENT_OPENING_HOURS،Place.Field.SECONDARY_OPENING_HOURS،Place.Field.PHONE_NUMBER،Place.Field.PRICE_LEVEL،Place.Field.RATING،Place.Field.OPENING_HOURS،Place.Field.USER_RATINGS_TOTAL،Place.Field.WEBSITE_URIتؤدي الحقول التالية إلى تشغيل رمز التخزين التعريفي لتفاصيل المكان (المفضّلة):
Place.Field.CURBSIDE_PICKUP،Place.Field.DELIVERY،Place.Field.DINE_IN،Place.Field.EDITORIAL_SUMMARY،Place.Field.RESERVABLE،Place.Field.REVIEWS،Place.Field.SERVES_BEER،Place.Field.SERVES_BREAKFAST،Place.Field.SERVES_BRUNCH،Place.Field.SERVES_DINNER،Place.Field.SERVES_LUNCH،Place.Field.SERVES_VEGETARIAN_FOOD،Place.Field.SERVES_WINE،Place.Field.TAKEOUT
المعلمات الاختيارية
المعلَمات الاختيارية
FetchPlaceRequest هي:
رمز المنطقة
تمثّل هذه السمة رمز المنطقة المستخدَم لتنسيق الاستجابة، ويتم تحديده كقيمة رمز CLDR مؤلف من حرفَين. لا يوجد قيمة افتراضية.
إذا تطابق اسم البلد في الحقل
Place.Field.ADDRESSفي الردّ معregionCode، سيتم حذف رمز البلد منPlace.Field.ADDRESS.تتطابق معظم رموز CLDR مع رموز ISO 3166-1، مع بعض الاستثناءات الملحوظة. على سبيل المثال، نطاق المستوى الأعلى الذي يتم ترميزه حسب البلد (ccTLD) في المملكة المتحدة هو uk. (co.uk). في حين أنّ رمز ISO 3166-1 الخاص بها هو gb (من الناحية التقنية، تشير وحدة "المملكة المتحدة لبريطانيا العظمى وأيرلندا الشمالية"). ويمكن أن تؤثّر المَعلمة في النتائج استنادًا إلى القانون الساري.
لضبط مَعلمة رمز المنطقة، يجب طلب الطريقة
setRegionCode()عند إنشاء عنصرFetchPlaceRequest.-
الرمز المميّز للجلسة
الرموز المميزة للجلسة هي سلاسل من إنشاء المستخدم تتتبع استدعاءات الإكمال التلقائي (الجديدة) على أنها "جلسات". تستخدم ميزة "الإكمال التلقائي" (ميزة جديدة) الرموز المميّزة للجلسة لتجميع مرحلتَي طلب البحث وتحديد الأماكن الخاصة بعملية البحث التي يجريها المستخدم ضمن ميزة "الإكمال التلقائي" في جلسة منفصلة، وذلك لأغراض الفوترة. يتم تمرير الرموز المميّزة للجلسة إلى استدعاءات تفاصيل المكان (جديدة) التي تتبع استدعاءات الإكمال التلقائي (الجديدة). لمزيد من المعلومات، راجِع الرموز المميّزة للجلسة.
لضبط مَعلمة الرمز المميّز للجلسة، يمكنك طلب الطريقة
setSessionToken()عند إنشاء كائنFetchPlaceRequest.
مثال على تفاصيل المكان
يطلب المثال التالي الحقول ID وNAME وADDRESS لمبنى Empire State في مدينة نيويورك.
// Define a place ID.
final String placeId = "ChIJaXQRs6lZwokRY6EFpJnhNNE";
// Specify the list of fields to return.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.NAME, Place.Field.ADDRESS);
// Construct a request object, passing the place ID and field list.
final FetchPlaceRequest request = FetchPlaceRequest.newInstance(placeId, placeFields);
// Pass the request object and make the request
Task<FetchPlaceResponse> placeTask = placesClient.fetchPlace(request);