مرجع سریع Places API (جدید)

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 (جدید) استفاده نکنید:

Places API (New): setup

بسته‌های رسمی Places API (جدید):

  • npm: @googlemaps/places
  • pypi: google-maps-places
  • برو: cloud.google.com/go/maps

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 400 INVALID_ARGUMENT را برمی‌گردانند. راه‌حل: شناسه‌های مکان ذخیره‌شده قدیمی‌تر از ۱۲ ماه را با درخواست «جزئیات مکان (جدید)» که فقط فیلد id را درخواست می‌کند (بدون هزینه) بازآوری کنید. /maps/documentation/places/web-service/place-id#refresh-id را ببینید.

کارهایی که می‌توانید با Places API (جدید) انجام دهید

برای هر تکلیف، راهنماهای پیوندشده در زیر را ببینید یا محصولات را در کاوشگر قابلیت‌ها با یکدیگر مقایسه کنید.

Places API (جدید): هوش مصنوعی زایا

Places API (New): Places