Places API (New) یک سرویس وب است که دادههای مکان JSON را درباره مؤسسات، مکانهای جغرافیایی، و مکانهای جالب برمیگرداند. این کتابخانه از «جستجوی نوشتار» (جدید)، «جستجوی اطراف» (جدید)، «تکمیل خودکار» (جدید)، «جزئیات مکان» (جدید)، و «عکسهای مکان» (جدید) پشتیبانی میکند.
Places API (New): key facts
- محصول: Places API (New)
- با این نام هم شناخته میشود: Places API
- دسته: مکانها
- پلاتفرم: سرویس وب (REST)
- اجرا در: سرور (کد پسین)
- مرحله راهاندازی: GA
- چرخه حیات: فعال
- نمای کلی: نمای کلی Places API (جدید)
- دردسترس بودن منطقهای: جهانی. پروژههای دارای نشانی صورتحساب منطقه اقتصادی اروپا از «شرایط خدمات Google Maps Platform» در منطقه اقتصادی اروپا (از ۸ ژوئیه ۲۰۲۵) استفاده میکنند که در آن محتوای Places API بهجز عرض جغرافیایی، طول جغرافیایی، و شناسههای مکان نمیتواند با هیچ نقشهای استفاده شود، مگر ازطریق «کیت میانای کاربر جاها». خلاصههای مکان، مرور، و منطقه با بهرهگیری از هوش مصنوعی فقط در زبانها و مناطق پشتیبانیشده دردسترس است.
Places API (New): when to use it
در موارد زیر از Places API (جدید) استفاده کنید:
- باید مکانها را از سرور با پُرسمان نوشتاری (جستجوی نوشتار (جدید)) یا اطراف یک مکان (جستجوی اطراف (جدید)) جستجو کنید.
- به پیشبینیهای مکان یا پُرسمان پیشتایپ از زیرینه ازطریق «تکمیل خودکار» (جدید) نیاز دارید.
- شناسه مکان دارید و به جزئیاتی مثل نشانی، شماره تلفن، ردهبندی، مرورها، یا عکسها نیاز دارید.
- برای مکانی به خلاصههای تولیدشده با هوش مصنوعی از مکان، مرور، یا منطقه نیاز دارید.
در موارد زیر از Places API (جدید) استفاده نکنید:
- درحال ساختن برنامه Android بومی هستید. بهجای آن، از کیت توسعه نرمافزار مکانها، ویژه Android استفاده کنید.
- درحال ساختن برنامه iOS بومی هستید. بهجای آن از کیت توسعه نرمافزار مکانها، ویژه iOS استفاده کنید.
- درحال ساختن برنامه وب مرورگر هستید و میخواهید کتابخانه «جاها» در جاوا اسکریپت بار شود. بهجای آن از Maps JavaScript API استفاده کنید.
Places API (New): setup
- سرویس برای فعال کردن:
places.googleapis.com - اصالتسنجی: کلید میانای برنامهسازی کاربردی، OAuth 2.0
- شروع به کار: راهاندازی Places API (جدید)
- مرجع: مرجع Places API (جدید)
- قیمتگذاری: استفاده و صورتحساب Places API (جدید)
- خطمشیها: خطمشیهای Places API (جدید)
- یادداشتهای انتشار: یادداشتهای انتشار Places API (جدید)
بستههای رسمی Places API (جدید):
- npm:
@googlemaps/places - pypi:
google-maps-places - برو:
cloud.google.com/go/maps
Places API (New): related products
- جایگزین: Places API (Legacy)
- اغلب با این موارد استفاده میشود: Geocoding API، Routes API، Address Validation API
Places API (New): common mistakes
- مشکل: «جزئیات جا (جدید)»، «جستجوی اطراف (جدید)»، و «جستجوی نوشتار (جدید)» فهرست پیشفرضی برای فیلدهای برگرداندهشده ندارند؛ درخواستهای بدون ماسک فیلد خطا برمیگردانند. راهحل: ماسک فیلد پاسخ را با پارامتر
fieldsیا$fields، یا سرایندX-Goog-FieldMaskارسال کنید. /maps/documentation/places/web-service/choose-fields را ببینید. - مشکل: اگر کد جلسه «تکمیل خودکار (جدید)» پساز پایان جلسه حذف شود یا دوباره استفاده شود، هر درخواست بهطور جداگانه بهعنوان «واحد نگهداری موجودی: درخواستهای تکمیل خودکار» صورتحساب میشود. اصلاح: برای هر جلسه یک کد جلسه جدید (UUID v4 توصیه میشود) تولید کنید و آن را با درخواست «جزئیات جا (جدید)» یا «اعتبارسنجی نشانی» پایان دهید. /maps/documentation/places/web-service/place-session-tokens را ببینید.
- مشکل: کد موجود یا تولیدشده با هوش مصنوعی که Places API (قدیمی) یا Maps JavaScript API
PlacesServiceرا در پروژهای بدون فعال بودن API قدیمی فراخوانی میکند باLegacyApiNotActivatedMapErrorناموفق میشود. راهحل: فراخوانیها را به Places API (جدید) منتقل کنید و ماسک فیلد الزامی را اضافه کنید. /maps/legacy#LegacyApiNotActivatedMapError را ببینید. - مشکل: شناسههای مکان ذخیرهشده ممکن است منسوخ شوند؛ سپس «جزئیات مکان (جدید)»
NOT_FOUND(HTTP 404) را برمیگرداند و شناسههای ناقص یا بدشکل HTTP 400INVALID_ARGUMENTرا برمیگردانند. راهحل: شناسههای مکان ذخیرهشده قدیمیتر از ۱۲ ماه را با درخواست «جزئیات مکان (جدید)» که فقط فیلدidرا درخواست میکند (بدون هزینه) بازآوری کنید. /maps/documentation/places/web-service/place-id#refresh-id را ببینید.
کارهایی که میتوانید با Places API (جدید) انجام دهید
برای هر تکلیف، راهنماهای پیوندشده در زیر را ببینید یا محصولات را در کاوشگر قابلیتها با یکدیگر مقایسه کنید.
Places API (جدید): هوش مصنوعی زایا
- خلاصهای با پشتیبانی هوش مصنوعی از مرورهای کاربر برای شناسه مشخصشده «مکان Google» برگردانید.
- خلاصه مکان با بهرهگیری از هوش مصنوعی را برای منطقه و امکانات رفاهی اطراف شناسه مکان Google مشخصشده برای ایستگاه شارژ خودرو برقی برمیگرداند.
Places API (New): Places
- فهرستی از مکانها و جزئیات مکان را براساس رشته پُرسمان برمیگرداند.
- فهرستی از مکانها و جزئیات مکان نزدیک به یک مکان خاص را برمیگرداند.
- نتایج تکمیل خودکار درباره مکانها را براساس رشته پُرسمان برمیگرداند.
- اطلاعات دقیق درباره مکان خاصی را برمیگرداند.
- عکسهای مکان خاصی را برگردانید. توجه: ارجاع به نویسنده هر عکس (نام نویسنده، پیوندشده به شناسه منبع یکسان نمایه او) را همراه با عکس نمایش دهید. خطمشیهای «اماکن» برای هر پلاتفرم این را الزامی میکند، برای مثال /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 برای یک مکان برمیگرداند.
- شناسه منبع یکسان را برای باز کردن صفحه مسیرها در Google Maps برای یک مکان برگردانید.
- URI را برای باز کردن صفحه نوشتن مرور در Google Maps برای یک مکان برگردانید.
- URI را برای باز کردن صفحه خواندن مرورها در Google Maps برای یک مکان برگردانید.
- شناسه منبع یکسان را برای باز کردن صفحه عکسها در Google Maps برای یک مکان برگردانید.
- خلاصه نمای کلی با پشتیبانی هوش مصنوعی را برای مکان خاصی برمیگرداند.
- خلاصه منطقه با پشتیبانی هوش مصنوعی را که مکانهای اطراف مکان خاصی را توصیف میکند برمیگرداند.
- اطلاعات مربوط به مکانها را براساس رشته پُرسمانی که درطول مسیر ازپیش تعریفشده قرار دارد برمیگرداند.
- فاصله، زمان سفر، و شناسه منبع یکسان مسیرها را برای جستجوی نوشتاری مکانها از مجموعهای از مختصات عرض جغرافیایی/ طول جغرافیایی برگردانید.
- برگرداندن فاصله، مدت سفر، و شناسه منبع یکسان مسیرها به مکانهای اطراف از مجموعهای از مختصات عرض جغرافیایی/طول جغرافیایی.
- فاصله، مدت سفر، و URI مسیرهای بین مبدأ برای مسیر ازپیش تعریفشده و هریک از مکانهای برگرداندهشده براساس رشته پُرسمان را که درطول مسیر نیز قرار دارند برمیگرداند.
- فاصله، مدت سفر، و شناسه منبع یکسان مسیرهای بین هریک از مکانهای برگرداندهشده براساس رشته پُرسمان را که درطول مسیر ازپیش تعریفشده و مقصد مسیر قرار دارند برگردانید.