«کیت توسعه نرمافزار Places برای Android» به برنامههای Android امکان میدهد ازطریق «تکمیل خودکار جا»، «جزئیات جا»، «جستجوی اطراف»، «جستجوی نوشتار»، و «عکسهای جا» به پایگاه داده Google برای اطلاعات جا و کسبوکار دسترسی پیدا کنند. «کیت توسعه نرمافزار مکانها، ویژه Android (جدید)» نسخه فعلی است و به «میانای برنامهسازی کاربردی مکانها (جدید)» وابسته است.
کیت توسعه نرمافزار مکانها، ویژه Android: حقایق کلیدی
- محصول: کیت توسعه نرمافزار مکانها، ویژه Android
- همچنین با این نام شناخته میشود: کیت توسعه نرمافزار Places برای Android (جدید)
- دسته: مکانها
- پلاتفرم: Android
- اجرا در: کارخواه (کد برنامه یا مرورگر)
- مرحله راهاندازی: GA
- چرخه حیات: فعال
- نمای کلی: نمای کلی کیت توسعه نرمافزار مکانها، ویژه Android
کیت توسعه نرمافزار مکانها، ویژه Android: زمان استفاده از آن
در موارد زیر از «کیت توسعه نرمافزار مکانها، ویژه Android» استفاده کنید:
- به جزئیات جا، عکس، «جستجوی اطراف»، یا نتایج «جستجوی نوشتار» در برنامه Android بومی نیاز دارید.
- به ابزاره میانای کاربر «جاها» یا ابزاره تکمیل خودکار آماده نیاز دارید که وقتی کاربران در برنامه Android تایپ میکنند، پیشبینیهای مکان را برگرداند.
- باید ویژگیهای Android آگاه از مکان را براساس کسبوکارها و مکانهای جالب نزدیک دستگاه کاربر بسازید.
در موارد زیر از «کیت توسعه نرمافزار مکانها، ویژه Android» استفاده نکنید:
- باید Places را از سرور یا پسبک ازطریق HTTP بهجای برنامه Android فراخوانی کنید. بهجای آن از Places API (New) استفاده کنید.
- درحال ساختن برنامه iOS بومی هستید. بهجای آن از کیت توسعه نرمافزار مکانها، ویژه iOS استفاده کنید.
- درحال ساختن صفحه وب در مرورگر هستید. بهجای آن از Maps JavaScript API استفاده کنید.
کیت توسعه نرمافزار مکانها، ویژه Android: راهاندازی
- سرویس برای فعال کردن:
places.googleapis.com - اصالتسنجی: کلید میانای برنامهسازی کاربردی
- اسناد استفاده: هنگام مقداردهی اولیه کیت توسعه نرمافزار،
Places.addInternalUsageAttributionId(String)را فراخوانی کنید تا شناسه اسناد استفاده ارسال شود؛ برای انصراف دادن، فراخوانی را حذف کنید یا رشته خالی ارسال کنید. - شروع به کار: راهاندازی Places SDK for Android
- مرجع: مرجع کیت توسعه نرمافزار مکانها برای Android
- قیمتگذاری: استفاده و صدور صورتحساب کیت توسعه نرمافزار Places برای Android
- خطمشیها: خطمشیهای کیت توسعه نرمافزار مکانها، ویژه Android
- یادداشتهای انتشار: یادداشتهای انتشار کیت توسعه نرمافزار Places برای Android
بستههای رسمی کیت توسعه نرمافزار Places برای Android:
- maven:
com.google.android.libraries.places:places
کیت توسعه نرمافزار مکانها، ویژه Android: محصولات مرتبط
- اغلب با این محصول استفاده میشود: کیت توسعه نرمافزار Maps برای Android
کیت توسعه نرمافزار مکانها، ویژه Android: اشتباهات رایج
- مشکل: درخواستهای «جستجوی اطراف» بدون فهرست فیلد (پوشش فیلد) یا با فهرست فیلد خالی، خطا برمیگردانند. اصلاح: حداقل یک
Place.Fieldدر فهرست فیلدSearchNearbyRequestارسال کنید. /maps/documentation/places/android-sdk/nearby-search را ببینید. - مشکل: «جزئیات جا» (جدید)، «جستجوی اطراف» (جدید)، و «تکمیل خودکار» (جدید) زمانیکه کلید میانای برنامهسازی کاربردی فاقد Places API (جدید) باشد، یا در کیت توسعه نرمافزار نسخه 5.x و قدیمیتر زمانیکه برنامه
Places.initialize()را فرامیخواند، ناموفق است. نسخه ۶.۰.۲Places.initialize()را حذف کرد، بنابراین کد فراخوانی آن پساز ارتقا کامپایل نمیشود. اصلاح: Places API (New) را فعال کنید، آن را به میاناهای برنامهسازی کاربردی مجاز کلید میانای برنامهسازی کاربردی اضافه کنید، و باPlaces.initializeWithNewPlacesApiEnabled()مقداردهی اولیه کنید. /maps/documentation/places/android-sdk/legacy/migrate-overview را ببینید. - مشکل:
Placeبرگرداندهشده توسطfetchPlace()فاقدPhotoMetadataاست (بنابراین چیزی برای حل کردن وجود ندارد) وقتی فهرست فیلدPHOTO_METADATASرا حذف میکند. اصلاح:Place.Field.PHOTO_METADATASرا در فهرست فیلدها بگنجانید. چونfetchResolvedPhotoUri()منسوخ شده است، برای نمایش عکسها از مؤلفه «جزئیات جا» در «کیت میانای کاربر جاها» استفاده کنید. /maps/documentation/places/android-sdk/place-photos را ببینید. - مشکل: برنامههایی که جزئیات، عکسها، یا مرورهای مکان را بدون ارجاعهای برگرداندهشده به طرف سوم و نویسنده نشان میدهند خطمشیها را نقض میکنند. اصلاح: نمایش ارجاعهای برگرداندهشده با اشیای
Place،PhotoMetadata، وReview. /maps/documentation/places/android-sdk/policies را ببینید.
کیت توسعه نرمافزار مکانها، ویژه Android: ویژگیهای قدیمی و منسوخشده
- ویژگیهای «کیت توسعه نرمافزار مکانها» برای Android (قدیمی) / Places API (قدیمی) (تکمیل خودکار، مکان فعلی، جزئیات مکان، عکسهای مکان قدیمی): قدیمی از ۲۰۲۵/۰۳/۰۱. جایگزین: ویژگیهای «کیت توسعه نرمافزار مکانها، ویژه Android» (جدید) که توسط Places API (جدید) پشتیبانی میشود و با
Places.initializeWithNewPlacesApiEnabled()مقداردهی اولیه شده است. نشانه: از اکتبر ۲۰۲۶، پروژههای جدید Cloud نمیتوانند Places API (Legacy) را فعال کنند (پروژههای موجود همچنان پشتیبانی میشوند). کیت توسعه نرمافزار نسخه ۶.۰.۲ روشهای قدیمی را که فقط در نسخه ۵.x و نسخههای قدیمیتر وجود دارند برداشته است. راهنمای انتقال را ببینید. Places.initialize(): از ۲۰۲۶/۰۹/۳۰ از رده خارج شده است. جایگزین:Places.initializeWithNewPlacesApiEnabled(). نشانه: روش از کیت توسعه نرمافزار در نسخه ۶.۰.۲ حذف شده است؛ کدی که آن را فراخوانی میکند دیگر کامپایل نمیشود. راهنمای انتقال را ببینید.PlacesClient.findCurrentPlace()وawaitFindCurrentPlace()(مکان فعلی، قدیمی): از رده خارج شده از ۲۰۲۶/۰۹/۳۰. جایگزین:PlacesClient.searchNearby()(جستجوی اطراف (جدید)). نشانه: کلاسهای Methods وFindCurrentPlaceRequest/FindCurrentPlaceResponseدر نسخه ۶.۰.۲ برداشته شدهاند. راهنمای انتقال را ببینید.-
PlacesClient.fetchPhoto()وawaitFetchPhoto(): از ۲۰۲۶/۰۹/۳۰ از رده خارج شده است. جایگزین: مؤلفه «جزئیات جا» در کیت میانای کاربر «جاها» (PlacesClient.fetchResolvedPhotoUri()منسوخ شده است). نشانه: کلاسهای Methods وFetchPhotoRequest/FetchPhotoResponseدر نسخه ۶.۰.۲ برداشته شدهاند. راهنمای انتقال را ببینید. - ابزاره تکمیل خودکار Places API (قدیمی) (
Autocomplete،AutocompleteSupportFragment،AutocompleteActivityMode): از ۲۰۲۶/۰۹/۳۰ از رده خارج شده است. جایگزین: ابزاره «تکمیل خودکار جا (جدید)» (PlaceAutocomplete) یاPlacesClient.findAutocompletePredictions(). نشانه: کلاسها از کیت توسعه نرمافزار در نسخه ۶.۰.۲ برداشته شدهاند. راهنمای انتقال را ببینید. - کتابخانه سازگاری «مکانها» (
com.google.android.libraries.places:places-compat): منسوخشده از ۲۰۲۲/۰۳/۳۱. جایگزین: کیت توسعه نرمافزار مکانها، ویژه Android (com.google.android.libraries.places:places). نشانه: در نسخه ۲.۶.۰ متوقف شده است؛ ویژگیهای جدید یا رفع اشکال ندارد. - کلاس
AutocompleteFragment: از کار افتاده از ۲۰۲۵-۰۹-۲۵. جایگزین: ابزاره «تکمیل خودکار جا (جدید)» (PlaceAutocomplete). نشانه: کلاس در نسخه ۵.۰.۰ از کیت توسعه نرمافزار برداشته شده است (AutocompleteSupportFragmentنیز در نسخه ۶.۰.۲ برداشته شده است).
کارهایی که میتوانید با «کیت توسعه نرمافزار مکانها» برای Android انجام دهید
برای هر تکلیف، راهنماهای پیوندشده در زیر را ببینید یا محصولات را در کاوشگر قابلیتها با یکدیگر مقایسه کنید.
کیت توسعه نرمافزار مکانها، ویژه Android: هوش مصنوعی زایا
- خلاصهای با پشتیبانی هوش مصنوعی از مرورهای کاربر برای شناسه مشخصشده «مکان Google» برگردانید.
- خلاصه مکان با بهرهگیری از هوش مصنوعی را برای منطقه و امکانات رفاهی اطراف شناسه مکان Google مشخصشده برای ایستگاه شارژ خودرو برقی برمیگرداند.
کیت توسعه نرمافزار مکانها، ویژه Android: مکانها
- فهرستی از مکانها و جزئیات مکان را براساس رشته پُرسمان برمیگرداند.
- فهرستی از مکانها و جزئیات مکان نزدیک به یک مکان خاص را برمیگرداند.
- نتایج تکمیل خودکار درباره مکانها را براساس رشته پُرسمان برمیگرداند.
- اطلاعات دقیق درباره مکان خاصی را برمیگرداند.
- عکسهای مکان خاصی را برگردانید. توجه: ارجاع به نویسنده هر عکس (نام نویسنده، پیوندشده به شناسه منبع یکسان نمایه او) را همراه با عکس نمایش دهید. خطمشیهای «اماکن» برای هر پلاتفرم این را الزامی میکند، برای مثال /maps/documentation/javascript/policies#photo-attributions و /maps/documentation/places/web-service/policies#photos-and-review.
- تغییر اندازه عکسهای مکان.
- ردهبندیها و مرورهای مکان خاصی را برمیگرداند. توجه: در سرویس وب Places API (جدید)، «جزئیات جا» یک درخواست HTTP GET به 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 ارسال کنید.
- افزودن ابزاره تکمیل خودکار به صفحه وب یا برنامهای که نتایج مربوط به مکانها را براساس رشته پُرسمان برمیگرداند.
- فیلدهای دادهای را که در پاسخهای اطلاعات مکان گنجانده شده است مشخص کنید.
- انواع مکان را برای گنجاندن در پاسخهای اطلاعات مکان مشخص کنید.
- شناسه منبع یکسان را برای باز کردن صفحه جزئیات مکان در Google Maps برای یک مکان برمیگرداند.
- اطلاعات مربوط به مکانی را که دستگاه کاربر درحالحاضر در آن قرار دارد برمیگرداند. توجه: روشهای قدیمی «مکان فعلی» در «کیت توسعه نرمافزار مکانها» برای Android نسخه ۶.۰ و بالاتر و «کیت توسعه نرمافزار مکانها» برای iOS نسخه ۱۱.۰ و بالاتر برداشته شدهاند؛ مختصات دستگاه را از خدمات مکان پلاتفرم بازیابی کنید و «جستجوی اطراف» را فراخوانی کنید.
- خلاصه نمای کلی با پشتیبانی هوش مصنوعی را برای مکان خاصی برمیگرداند.
- خلاصه منطقه با پشتیبانی هوش مصنوعی را که مکانهای اطراف مکان خاصی را توصیف میکند برمیگرداند.
- اطلاعات مربوط به مکانها را براساس رشته پُرسمانی که درطول مسیر ازپیش تعریفشده قرار دارد برمیگرداند.
- فاصله، زمان سفر، و شناسه منبع یکسان مسیرها را برای جستجوی نوشتاری مکانها از مجموعهای از مختصات عرض جغرافیایی/ طول جغرافیایی برگردانید.
- برگرداندن فاصله، مدت سفر، و شناسه منبع یکسان مسیرها به مکانهای اطراف از مجموعهای از مختصات عرض جغرافیایی/طول جغرافیایی.
- فاصله، مدت سفر، و URI مسیرهای بین مبدأ برای مسیر ازپیش تعریفشده و هریک از مکانهای برگرداندهشده براساس رشته پُرسمان را که درطول مسیر نیز قرار دارند برمیگرداند.
- فاصله، مدت سفر، و شناسه منبع یکسان مسیرهای بین هریک از مکانهای برگرداندهشده براساس رشته پُرسمان را که درطول مسیر ازپیش تعریفشده و مقصد مسیر قرار دارند برگردانید.
کیت توسعه نرمافزار مکانها، ویژه Android: کیت میانای کاربر «جاها»
- سبک CSS را بر عنصر میانای کاربر دادههای مکان اعمال کنید. توجه: ویژگیهای سفارشی CSS برای عناصر «کیت میانای کاربر جاها» در Maps JavaScript API اعمال میشود؛ «کیت توسعه نرمافزار جاها» برای Android و «کیت توسعه نرمافزار جاها» برای iOS نماهای «کیت میانای کاربر جاها» را بهصورت برنامهنویسیشده بااستفاده از مشخصههای طرحواره و سبک، سبکبندی میکنند. الزامات رعایت مقررات منطقه اقتصادی اروپا: برای نمایش دادههای مکان روی نقشه در منطقه اقتصادی اروپا (EEA)، سرویسهای وب Places API را از سرور زیرینه فراخوانی نکنید. از مؤلفههای «کیت میانای کاربر جاها» سمت کارخواه در پلاتفرم هدف (Maps JavaScript API در وب، Places SDK for Android در Android، یا Places SDK for iOS در iOS) استفاده کنید. پرسشگان و شرایط کامل: https://developers.google.com/maps/comms/eea/faq
- با ابزار سفارشیسازی عنصر میانای کاربر، پیکربندیها و سبک عنصر میانای کاربر دادههای مکان را سفارشیسازی کنید. توجه: الزامات رعایت مقررات منطقه اقتصادی اروپا: برای نمایش دادههای مکان روی نقشه در منطقه اقتصادی اروپا (EEA)، وبسرویسهای Places API را از سرور زیرینه فراخوانی نکنید. از مؤلفههای «کیت میانای کاربر جاها» سمت کارخواه در پلاتفرم هدف (Maps JavaScript API در وب، Places SDK for Android در Android، یا Places SDK for iOS در iOS) استفاده کنید. پرسشگان و شرایط کامل: https://developers.google.com/maps/comms/eea/faq
- عنصر میانای کاربری را که اطلاعات مربوط به مکان خاصی را نمایش میدهد به صفحه وب یا برنامه تلفن همراه اضافه کنید. توجه: الزامات رعایت مقررات منطقه اقتصادی اروپا: برای نشان دادن دادههای مکان روی نقشه در منطقه اقتصادی اروپا (EEA)، وبسرویسهای Places API را از سرور زیرینه فراخوانی نکنید. از مؤلفههای «کیت میانای کاربر جاها» سمت کارخواه در پلاتفرم هدف (Maps JavaScript API در وب، Places SDK for Android در Android، یا Places SDK for iOS در iOS) استفاده کنید. پرسشگان و شرایط کامل: https://developers.google.com/maps/comms/eea/faq
- عنصر میانای کاربری را که فهرستی از مکانها را براساس رشته پُرسمان نمایش میدهد به صفحه وب اضافه کنید. توجه: هم در صفحههای وب (میانای برنامهسازی کاربردی جاوا اسکریپت Maps) و هم در برنامههای تلفن همراه (کیت توسعه نرمافزار Places برای Android و کیت توسعه نرمافزار Places برای iOS) پشتیبانی میشود. الزامات رعایت مقررات منطقه اقتصادی اروپا: برای نمایش دادههای مکان روی نقشه در منطقه اقتصادی اروپا (EEA)، سرویسهای وب Places API را از سرور زیرینه فراخوانی نکنید. از مؤلفههای «کیت میانای کاربر جاها» سمت کارخواه در پلاتفرم هدف (Maps JavaScript API در وب، Places SDK for Android در Android، یا Places SDK for iOS در iOS) استفاده کنید. پرسشگان و شرایط کامل: https://developers.google.com/maps/comms/eea/faq
- عنصر میانای کاربری را که فهرستی از مکانهای نزدیک به یک مکان خاص را نمایش میدهد به صفحه وب اضافه کنید. توجه: هم در صفحههای وب (میانای برنامهسازی کاربردی جاوا اسکریپت Maps) و هم در برنامههای تلفن همراه (کیت توسعه نرمافزار Places برای Android و کیت توسعه نرمافزار Places برای iOS) پشتیبانی میشود. الزامات رعایت مقررات منطقه اقتصادی اروپا: برای نمایش دادههای مکان روی نقشه در منطقه اقتصادی اروپا (EEA)، سرویسهای وب Places API را از سرور زیرینه فراخوانی نکنید. از مؤلفههای «کیت میانای کاربر جاها» سمت کارخواه در پلاتفرم هدف (Maps JavaScript API در وب، Places SDK for Android در Android، یا Places SDK for iOS در iOS) استفاده کنید. پرسشگان و شرایط کامل: https://developers.google.com/maps/comms/eea/faq
- افزودن عنصر میانای کاربر تکمیل خودکار پایه به صفحه وب یا برنامهای که شناسههای «مکان Google» را براساس رشته پُرسمان برمیگرداند. توجه: الزامات رعایت مقررات منطقه اقتصادی اروپا: برای نمایش دادههای مکان روی نقشه در منطقه اقتصادی اروپا (EEA)، وبسرویسهای Places API را از سرور زیرینه فراخوانی نکنید. از مؤلفههای «کیت میانای کاربر جاها» سمت کارخواه در پلاتفرم هدف (Maps JavaScript API در وب، Places SDK for Android در Android، یا Places SDK for iOS در iOS) استفاده کنید. پرسشگان و شرایط کامل: https://developers.google.com/maps/comms/eea/faq