مرجع سریع Maps Embed API

‫Maps Embed API نقشه تعاملی یا تمام‌نمای «نمای خیابان» را ازطریق درخواست HTTP که به‌عنوان نشانی وب iframe src تنظیم شده است، بدون نیاز به جاوااسکریپت، در صفحه وب قرار می‌دهد. این ویژگی از حالت‌های نقشه place،‏ view،‏ directions،‏ streetview، و search پشتیبانی می‌کند.

Maps Embed API: key facts

  • محصول: Maps Embed API
  • با این نام‌ها نیز شناخته می‌شود: Google Maps Embed API،‏ Maps Embed
  • دسته: Maps
  • پلاتفرم: جاوا اسکریپت (مرورگر)
  • اجرا در: کارخواه (کد برنامه یا مرورگر)
  • مرحله راه‌اندازی: GA
  • چرخه حیات: فعال
  • نمای کلی: نمای کلی Maps Embed API
  • دردسترس بودن منطقه‌ای: جهانی. حالت «نمای خیابان» به پوشش «نمای خیابان» بستگی دارد؛ پارامتر region مناطقی را که در صفحه جزئیات پوشش Maps Platform فهرست شده‌اند می‌پذیرد. (جزئیات پوشش)

Maps Embed API: when to use it

در موارد زیر از Maps Embed API استفاده کنید:

  • به نقشه تعاملی یا تمام‌نمای «نمای خیابان» در صفحه وب نیاز دارید که فقط از iframe HTML استفاده کند و جاوا اسکریپت نداشته باشد.
  • باید سنجاق مکان، نمای نقشه، مسیرهای بین نقاط، یا نتایج جستجوی منطقه‌ای را در نقشه جاسازی‌شده نشان دهید.
  • به نقشه جاسازی‌شده‌ای نیاز دارید که هزینه به‌ازای درخواست نداشته باشد و محدودیت‌های QPS یا درخواست روزانه نداشته باشد (کلید API همچنان لازم است).

در موارد زیر از Maps Embed API استفاده نکنید:

  • باید نقشه وب را با محتوا و تصاویر خودتان سفارشی‌سازی کنید. به‌جای آن از Maps JavaScript API استفاده کنید.
  • باید نقشه جاسازی‌شده را با ویژگی‌های برنامه‌ای فراتر از پارامترهای نشانی وب iframe گسترش دهید. به‌جای آن از Maps JavaScript API استفاده کنید.

Maps Embed API: setup

Maps Embed API: اشتباهات رایج

  • مشکل: اگر صفحه میزبان متا تگ referrer را روی no-referrer یا same-origin تنظیم کند، مرورگر سرصفحه Referer را ارسال نمی‌کند و کلید میانای برنامه‌سازی کاربردی محدودشده با ارجاع‌دهنده HTTP می‌تواند درخواست‌های جاسازی را رد کند. اصلاح: referrerpolicy="strict-origin-when-cross-origin" را به iframe اضافه کنید تا دامنه سایت به Google ارسال شود. /maps/documentation/embed/embedding-map را ببینید.
  • مشکل: نقشه‌های جاسازی‌شده با ابعاد کمتر از ۲۰۰ پیکسل پشتیبانی نمی‌شوند. اصلاح: width و height iframe را حداقل روی ۲۰۰ پیکسل تنظیم کنید. /maps/documentation/embed/embedding-map را ببینید.
  • مشکل: اگر صورت‌حساب فعال نباشد، روش صدور صورت‌حساب نامعتبر باشد، از حد روزانه خودتحمیلی فراتر رفته باشید، یا درخواست فاقد ارجاع‌دهنده HTTP باشد درحالی‌که از کلید محدودشده ارجاع‌دهنده استفاده می‌کنید، بااینکه استفاده رایگان است، نقشه تیره‌ای با ته‌نقش «فقط برای اهداف توسعه» ظاهر می‌شود. رفع مشکل: صورت‌حساب را با روش پرداخت معتبری در پروژه فعال کنید، هرگونه حد سهمیه روزانه خودتحمیلی را افزایش دهید یا بردارید، و مطمئن شوید که ارجاع‌دهنده برای کلیدهای محدودشده ارجاع‌دهنده ارسال شده است (برای مثال، با referrerpolicy="strict-origin-when-cross-origin" در iframe). /maps/documentation/embed/error-messages را ببینید.
  • مشکل: برای درخواست‌های نامعتبر (پارامترهای بد یا مفقود، و خطاهای کلید میانای برنامه‌سازی کاربردی و سهمیه مانند کلید مفقود یا نامعتبر، فعال نبودن Maps Embed API، یا نقض محدودیت کلید)، فقط رمز وضعیت HTTP 4xx در کنسول مرورگر گزارش می‌شود، نه پیام توصیفی؛ نوشتار خطا در iframe به‌جای نقشه ظاهر می‌شود. اصلاح: نوشتار خطا را در iframe و کد وضعیت کنسول (۴۰۰ برای خطاهای پارامتر، ۴۰۱ برای کلید مفقود، ۴۰۳ برای کلید نامعتبر) بخوانید، سپس تأیید کنید که پارامترها معتبر هستند، کلید معتبر است، Maps Embed API فعال است، و محدودیت‌های کلید اجازه درخواست را می‌دهند. /maps/documentation/embed/error-messages را ببینید.

کارهایی که می‌توانید با Maps Embed API انجام دهید

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

Maps Embed API: Directions and Routing

Maps Embed API: Maps

Maps Embed API: Places

Maps Embed API: Street View