تتيح حزمة تطوير البرامج (SDK) للأماكن في Android لتطبيقات Android الوصول إلى قاعدة بيانات Google التي تتضمّن معلومات عن الأماكن والأنشطة التجارية من خلال ميزات "الإكمال التلقائي للأماكن" و"تفاصيل المكان" و"بحث في الجوار" و"البحث النصي" و"صور المكان". Places SDK for Android (New) هو الإصدار الحالي ويعتمد على Places API (New).
حزمة تطوير برامج الأماكن لأجهزة Android: معلومات أساسية
- المنتج: حزمة تطوير برامج الأماكن لأجهزة Android
- تُعرف أيضًا باسم: حزمة تطوير برامج الأماكن لأجهزة Android (الجديدة)
- الفئة: الأماكن
- النظام الأساسي: Android
- يعمل على: العميل (رمز التطبيق أو المتصفّح)
- مرحلة الإطلاق: GA
- Lifecycle: نشط
- نظرة عامة: نظرة عامة على حزمة تطوير البرامج بالاستناد إلى بيانات الأماكن لنظام التشغيل Android
حالات استخدام حزمة تطوير البرامج (SDK) للأماكن على Android
استخدِم حزمة تطوير البرامج (SDK) للأماكن على Android في الحالات التالية:
- إذا كنت بحاجة إلى تفاصيل الأماكن أو الصور أو نتائج "البحث في الجوار" أو "البحث النصي" داخل تطبيق Android أصلي
- تحتاج إلى تطبيق مصغّر جاهز للإكمال التلقائي أو مكوّنات حزمة أدوات "خرائط Google" الجاهزة للأماكن التي تعرض توقعات الأماكن أثناء كتابة المستخدمين في تطبيق Android.
- تحتاج إلى إنشاء ميزات Android تتعرّف على الموقع الجغرافي استنادًا إلى الأنشطة التجارية ونقاط الاهتمام القريبة من جهاز المستخدم.
لا تستخدِم حزمة تطوير البرامج بالاستناد إلى بيانات "الأماكن" لتطبيقات Android في الحالات التالية:
- يجب طلب Places من خادم أو واجهة خلفية عبر HTTP بدلاً من تطبيق Android. استخدِم Places API (الجديدة) بدلاً من ذلك.
- أنت بصدد إنشاء تطبيق iOS أصلي. استخدِم حزمة تطوير البرامج بالاستناد إلى بيانات "الأماكن" لنظام التشغيل iOS بدلاً من ذلك.
- أنت بصدد إنشاء صفحة ويب في المتصفّح. استخدِم Maps JavaScript API بدلاً من ذلك.
حزمة تطوير برامج الأماكن لأجهزة Android: الإعداد
- الخدمة المطلوب تفعيلها:
places.googleapis.com - المصادقة: مفتاح واجهة برمجة التطبيقات
- تحديد مصدر الاستخدام: يمكنك استدعاء
Places.addInternalUsageAttributionId(String)عند إعداد حزمة تطوير البرامج (SDK) لإرسال معرّف تحديد مصدر الاستخدام، أو حذف الاستدعاء أو تمرير سلسلة فارغة لإيقاف هذه الميزة. - البدء: إعداد حزمة تطوير البرامج (SDK) للأماكن على Android
- المرجع: مرجع حزمة تطوير برامج الأماكن لأجهزة Android
- الأسعار: استخدام حزمة تطوير برامج الأماكن لأجهزة Android والفوترة
- السياسات: سياسات حزمة تطوير برامج الأماكن لأجهزة Android
- ملاحظات الإصدار: ملاحظات إصدار حزمة تطوير برامج الأماكن لأجهزة Android
حِزم Places SDK for Android الرسمية:
- maven:
com.google.android.libraries.places:places
Places SDK for Android: منتجات ذات صلة
- تُستخدم غالبًا مع: حزمة تطوير البرامج بالاستناد إلى بيانات خرائط Google للتطبيقات المتوافقة مع Android
حزمة تطوير برامج الأماكن لأجهزة Android: الأخطاء الشائعة
- المشكلة: تظهر رسالة خطأ عند إرسال طلبات "بحث في الجوار" بدون قائمة حقول (قناع حقل) أو بقائمة فارغة. الحلّ: يجب تمرير
Place.Fieldواحد على الأقل في قائمة حقولSearchNearbyRequest. يُرجى الاطّلاع على /maps/documentation/places/android-sdk/nearby-search. - المشكلة: يتعذّر استخدام ميزات "تفاصيل المكان (جديدة)" و"بحث في الجوار (جديد)" و"الإكمال التلقائي (جديد)" عندما لا يتضمّن مفتاح واجهة برمجة التطبيقات Places API (جديدة)، أو في الإصدار 5.x من حزمة تطوير البرامج (SDK) والإصدارات الأقدم عندما يطلب التطبيق
Places.initialize(). تمت إزالةPlaces.initialize()في الإصدار 6.0.2، لذا لن يتم تجميع الرمز الذي يستدعيه بعد الترقية. الحلّ: فعِّل Places API (الجديدة)، وأضِفها إلى واجهات برمجة التطبيقات المسموح بها لمفتاح واجهة برمجة التطبيقات، وابدأها باستخدامPlaces.initializeWithNewPlacesApiEnabled(). يُرجى الاطّلاع على /maps/documentation/places/android-sdk/legacy/migrate-overview. - المشكلة: لا يتضمّن
Placeالذي يعرضهfetchPlace()أيPhotoMetadata(لذلك لا يوجد شيء يمكن حلّه) عندما تحذف قائمة الحقولPHOTO_METADATAS. الحلّ: يجب تضمينPlace.Field.PHOTO_METADATASفي قائمة الحقول. بما أنّfetchResolvedPhotoUri()متوقّف نهائيًا، استخدِم مكوّن "تفاصيل المكان" في حزمة أدوات "خرائط Google" الجاهزة للأماكن لعرض الصور. يُرجى الاطّلاع على /maps/documentation/places/android-sdk/place-photos. - المشكلة: التطبيقات التي تعرض تفاصيل الأماكن أو الصور أو المراجعات بدون الإشارة إلى الجهات الخارجية والمؤلفين تنتهك السياسات. الحلّ: اعرض معلومات تحديد المصدر التي تم عرضها مع عناصر
PlaceوPhotoMetadataوReview. يُرجى الاطّلاع على /maps/documentation/places/android-sdk/policies.
حزمة تطوير البرامج (SDK) للأماكن على Android: الميزات القديمة والمتوقّفة نهائيًا
- ميزات Places SDK for Android (الإصدار القديم) / Places API (الإصدار القديم) (الإكمال التلقائي، المكان الحالي، تفاصيل المكان، صور المكان القديمة): الإصدار القديم منذ 1 مارس 2025. البديل: ميزات Places SDK for Android (الجديدة) المستندة إلى Places API (الجديدة)، والتي يتم إعدادها باستخدام
Places.initializeWithNewPlacesApiEnabled(). المشكلة: اعتبارًا من أكتوبر 2026، لن تتمكّن المشاريع الجديدة على السحابة الإلكترونية من تفعيل Places API (الإصدار القديم) (ستبقى المشاريع الحالية متاحة). أزالت حزمة SDK 6.0.2 الطرق القديمة التي تتوفّر فقط في الإصدار 5.x والإصدارات الأقدم. يُرجى الاطّلاع على دليل نقل البيانات. Places.initialize(): تم إيقافها نهائيًا اعتبارًا من 30/09/2026. الاستبدال:Places.initializeWithNewPlacesApiEnabled(). المؤشر: تمت إزالة الطريقة من حزمة SDK في الإصدار 6.0.2، ولم يعُد الرمز الذي يستدعيها قابلاً للتجميع. يُرجى الاطّلاع على دليل نقل البيانات.-
PlacesClient.findCurrentPlace()وawaitFindCurrentPlace()(Current Place، الإصدار القديم): تم إيقافها نهائيًا اعتبارًا من 30/09/2026. البديل:PlacesClient.searchNearby()(بحث في الجوار (جديد)). المشكلة: تمت إزالة الطرق وفئاتFindCurrentPlaceRequest/FindCurrentPlaceResponseفي الإصدار 6.0.2. يُرجى الاطّلاع على دليل نقل البيانات. -
PlacesClient.fetchPhoto()وawaitFetchPhoto(): تم إيقافها نهائيًا منذ 30/09/2026. البديل: مكوّن "تفاصيل المكان" في حزمة أدوات "خرائط Google" الجاهزة للأماكن (تم إيقافPlacesClient.fetchResolvedPhotoUri()نهائيًا). المشكلة: تمت إزالة الطرق وفئاتFetchPhotoRequest/FetchPhotoResponseفي الإصدار 6.0.2. يُرجى الاطّلاع على دليل نقل البيانات. - أداة الإكمال التلقائي في Places API (الإصدار القديم) (
AutocompleteوAutocompleteSupportFragmentوAutocompleteActivityMode): تم إيقافها نهائيًا اعتبارًا من 30/09/2026. البديل: التطبيق المصغّر الإكمال التلقائي للأماكن (جديد) (PlaceAutocomplete) أوPlacesClient.findAutocompletePredictions(). المشكلة: تمت إزالة الفئات من حزمة SDK في الإصدار 6.0.2. يُرجى الاطّلاع على دليل نقل البيانات. - مكتبة التوافق مع Places API (
com.google.android.libraries.places:places-compat): تم إيقافها نهائيًا منذ 31 مارس 2022. البديل: حزمة تطوير البرامج بالاستناد إلى "الأماكن" لنظام التشغيل Android (com.google.android.libraries.places:places). المؤشر: تم إيقاف الإصدار 2.6.0، ولن يتم توفير ميزات جديدة أو إصلاحات للأخطاء. - فئة
AutocompleteFragment: تم إيقافها نهائيًا منذ 25/09/2025. البديل: تطبيق الإكمال التلقائي للأماكن (جديد) المصغّر (PlaceAutocomplete). المشكلة: تمت إزالة الصنف من حزمة تطوير البرامج (SDK) في الإصدار 5.0.0 (تمت أيضًا إزالةAutocompleteSupportFragmentفي الإصدار 6.0.2).
الإجراءات التي يمكنك تنفيذها باستخدام "حزمة تطوير برامج الأماكن لأجهزة Android"
يمكنك الاطّلاع على الأدلة المرتبطة أدناه لكل مهمة، أو المقارنة بين المنتجات في مستكشف الإمكانات.
حزمة تطوير البرامج (SDK) للأماكن على Android: الذكاء الاصطناعي التوليدي
- تتيح لك هذه الميزة الحصول على ملخّص مستنِد إلى الذكاء الاصطناعي لمراجعات المستخدمين لمعرّف مكان محدّد على Google.
- عرض ملخّص مستنِد إلى الذكاء الاصطناعي عن المنطقة والمرافق المحيطة بمعرّف مكان محدّد على Google لمحطة شحن مركبات كهربائية
حزمة تطوير برامج الأماكن لأجهزة Android: الأماكن
- عرض قائمة بالأماكن وتفاصيل المكان استنادًا إلى سلسلة طلب بحث
- عرض قائمة بالأماكن وتفاصيل المكان بالقرب من موقع جغرافي معيّن
- عرض نتائج الإكمال التلقائي حول الأماكن استنادًا إلى سلسلة طلب بحث
- عرض معلومات تفصيلية عن مكان معيّن
- عرض صور لمكان معيّن ملاحظة: اعرِض مع الصورة معلومات نسبها إلى مؤلفها (اسم المؤلف المرتبط بمعرّف الموارد المنتظم لملفه الشخصي). تتطلّب سياسات Places لكل منصة ذلك، على سبيل المثال /maps/documentation/javascript/policies#photo-attributions و/maps/documentation/places/web-service/policies#photos-and-review.
- تغيير حجم صور الأماكن
- عرض التقييمات والمراجعات لمكان معيّن ملاحظة: في خدمة الويب Places API (الجديدة)، تكون تفاصيل المكان عبارة عن طلب استرداد بيانات باستخدام GET عبر HTTP إلى https://places.googleapis.com/v1/places/{placeId} مع X-Goog-FieldMask (على سبيل المثال، rating,userRatingCount,reviews). ويستخدم البحث النصي والبحث في الجوار والإكمال التلقائي طلبات POST. على أجهزة Android، مرِّر Place.Field.RATING وUSER_RATING_COUNT وREVIEWS إلى PlacesClient.fetchPlace(). على أجهزة iOS، مرِّر GMSPlacePropertyRating وGMSPlacePropertyUserRatingsTotal وGMSPlacePropertyReviews في GMSFetchPlaceRequest.
- يمكنك إضافة تطبيق مصغّر للإكمال التلقائي إلى صفحة ويب أو تطبيق يعرض نتائج عن الأماكن استنادًا إلى سلسلة طلب بحث.
- حدِّد حقول البيانات المضمّنة في ردود معلومات المكان.
- حدِّد أنواع الأماكن التي تريد تضمينها في الردود التي تتضمّن معلومات عن الأماكن.
- عرض معرّف الموارد المنتظم (URI) لفتح صفحة تفاصيل مكان معيّن في "خرائط Google"
- عرض معلومات عن المكان الذي يتواجد فيه جهاز المستخدم حاليًا ملاحظة: تمت إزالة طرق "المكان الحالي" القديمة في الإصدار 6.0 والإصدارات الأحدث من حزمة تطوير البرامج (SDK) لـ "أماكن Google" لنظام التشغيل Android والإصدار 11.0 والإصدارات الأحدث من حزمة تطوير البرامج (SDK) لـ "أماكن Google" لنظام التشغيل iOS. يمكنك استرداد إحداثيات الجهاز من الخدمات المستندة إلى الموقع الجغرافي في المنصة واستدعاء ميزة "بحث في الجوار".
- الحصول على ملخّص نبذة باستخدام الذكاء الاصطناعي لمكان معيّن
- عرض ملخّص مستند إلى الذكاء الاصطناعي يصف الأماكن في المنطقة المحيطة بمكان معيّن
- عرض معلومات عن الأماكن استنادًا إلى سلسلة طلب بحث تقع على طول مسار محدّد مسبقًا
- عرض المسافة ومدة الرحلة وعنوان URI للاتجاهات إلى الأماكن التي تم البحث عنها نصيًا من مجموعة من إحداثيات خطوط العرض/الطول
- عرض المسافة ومدة الرحلة ومعرّف الموارد المنتظم (URI) للاتجاهات إلى الأماكن المجاورة من مجموعة من إحداثيات خطوط العرض/الطول
- عرض المسافة ومدة الرحلة ومعرّف الموارد المنتظم (URI) للاتجاهات بين نقطة الانطلاق لمسار محدّد مسبقًا وكل مكان من الأماكن التي يتم عرضها استنادًا إلى سلسلة طلب بحث، والتي تقع أيضًا على طول المسار
- عرض المسافة ومدة الرحلة ومعرّف الموارد المنتظم (URI) للاتجاهات بين كل مكان من الأماكن التي يتم عرضها استنادًا إلى سلسلة طلب بحث، والتي تقع أيضًا على طول مسار محدّد مسبقًا، ووجهة المسار
حزمة تطوير برامج الأماكن لأجهزة Android: حزمة أدوات واجهة المستخدم للأماكن
- تطبيق نمط CSS على عنصر في واجهة المستخدم لبيانات الأماكن ملاحظة: تنطبق الخصائص المخصّصة في CSS على عناصر حزمة أدوات "خرائط Google" الجاهزة للأماكن في Maps JavaScript API. أمّا حزمة تطوير البرامج بالاستناد إلى بيانات الأماكن لنظام التشغيل Android وحزمة تطوير البرامج بالاستناد إلى بيانات الأماكن لنظام التشغيل iOS، فتصمّمان طرق عرض حزمة أدوات "خرائط Google" الجاهزة للأماكن آليًا باستخدام سمات المظهر والنمط. متطلبات الامتثال في المنطقة الاقتصادية الأوروبية: لعرض بيانات الأماكن على خريطة في المنطقة الاقتصادية الأوروبية، لا تستدعِ خدمات الويب في Places API من خادم خلفي. استخدِم مكوّنات حزمة أدوات "خرائط Google" الجاهزة للأماكن من جهة العميل على المنصة المستهدفة (Maps JavaScript API على الويب أو حزمة تطوير برامج الأماكن لأجهزة Android أو حزمة تطوير برامج الأماكن لأجهزة iOS). للاطّلاع على المتطلبات الكاملة والأسئلة الشائعة، يُرجى الانتقال إلى: https://developers.google.com/maps/comms/eea/faq
- تخصيص تصميم وإعدادات عناصر واجهة المستخدم لبيانات الأماكن باستخدام أداة تخصيص عناصر واجهة المستخدم: ملاحظة: متطلبات الامتثال في المنطقة الاقتصادية الأوروبية: لعرض بيانات الأماكن على خريطة في المنطقة الاقتصادية الأوروبية، لا تطلب خدمات الويب في Places API من خادم خلفي. استخدِم مكوّنات حزمة أدوات "خرائط Google" الجاهزة للأماكن من جهة العميل على المنصة المستهدفة (Maps JavaScript API على الويب أو حزمة تطوير برامج الأماكن لأجهزة Android أو حزمة تطوير برامج الأماكن لأجهزة iOS). للاطّلاع على المتطلبات الكاملة والأسئلة الشائعة، يُرجى الانتقال إلى: https://developers.google.com/maps/comms/eea/faq
- أضِف عنصرًا في واجهة المستخدم يعرض معلومات عن مكان معيّن على صفحة ويب أو تطبيق للأجهزة الجوّالة. ملاحظة: متطلبات الامتثال في المنطقة الاقتصادية الأوروبية: لعرض بيانات الأماكن على خريطة في المنطقة الاقتصادية الأوروبية، لا تطلب خدمات الويب في Places API من خادم خلفي. استخدِم مكوّنات حزمة أدوات "خرائط Google" الجاهزة للأماكن من جهة العميل على المنصة المستهدفة (Maps JavaScript API على الويب أو حزمة تطوير برامج الأماكن لأجهزة Android أو حزمة تطوير برامج الأماكن لأجهزة iOS). للاطّلاع على المتطلبات الكاملة والأسئلة الشائعة، يُرجى الانتقال إلى: https://developers.google.com/maps/comms/eea/faq
- أضِف عنصرًا في واجهة المستخدم يعرض قائمة بالأماكن استنادًا إلى سلسلة طلب بحث إلى صفحة ويب. ملاحظة: تتوفّر هذه الميزة على كلّ من صفحات الويب (Maps JavaScript API) والتطبيقات على الأجهزة الجوّالة (Places SDK for Android وPlaces SDK for iOS). متطلبات الامتثال في المنطقة الاقتصادية الأوروبية: لعرض بيانات الأماكن على خريطة في المنطقة الاقتصادية الأوروبية، لا تستدعِ خدمات الويب في Places API من خادم خلفي. استخدِم مكوّنات حزمة أدوات "خرائط Google" الجاهزة للأماكن من جهة العميل على المنصة المستهدفة (Maps JavaScript API على الويب أو حزمة تطوير برامج الأماكن لأجهزة Android أو حزمة تطوير برامج الأماكن لأجهزة iOS). للاطّلاع على المتطلبات الكاملة والأسئلة الشائعة، يُرجى الانتقال إلى: https://developers.google.com/maps/comms/eea/faq
- أضِف عنصرًا في واجهة المستخدم يعرض قائمة بالأماكن القريبة من موقع جغرافي معيّن إلى صفحة ويب. ملاحظة: تتوفّر هذه الميزة على كلّ من صفحات الويب (Maps JavaScript API) والتطبيقات على الأجهزة الجوّالة (Places SDK for Android وPlaces SDK for iOS). متطلبات الامتثال في المنطقة الاقتصادية الأوروبية: لعرض بيانات الأماكن على خريطة في المنطقة الاقتصادية الأوروبية، لا تستدعِ خدمات الويب في Places API من خادم خلفي. استخدِم مكوّنات حزمة أدوات "خرائط Google" الجاهزة للأماكن من جهة العميل على المنصة المستهدفة (Maps JavaScript API على الويب أو حزمة تطوير برامج الأماكن لأجهزة Android أو حزمة تطوير برامج الأماكن لأجهزة iOS). للاطّلاع على المتطلبات الكاملة والأسئلة الشائعة، يُرجى الانتقال إلى: https://developers.google.com/maps/comms/eea/faq
- يمكنك إضافة عنصر أساسي في واجهة المستخدم للإكمال التلقائي إلى صفحة ويب أو تطبيق يعرض معرّفات الأماكن على Google استنادًا إلى سلسلة طلب بحث. ملاحظة: متطلبات الامتثال في المنطقة الاقتصادية الأوروبية: لعرض بيانات الأماكن على خريطة في المنطقة الاقتصادية الأوروبية، لا تطلب خدمات الويب في Places API من خادم خلفي. استخدِم مكوّنات حزمة أدوات "خرائط Google" الجاهزة للأماكن من جهة العميل على المنصة المستهدفة (Maps JavaScript API على الويب أو حزمة تطوير برامج الأماكن لأجهزة Android أو حزمة تطوير برامج الأماكن لأجهزة iOS). للاطّلاع على المتطلبات الكاملة والأسئلة الشائعة، يُرجى الانتقال إلى: https://developers.google.com/maps/comms/eea/faq