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

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

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

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

يقدّم الكائن Place معلومات عن مكان معيّن. يمكنك الحصول على كائن Place بالطرق التالية:

• الاتصال بـ PlacesClient.fetchPlace() : للاطّلاع على دليل الحصول على مكان باستخدام مستند تعريف
• الاتصال بـ PlacesClient.findCurrentPlace() – للاطّلاع على دليل الحصول على المكان الحالي
  مع أنّ PlacesClient.fetchPlace() تتوافق مع جميع حقول بيانات الأماكن، فإنّ PlacesClient.findCurrentPlace() لا يتوافق إلا مع مجموعة فرعية من حقول بيانات الأماكن. للحصول على قائمة بالحقول غير المتوافقة مع findCurrentPlace()، يُرجى الاطّلاع على التوافق مع حقول حزمة تطوير البرامج (SDK) للأماكن في Android.

عندما تطلب مكانًا، يجب عليك تحديد بيانات المكان التي تريد عرضها. للقيام بذلك، مرر قائمة من قيم Place.Field تحدد البيانات المطلوب عرضها. تُعدّ هذه القائمة اعتبارًا من الاعتبار، لأنّها تؤثر في تكلفة كل طلب.

بسبب عدم إمكانية أن تكون نتائج بيانات المكان فارغة، يتم عرض فقط نتائج الأماكن التي تحتوي على بيانات (على سبيل المثال، إذا لم يكن المكان المطلوب لا يحتوي على صور، لن يكون الحقل photos متاحًا في النتيجة).

يمرر المثال التالي قائمة من ثلاث قيم لحقل Place.Field لتحديد البيانات التي يتم عرضها بواسطة الطلب:

Kotlin

// Specify the fields to return.
val placeFields = listOf(Place.Field.NAME, Place.Field.RATING, Place.Field.OPENING_HOURS)

Java

// Specify the fields to return.
final List placeFields = Arrays.asList(Place.Field.NAME, Place.Field.RATING, Place.Field.OPENING_HOURS);

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

الوصول إلى حقول بيانات عنصر المكان

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

• getAddress(): عنوان المكان بتنسيق يمكن للمستخدمين قراءته.
• getAddressComponents() – List من عناصر العنوان لهذا المكان. يتم توفير هذه المكوّنات بغرض استخراج المعلومات المنظَّمة حول عنوان المكان، مثل العثور على المدينة التي يقع فيها ذلك المكان. ولا تستخدم هذه المكوّنات لتنسيق العنوان، بل يمكنك استخدام السمة getAddress() التي توفّر عنوانًا منسّقًا مترجَمًا.
• getId() – المعرّف النصي للمكان. يمكنك الاطّلاع على مزيد من المعلومات عن معرّفات الأماكن في بقية هذه الصفحة.
• getLatLng() – الموقع الجغرافي للمكان، ويتم تحديده كإحداثيات خطوط الطول والعرض.
• getName() – اسم المكان

• getOpeningHours() – OpeningHours للمكان يمكنك الاتصال بالرقم OpeningHours.getWeekdayText() لعرض قائمة بالسلاسل التي تمثّل ساعات الفتح والإغلاق لكل يوم من الأسبوع. يمكنك استدعاء OpeningHours.getPeriods() لعرض قائمة تضم عناصر period مع معلومات أكثر تفصيلاً تعادل البيانات المقدَّمة من getWeekdayText().

  ملاحظة: إذا كان المكان مفتوحًا دائمًا، يتم تمثيل الفترة الزمنية يوم الأحد عند منتصف الليل، وتكون القيمة closeEvent فارغة.

  يحتوي الكائن Place أيضًا على طريقة getCurrentOpeningHours() التي تعرض ساعات عمل المكان خلال الأيام السبعة التالية، وgetSecondaryOpeningHours() التي تعرض ساعات العمل الثانوية للمكان خلال الأيام السبعة التالية.

• isOpen() – تشير إلى ما إذا كان المكان مفتوحًا حاليًا. إذا لم يتم تحديد وقت، يكون الوقت التلقائي هو الآن. لن يتم إرجاع isOpen إلا إذا كانت السمتان Place.Field.UTC_OFFSET و Place.Field.OPENING_HOURS متاحة. لضمان الحصول على نتائج دقيقة، يُرجى طلب الحقلين Place.Field.BUSINESS_STATUS وPlace.Field.UTC_OFFSET في طلب المكان الأصلي. في حال عدم طلب ذلك، يُفترض أن يكون النشاط التجاري قيد التشغيل. يمكنك مشاهدة هذا الفيديو للتعرّف على كيفية استخدام isOpen مع "تفاصيل المكان".

  ملاحظة: تم إيقاف هذه الطريقة نهائيًا. استخدِم PlacesClient.isOpen(IsOpenRequest request) بدلاً من ذلك. ولمزيد من المعلومات، يمكنك الاطّلاع على التعرُّف على الحالة "مفتوح".

إليك بعض الأمثلة البسيطة:

Kotlin

val name = place.name
val address = place.address
val location = place.latLng

      

Java

final CharSequence name = place.getName();
final CharSequence address = place.getAddress();
final LatLng location = place.getLatLng();

      

الوصول إلى بيانات المكان التي تمت إضافتها في الإصدار 3.3.0

يضيف الإصدار 3.3.0 من حزمة تطوير برامج الأماكن لنظام التشغيل Android بيانات جديدة إلى Place:

• أنواع الأماكن: قيم الأنواع الجديدة المرتبطة بالمكان
• المراجعات: ما يصل إلى خمس مراجعات عن المكان.
• رمز لغة الاسم: رمز اللغة لاسم مكان معيّن.

توضح الأقسام التالية كيفية الوصول إلى هذه البيانات الجديدة.

ملاحظة: تتوافق حزمة تطوير البرامج (SDK) الجديدة فقط مع بيانات Place الجديدة في لغة Java.

الوصول إلى أنواع أماكن جديدة

ويمكن أن يكون لكل مكان قيمة واحدة أو أكثر من قيم type مرتبطة به. تضيف حزمة تطوير برامج الأماكن لنظام التشغيل Android الإصدار 3.3.0 العديد من قيم الأنواع الجديدة. للحصول على القائمة الكاملة، راجع أنواع الأماكن الموسَّعة.

في حزمة تطوير برامج الأماكن لنظام التشغيل Android الإصدار 3.2.0 والإصدارات الأقدم، استخدمت طريقة Place.getTypes() للوصول إلى قيم النوع المرتبطة بالمكان. تعرض Place.getTypes() قائمة الأنواع كقيم تعداد يتم تحديدها بواسطة Place.Types.

تم إيقاف طريقة Place.getTypes() اعتبارًا من الإصدار 3.3.0 من حزمة SDK للأماكن لنظام التشغيل Android. ومع أنّه يمكنك مواصلة استخدامه خلال فترة الإيقاف النهائي، عليك نقل بيانات تطبيقاتك لاستخدام Place.getPlaceTypes() بدلاً من ذلك.

تعرض الطريقة Place.getPlaceTypes() قيم النوع كقائمة من قيم السلسلة. تعتمد القيم التي يتم عرضها على إصدار حزمة SDK للأماكن لنظام التشغيل Android:

• حزمة SDK لأماكن Android (جديدة): تعرض السلاسل المحدّدة في الجدول "أ" والجدول "ب" والمعروضَين في أنواع الأماكن (جديد)، بما في ذلك جميع أنواع الأماكن المضافة التي تمت إضافتها في الإصدار 3.3.0.
• حزمة تطوير برامج الأماكن لنظام التشغيل Android: تعرض التعدادات التي حدّدتها Place.Types، ولا تشمل الأنواع الجديدة التي تمت إضافتها في الإصدار 3.3.0.

للتعرّف على الاختلافات الرئيسية بين إصدارَي حزمة SDK، يُرجى الاطّلاع على مقالة اختيار إصدار حزمة SDK.

الوصول إلى مراجعات الأماكن

تُضيف حزمة تطوير البرامج (SDK) الخاصة بالأماكن لنظام التشغيل Android (الجديدة) الفئة Review التي تحتوي على مراجعة لمكان. ويمكن أن يحتوي الكائن Place على ما يصل إلى خمس مراجعات.

يمكن أن تحتوي الفئة Review أيضًا على الإسناد والإحالة إلى المؤلف. إذا عرضت المراجعة في تطبيقك، عليك أيضًا عرض أي إحالة أو مؤلف. للمزيد من المعلومات، راجع عرض مراجعة.

لتعبئة العنصر Place بالمراجعات، يجب استيفاء الشروط التالية:

1. عليك تفعيل حزمة تطوير البرامج (SDK) الجديدة عند إعداد مشروعك على Google Cloud.
2. إعداد حزمة تطوير البرامج (SDK) الجديدة ضمن نشاط أو جزء
3. أدرِج Place.Field.REVIEWS في قائمة حقول طلب تفاصيل المكان.
4. يمكنك الاتصال بالرقم PlacesClient.fetchPlace(). لا يُسمَح باستخدام حقل المراجعات في PlacesClient.findCurrentPlace().
5. استخدِم طريقة Place.getReviews() للوصول إلى حقل بيانات المراجعات في عنصر Place.

الوصول إلى رمز لغة اسم المكان

تعرض طريقة Place.getName() الحالية سلسلة نصية تحتوي على اسم مكان. لتعبئة الكائن Place باسم المكان، يجب تضمين Place.Field.NAME في قائمة الحقول الخاصة بطلب تفاصيل المكان.

يحتوي الكائن Place الآن على رمز اللغة لسلسلة الاسم. لملء الكائن Place برمز اللغة، يجب:

1. عليك تفعيل حزمة تطوير البرامج (SDK) الجديدة عند إعداد مشروعك على Google Cloud.
2. إعداد حزمة تطوير البرامج (SDK) الجديدة ضمن نشاط أو جزء
3. أدرِج Place.Field.NAME في قائمة حقول الطلب. تضبط هذه القيمة الاستجابة لتضمين كل من اسم المكان ورمز اللغة في الكائن Place.
4. يمكنك الاتصال بالرقم PlacesClient.fetchPlace(). PlacesClient.findCurrentPlace() غير متوافق مع حقل رمز اللغة.
5. استخدِم الطريقة Place.getNameLanguageCode() للوصول إلى حقل رمز اللغة في الكائن Place.

تحديد رمز المنطقة في الإصدار 3.3.0

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

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

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

الحصول على مكان باستخدام مستند تعريف

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

للوصول إلى مكان من خلال رقم التعريف، يُرجى الاتصال بالرقم PlacesClient.fetchPlace() مع تمرير FetchPlaceRequest.

تعرض واجهة برمجة التطبيقات FetchPlaceResponse في Task. يحتوي FetchPlaceResponse على عنصر Place يتطابق مع رقم تعريف المكان الذي تم تقديمه.

يعرض مثال الرمز التالي استدعاء fetchPlace() للحصول على تفاصيل للمكان المحدد.

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")
        }
    }

      

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.
    }
});

      

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

الحصول على الحالة "مفتوح"

تعرض الطريقة PlacesClient.isOpen(IsOpenRequest request) كائن IsOpenResponse يشير إلى ما إذا كان المكان مفتوحًا حاليًا استنادًا إلى الوقت المحدد في الاستدعاء.

تستخدم هذه الطريقة وسيطة واحدة من النوع IsOpenRequest تحتوي على:

• تمثّل هذه السمة كائن Place أو سلسلة تحدّد رقم تعريف مكان.
  ملاحظة: يجب أن يحتوي الكائن Place على رقم تعريف مكان صالح.
• قيمة وقت اختيارية تحدد الوقت بالمللي ثانية من 1970-01-01T00:00:00Z. إذا لم يتم تحديد وقت، يكون الوقت التلقائي هو الآن.

تتطلّب هذه الطريقة توفّر الحقول التالية في الكائن Place:

• Place.Field.BUSINESS_STATUS
• Place.Field.CURRENT_OPENING_HOURS
• Place.Field.OPENING_HOURS
• Place.Field.UTC_OFFSET

إذا لم تتوفر هذه الحقول في عنصر Place أو إذا ضبطت رقم تعريف مكان، تستخدم الطريقة PlacesClient.fetchPlace() لجلبها. لمزيد من المعلومات حول إنشاء كائن المكان باستخدام الحقول الضرورية، راجع تفاصيل المكان.

ملاحظة: يتم تحصيل رسوم من رمز رمز التخزين التعريفي للبيانات الأساسية الخاص بالأماكن مقابل المكالمات الواردة إلى fetchPlace() في Place.Field.UTC_OFFSET و Place.Field.BUSINESS_STATUS. يتم تحصيل رسوم من رمز التخزين التعريفي لبيانات جهات الاتصال الخاصة بالأماكن مقابل المكالمات التي يتم إجراؤها إلى fetchPlace() في Place.Field.CURRENT_OPENING_HOURS وPlace.Field.OPENING_HOURS.

يحدّد المثال التالي ما إذا كان المكان مفتوحًا حاليًا. في هذا المثال، يتم تمرير معرّف المكان فقط إلى isOpen():

Kotlin

val isOpenCalendar: Calendar = Calendar.getInstance()
val placeId = "ChIJD3uTd9hx5kcR1IQvGfr8dbk"

val request: IsOpenRequest = try {
    IsOpenRequest.newInstance(placeId, isOpenCalendar.timeInMillis)
} catch (e: IllegalArgumentException) {
    e.printStackTrace()
    return
}
val isOpenTask: Task<IsOpenResponse> = placesClient.isOpen(request)
isOpenTask.addOnSuccessListener { response ->
    val isOpen = response.isOpen
}
// ...

      

Java

@NonNull
Calendar isOpenCalendar = Calendar.getInstance();
String placeId = "ChIJD3uTd9hx5kcR1IQvGfr8dbk";
IsOpenRequest isOpenRequest;

try {
    isOpenRequest = IsOpenRequest.newInstance(placeId, isOpenCalendar.getTimeInMillis());
} catch (IllegalArgumentException e) {
    e.printStackTrace();
    return;
}

Task<IsOpenResponse> placeTask = placesClient.isOpen(isOpenRequest);

placeTask.addOnSuccessListener(
        (response) ->
                isOpen = response.isOpen());
// ...

      

يوضّح المثال التالي استدعاء isOpen() حيث يتم تمرير عنصر Place. يجب أن يحتوي الكائن Place على رقم تعريف مكان صالح:

Kotlin

val isOpenCalendar: Calendar = Calendar.getInstance()
var place: Place
val placeId = "ChIJD3uTd9hx5kcR1IQvGfr8dbk"
// Specify the required fields for an isOpen request.
val placeFields: List<Place.Field> = listOf(
    Place.Field.BUSINESS_STATUS,
    Place.Field.CURRENT_OPENING_HOURS,
    Place.Field.ID,
    Place.Field.OPENING_HOURS,
    Place.Field.UTC_OFFSET
)

val placeRequest: FetchPlaceRequest =
    FetchPlaceRequest.newInstance(placeId, placeFields)
val placeTask: Task<FetchPlaceResponse> = placesClient.fetchPlace(placeRequest)
placeTask.addOnSuccessListener { placeResponse ->
    place = placeResponse.place

    val isOpenRequest: IsOpenRequest = try {
        IsOpenRequest.newInstance(place, isOpenCalendar.timeInMillis)
    } catch (e: IllegalArgumentException) {
        e.printStackTrace()
        return@addOnSuccessListener
    }
    val isOpenTask: Task<IsOpenResponse> = placesClient.isOpen(isOpenRequest)
    isOpenTask.addOnSuccessListener { isOpenResponse ->
        val isOpen = isOpenResponse.isOpen
    }
    // ...
}
// ...

      

Java

@NonNull
Calendar isOpenCalendar = Calendar.getInstance();
String placeId = "ChIJD3uTd9hx5kcR1IQvGfr8dbk";
// Specify the required fields for an isOpen request.
List<Place.Field> placeFields = new ArrayList<>(Arrays.asList(
        Place.Field.BUSINESS_STATUS,
        Place.Field.CURRENT_OPENING_HOURS,
        Place.Field.ID,
        Place.Field.OPENING_HOURS,
        Place.Field.UTC_OFFSET
));

FetchPlaceRequest request = FetchPlaceRequest.newInstance(placeId, placeFields);
Task<FetchPlaceResponse> placeTask = placesClient.fetchPlace(request);

placeTask.addOnSuccessListener(
        (placeResponse) -> {
            Place place = placeResponse.getPlace();
            IsOpenRequest isOpenRequest;

            try {
                isOpenRequest = IsOpenRequest.newInstance(place, isOpenCalendar.getTimeInMillis());
            } catch (IllegalArgumentException e) {
                e.printStackTrace();
                return;
            }
            Task<IsOpenResponse> isOpenTask = placesClient.isOpen(isOpenRequest);

            isOpenTask.addOnSuccessListener(
                    (isOpenResponse) -> isOpen = isOpenResponse.isOpen());
            // ...
        });
// ...

      

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

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

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

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

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

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