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

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

إن حزمة تطوير البرامج للأماكن لنظام التشغيل 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<Place.Field> 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().

  ملاحظة: إذا كان المكان مفتوحًا دائمًا، يتم تمثيل الفترة الزمنية على أنّها الأحد في منتصف الليل، وتكون 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();

      

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

رقم تعريف المكان هو معرّف نصي يُعرِّف المكان بشكل فريد. في حزمة تطوير برامج الأماكن لنظام التشغيل 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، راجِع إعداد عميل Places API.

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

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

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