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

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

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

• البحث النصي (الجديد)
• Nearby Search (New)
• الإكمال التلقائي (جديد)

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

يمكنك طلب تفاصيل المكان من خلال استدعاء 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 Details (New) البيانات في شكل عنصر Place، والذي يتضمّن فقط الحقول التي طلبتها باستخدام قائمة الحقول. لا يمكن أن تكون نتائج بيانات الأماكن فارغة، لذا يتم عرض نتائج الأماكن التي تحتوي على بيانات فقط (على سبيل المثال، إذا لم يتضمّن المكان المطلوب أي صور، لن يظهر حقل الصور في النتيجة).

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

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

المَعلمات المطلوبة لـ FetchPlaceRequest هي:

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

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

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

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

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

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

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

    Place.Field.ID
Place.Field.PHOTO_METADATAS
Place.Field.RESOURCE_NAME
    

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

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

    Place.Field.ADDRESS_COMPONENTS
ADR_FORMAT_ADDRESS
Place.Field.FORMATTED_ADDRESS*
        * يُرجى استخدام هذه السمة بدلاً من Place.Field.ADDRESS (متوقّفة نهائيًا).
    Place.Field.LOCATION*
        * يجب استخدامها بدلاً من Place.Field.LAT_LNG (متوقّفة نهائيًا).
    Place.Field.PLUS_CODE
Place.Field.SHORT_FORMATTED_ADDRESS
Place.Field.TYPES
Place.Field.VIEWPORT

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

  • تؤدي الحقول التالية إلى تفعيل رمز التخزين التعريفي Pro لتفاصيل المكان:

    Place.Field.ACCESSIBILITY_OPTIONS*
        * يُرجى استخدام هذه السمة بدلاً من Place.Field.WHEELCHAIR_ACCESSIBLE_ENTRANCE (تم إيقافها نهائيًا).
    Place.Field.BUSINESS_STATUS
Place.Field.DISPLAY_NAME*
        * يُرجى استخدام هذه السمة بدلاً من Place.Field.NAME التي تم إيقافها نهائيًا.
    Place.Field.GOOGLE_MAPS_URI
Place.Field.ICON_BACKGROUND_COLOR
Place.Field.ICON_MASK_URL*
        * يجب استخدام هذه السمة بدلاً من Place.Field.ICON_URL (متوقّفة نهائيًا).
    Place.Field.PRIMARY_TYPE
Place.Field.PRIMARY_TYPE_DISPLAY_NAME
Place.Field.SUB_DESTINATIONS
Place.Field.UTC_OFFSET

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

  • تؤدي الحقول التالية إلى تفعيل رمز التخزين التعريفي Enterprise لتفاصيل المكان:

    Place.Field.CURRENT_OPENING_HOURS
Place.Field.CURRENT_SECONDARY_OPENING_HOURS
Place.Field.INTERNATIONAL_PHONE_NUMBER*
        * يجب استخدام هذه السمة بدلاً من Place.Field.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.USER_RATINGS_TOTAL التي تم إيقافها نهائيًا.
    Place.Field.WEBSITE_URI

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

  • تؤدي الحقول التالية إلى تفعيل رمز التخزين التعريفي Enterprise Plus لخدمة "تفاصيل المكان":

    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

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

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

المَعلمات الاختيارية لـ FetchPlaceRequest هي:

• رمز المنطقة

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

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

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

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

• الرمز المميّز للجلسة

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

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

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

يطلب المثال التالي الحقول ID وDISPLAY_NAME وFORMATTED_ADDRESS لمبنى إمباير ستيت في مدينة نيويورك.

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