تفاصيل المكان (جديد)

اختيار النظام الأساسي: Android iOS JavaScript خدمة الويب

يمكنك طلب مزيد من التفاصيل عن مؤسسة أو نقطة ملفتة للاهتمام معيّنة باستخدام معرّف مكانه وتقديم طلب بشأن ملفه الشخصي. تعرِض ميزة "تفاصيل المكان" (جديد) معلومات أكثر شمولاً عن المكان المحدَّد، مثل العنوان الكامل ورقم الهاتف والتقييمات والمراجعات التي كتبها المستخدمون.

هناك العديد من الطرق للحصول على رقم تعريف مكان. يمكنك استخدام:

• البحث النصي (ميزة جديدة)
• البحث عن الأماكن القريبة (ميزة جديدة)
• الإكمال التلقائي (جديد)

ملاحظة: تتوفّر ميزة "تفاصيل الأماكن" (الجديدة) في حزمة تطوير البرامج (SDK) لنظام "الأماكن" لنظام التشغيل Android 3.3.0 والإصدارات الأحدث. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة اختيار إصدار حزمة SDK. لمزيد من المعلومات حول استخدام واجهات برمجة تطبيقات Kotlin التي تمت إضافتها في الإصدار 4.0.0، يُرجى الاطّلاع على لمحة عن المرجع.

طلبات "تفاصيل المكان" (جديد)

يمكنك طلب تفاصيل عن المكان من خلال استدعاء 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);

ملاحظة: لمزيد من المعلومات عن إعداد PlacesClient، اطّلِع على إعداد عميل Places API.

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

ردود "تفاصيل المكان" (جديد)

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

للوصول إلى حقول البيانات، استخدِم الطريقة المناسبة. على سبيل المثال، للوصول إلى اسم المكان، اتصل بالرقم getName().

المعلمات المطلوبة

في ما يلي المَعلمات المطلوبة لسمة FetchPlaceRequest:

• معرّف المكان

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

• قائمة الحقول

  عند طلب مكان، عليك تحديد بيانات المكان التي تريد عرضها. للقيام بذلك، عليك إرسال قائمة بقيم Place.Field تحدد البيانات المطلوب عرضها. لا تتوفّر قائمة تلقائية بالحقول المعروضة في الردّ.

  قوائم الحقول هي من أفضل الممارسات في التصميم لضمان عدم طلب بيانات غير ضرورية، ما يساعد في تجنُّب وقت المعالجة غير الضروري و الرسوم المرتبطة بالفوترة.وهذه القائمة هي من العوامل المهمة التي يجب أخذها في الاعتبار لأنّها تؤثّر في تكلفة كل طلب. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة الاستخدام والفواتير.

  حدِّد حقلًا واحدًا أو أكثر من الحقول التالية:

  • تؤدي الحقول التالية إلى تنشيط رمز التخزين التعريفي لـ "تفاصيل المكان" (أرقام التعريف فقط):

    Place.Field.DISPLAY_NAME، Place.Field.ID، Place.Field.PHOTO_METADATAS، Place.Field.RESOURCE_NAME
    
    ملاحظات:

    • تم إيقاف حقل Place.Field.NAME نهائيًا في الإصدار 4.0 من حزمة تطوير برامج "الأماكن" لأجهزة Android. استخدِم Place.Field.DISPLAY_NAME بدلاً من ذلك.
    • يحتوي الحقل RESOURCE_NAME على اسم مورد المكان بالتنسيق: places/PLACE_ID. استخدِم DISPLAY_NAME للوصول إلى الاسم النصي للمكان.

  • تؤدي الحقول التالية إلى تنشيط رمز التخزين التعريفي لـ "تفاصيل المكان (الموقع الجغرافي فقط)":

    Place.Field.ADDRESS_COMPONENTS، ADR_FORMAT_ADDRESS، Place.Field.FORMATTED_ADDRESS، Place.Field.LOCATION، Place.Field.PLUS_CODE، Place.Field.SHORT_FORMATTED_ADDRESS، Place.Field.TYPES، Place.Field.VIEWPORT
    
    ملاحظة:تم إيقاف حقلَي Place.Field.ADDRESS وPlace.Field.LAT_LNG نهائيًا في الإصدار 4.0 من حزمة تطوير البرامج (SDK) لنظام التشغيل Android من Places. استخدِم Place.Field.FORMATTED_ADDRESS وPlace.Field.LOCATION بدلاً من ذلك.

  • تؤدي الحقول التالية إلى تنشيط رمز التخزين التعريفي لـ "تفاصيل المكان (أساسية)":

    Place.Field.ACCESSIBILITY_OPTIONS، Place.Field.BUSINESS_STATUS، Place.Field.GOOGLE_MAPS_URI، Place.Field.ICON_BACKGROUND_COLOR، Place.Field.ICON_MASK_URL، Place.Field.PRIMARY_TYPE، Place.Field.PRIMARY_TYPE_DISPLAY_NAME، Place.Field.SUB_DESTINATIONS، Place.Field.UTC_OFFSET
    
    ملاحظة: تم إيقاف حقلَي Place.Field.ICON_URL و Place.Field.WHEELCHAIR_ACCESSIBLE_ENTRANCE نهائيًا في الإصدار 4.0 من حزمة تطوير البرامج (SDK) لتطبيق "الأماكن" على نظام التشغيل Android. استخدِم Place.Field.ICON_MASK_URL Place.Field.ACCESSIBILITY_OPTIONS بدلاً من ذلك. لا يتوفّر الخيار Place.Field.ACCESSIBILITY_OPTIONS إلا لميزة "تفاصيل المكان" (الجديدة).

  • تؤدي الحقول التالية إلى تنشيط رمز التخزين التعريفي لـ "تفاصيل المكان" (متقدّمة):

    Place.Field.CURRENT_OPENING_HOURS Place.Field.CURRENT_SECONDARY_OPENING_HOURS Place.Field.INTERNATIONAL_PHONE_NUMBER Place.Field.NATIONAL_PHONE_NUMBER Place.Field.OPENING_HOURS Place.Field.PRICE_LEVEL Place.Field.RATING Place.Field.SECONDARY_OPENING_HOURS Place.Field.USER_RATING_COUNT Place.Field.WEBSITE_URI
    
    ملاحظة:تم إيقاف حقلَي Place.Field.PHONE_NUMBER Place.Field.USER_RATINGS_TOTAL نهائيًا في الإصدار 4.0 من حزمة تطوير البرامج (SDK) لتطبيق "الأماكن" على Android. استخدِم Place.Field.INTERNATIONAL_PHONE_NUMBER و Place.USER_RATING_COUNT بدلاً منهما.

  • تؤدي الحقول التالية إلى تنشيط رمز التخزين التعريفي (المفضّل) لتفاصيل المكان:

    Place.Field.ALLOWS_DOGS، Place.Field.CURBSIDE_PICKUP، Place.Field.DELIVERY، Place.Field.DINE_IN، Place.Field.EDITORIAL_SUMMARY، Place.Field.EV_CHARGE_OPTIONS، Place.Field.FUEL_OPTIONS، Place.Field.GOOD_FOR_CHILDREN، Place.Field.GOOD_FOR_GROUPS، Place.Field.GOOD_FOR_WATCHING_SPORTS، Place.Field.LIVE_MUSIC، Place.Field.MENU_FOR_CHILDREN، Place.Field.OUTDOOR_SEATING، Place.Field.PARKING_OPTIONS، Place.Field.PAYMENT_OPTIONS، Place.Field.RESERVABLE، Place.Field.RESTROOM، Place.Field.REVIEWS، Place.Field.SERVES_BEER، Place.Field.SERVES_BREAKFAST، Place.Field.SERVES_BRUNCH، Place.Field.SERVES_COCKTAILS، Place.Field.SERVES_COFFEE، Place.Field.SERVES_DESSERT، Place.Field.SERVES_DINNER، Place.Field.SERVES_LUNCH، Place.Field.SERVES_VEGETARIAN_FOOD، Place.Field.SERVES_WINE، Place.Field.TAKEOUT
  ملاحظة: في الإصدار 4.0 من حزمة تطوير البرامج (SDK) لنظام التشغيل Android المستندة إلى "بيانات الأماكن"، تم إيقاف العديد من حقول بيانات الأماكن نهائيًا وإضافة حقول جديدة. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة نقل البيانات إلى حقول بيانات الأماكن الجديدة في حزمة تطوير البرامج (SDK) لنظام التشغيل Android 4.0 .

المعلمات الاختيارية

في ما يلي المَعلمات الاختيارية لسمة FetchPlaceRequest:

• رمز المنطقة

  رمز المنطقة المستخدَم لتنسيق الاستجابة، ويتم تحديده على أنّه قيمة رمز CLDR المكوّن من حرفَين. لا تتوفّر قيمة تلقائية.

  إذا كان اسم البلد في حقل Place.Field.FORMATTED_ADDRESS في الاستجابة يتطابق مع regionCode، يتم حذف رمز البلد من Place.Field.FORMATTED_ADDRESS.

  تتطابق معظم رموز CLDR مع رموز ISO 3166-1، باستثناء بعض الاستثناءات البارزة. على سبيل المثال، رمز المستوى الأعلى للمنطقة الجغرافية للمملكة المتحدة هو "uk" (‎.co.uk)، بينما رمزه وفقًا لمعيار ISO 3166-1 هو "gb" (من الناحية الفنية لجهة "المملكة المتحدة لبريطانيا العظمى وأيرلندا الشمالية"). يمكن أن تؤثّر المَعلمة في النتائج استنادًا إلى القانون الساري.

  لضبط مَعلمة رمز المنطقة، استخدِم الطريقة setRegionCode() عند إنشاء العنصر FetchPlaceRequest.

• رمز الجلسة

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

  لضبط مَعلمة رمز تمييز الجلسة، استخدِم طريقة setSessionToken() عند إنشاء عنصر FetchPlaceRequest.

مثال على تفاصيل المكان

يطلب المثال التالي حقول ID وDISPLAY_NAME وFORMATTED_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.DISPLAY_NAME, Place.Field.FORMATTED_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);