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

المطوّرون في المنطقة الاقتصادية الأوروبية

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

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

يوفّر العنصر Place معلومات عن مكان معيّن. يمكنك الحصول على عنصر Place من خلال استدعاء PlacesClient.fetchPlace(). راجِع الدليل حول الحصول على مكان من خلال رقم التعريف.

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

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

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

Kotlin

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

Java

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

الوصول إلى حقول بيانات كائن "المكان"

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

  • 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();

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

معرّف المكان هو معرّف نصي يحدّد مكانًا بشكل فريد. في حزمة تطوير البرامج (SDK) الخاصة بـ "الأماكن في 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() لاستردادها. لمزيد من المعلومات حول إنشاء عنصر Place مع الحقول اللازمة، يُرجى الاطّلاع على تفاصيل المكان.

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

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

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