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

اختَر النظام الأساسي: 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);

ملاحظة: تتوافق كل من منصة Places SDK لنظام التشغيل Android وحزمة تطوير البرامج (SDK) لـ "Places 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

تضيف حزمة تطوير برامج الأماكن لأجهزة Android الإصدار 3.3.0 بيانات جديدة إلى 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.
• حزمة تطوير برامج الأماكن (SDK) لنظام التشغيل Android: تعرض التعدادات التي تحدّدها Place.Types، والتي لا تشمل الأنواع الجديدة التي تمت إضافتها في الإصدار 3.3.0.

لمعرفة الاختلافات الرئيسية بين إصدارَي حزمة تطوير البرامج (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());
            // ...
        });
// ...

      

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

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

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

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

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

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