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

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

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

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

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

عندما تطلب مكانًا، يجب عليك تحديد بيانات المكان التي تريد عرضها. لإجراء ذلك، مرِّر قائمة من قيم 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);

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

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

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

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

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

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

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:

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

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

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

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

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

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

تعرض الطريقة Place.getPlaceTypes() قيم النوع كقائمة من قيم السلسلة. تعتمد القيم المعروضة على إصدارك من حزمة تطوير برامج الأماكن لـ Android:

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

      

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

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

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

  • عنصر 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() لاسترجاعها. لمزيد من المعلومات حول إنشاء كائن المكان باستخدام الحقول اللازمة، راجع تفاصيل المكان.

يحدّد المثال التالي ما إذا كان المكان مفتوحًا حاليًا. في هذا المثال، تمرِّر معرّف المكان إلى "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 هو المعرّف نفسه المستخدَم في واجهة برمجة تطبيقات الأماكن. ويمكن أن يشير رقم تعريف كل مكان إلى مكان واحد فقط، ولكن يمكن أن يتضمّن المكان الواحد أكثر من رقم تعريف مكان واحد. هناك ظروف أخرى قد تؤدي إلى حصول مكان على رقم تعريف جديد. على سبيل المثال، قد يحدث ذلك عند نقل نشاط تجاري إلى موقع جغرافي جديد.

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

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