جاسازی نقشه

این راهنما نشان می‌دهد که چگونه یک نقشه تعاملی را در صفحه وب خود جاسازی کنید.

ایجاد نشانی وب Maps Embed API

در زیر نمونه‌ای از نشانی وب که Maps Embed API را بار می‌کند آورده شده است:

https://www.google.com/maps/embed/v1/MAP_MODE?key=YOUR_API_KEY&PARAMETERS

جایگزین کردن:

افزودن نشانی وب به iframe

برای استفاده از Maps Embed API در صفحه وب خود، نشانی وبی را که ساخته‌اید به‌عنوان مقدار مشخصه src iframe تنظیم کنید. اندازه نقشه را با مشخصه‌های height و width iframe کنترل کنید، برای مثال:

<iframe
  width="450"
  height="250"
  frameborder="0" style="border:0"
  referrerpolicy="strict-origin-when-cross-origin"
  src="https://www.google.com/maps/embed/v1/MAP_MODE?key=YOUR_API_KEY&PARAMETERS"
  allowfullscreen>
</iframe>

نمونه iframe بالا از ویژگی‌های اضافی زیر استفاده می‌کند:

  • ویژگی allowfullscreen برای اینکه به بخش‌های خاصی از نقشه اجازه داده شود تمام‌صفحه شوند.
  • ویژگی‌های frameborder="0" و style="border:0" برای برداشتن حاشیه iframe استاندارد از اطراف نقشه.
  • ویژگی referrerpolicy="strict-origin-when-cross-origin" تضمین می‌کند که مرورگر دامنه وب‌سایتتان را به‌عنوان سرصفحه Referer به Google ارسال کند. این کار به محدودیت‌های کلید میانای برنامه‌سازی کاربردی اجازه می‌دهد درخواست را اعتبارسنجی کند و درعین‌حال مسیرهای صفحه خاص شما را خصوصی نگه دارد.

می‌توانید اندازه iframe را متناسب با ساختار و طراحی وب‌سایت خود تغییر دهید، اما متوجه شده‌ایم که بازدیدکنندگان معمولاً تعامل با نقشه‌های بزرگ‌تر را آسان‌تر می‌دانند. توجه داشته باشید که نقشه‌های جاسازی‌شده با اندازه کمتر از ۲۰۰ پیکسل در هریک از ابعاد پشتیبانی نمی‌شوند.

اطلاعات ارجاع‌دهنده و محدودیت‌های کلید میانای برنامه‌سازی کاربردی

اگر وب‌سایت میزبان دارای متا تگ referrer باشد که روی no-referrer یا same-origin تنظیم شده است، مرورگر سرصفحه Referer را به Google ارسال نخواهد کرد. این امر ممکن است باعث شود محدودیت کلید میانای API درخواست‌ها را رد کند. برای اینکه محدودیت به‌درستی کار کند، ویژگی referrerpolicy را به iframe اضافه کنید، همان‌طور که در مثال بالا نشان داده شده است، تا صریحاً اجازه دهید سرصفحه‌های Referer به Google ارسال شود.

  • strict-origin-when-cross-origin (توصیه‌شده): فقط دامنه پایه شما را (مثلاً https://example.com/) به Google ارسال می‌کند. این کار باعث می‌شود مسیرهای صفحه خاص شما خصوصی بماند و درعین‌حال محدودیت‌های کلید میانای برنامه‌سازی کاربردی همچنان کار کند.
  • no-referrer-when-downgrade (قدیمی): کل نشانی وب را ارسال می‌کند، ازجمله مسیرهای صفحه خاص و پارامترهای پُرسمان (برای مثال، https://example.com/contact?user=123).

درباره سرصفحه Referrer-Policy بیشتر بدانید.

انتخاب حالت‌های نقشه

می‌توانید یکی از حالت‌های نقشه زیر را برای استفاده در نشانی وب درخواستتان مشخص کنید:

  • place: سنجاق نقشه را در مکان یا نشانی خاصی نمایش می‌دهد، مثلاً در نشانگر مکانی، کسب‌وکار، عنصر جغرافیایی، یا شهر.
  • view: نقشه‌ای بدون نشانگر یا مسیر برمی‌گرداند.
  • directions: مسیر بین دو یا چند نقطه مشخص‌شده روی نقشه، و همچنین فاصله و مدت سفر را نمایش می‌دهد.
  • streetview: نماهای تمام‌نمای تعاملی را از مکان‌های تعیین‌شده نشان می‌دهد.
  • search: نتایج جستجو را در سراسر منطقه نقشه نمایان نشان می‌دهد.

حالت place

نشانی وب زیر از حالت نقشه place برای نمایش نشانگر نقشه در برج ایفل استفاده می‌کند:

https://www.google.com/maps/embed/v1/place
  ?key=YOUR_API_KEY
  &q=Eiffel+Tower,Paris+France

می‌توانید از پارامترهای زیر استفاده کنید:

پارامتر نوع شرح مقادیر قابل قبول
q الزامی مکان نشانگر نقشه را تعریف می‌کند. نام مکان، نشانی، plus code، یا شناسه مکان با نویسه گریز URL. Maps Embed API از هر دو + و %20 هنگام گریز از فاصله‌ها پشتیبانی می‌کند. برای مثال، «City Hall, New York, NY» را به City+Hall,New+York,NY، یا Plus Code «849VCWC8+R9» را به 849VCWC8%2BR9 تبدیل کنید.
center اختیاری مرکز نمای نقشه را تعریف می‌کند. مقدار طول و عرض جغرافیایی جداشده با کاما را می‌پذیرد؛ برای مثال: 37.4218,-122.0840.
zoom اختیاری سطح بزرگ‌نمایی اولیه نقشه را تنظیم می‌کند. مقادیر از 0 (کل جهان) تا 21 (ساختمان‌های تکی) متغیر است. حد بالا ممکن است بسته به داده‌های نقشه دردسترس در مکان انتخاب‌شده متفاوت باشد.
maptype اختیاری نوع کاشی‌های نقشه را برای بار کردن تعریف می‌کند. roadmap (پیش‌فرض) یا satellite
language اختیاری زبان مورد استفاده برای عناصر میانای کاربر و نمایش برچسب‌ها روی کاشی‌های نقشه را تعریف می‌کند. به‌طور پیش‌فرض، بازدیدکنندگان نقشه را به زبان خودشان خواهند دید. این پارامتر فقط برای برخی‌از کاشی‌های کشور پشتیبانی می‌شود؛ اگر زبان خاص درخواست‌شده برای مجموعه کاشی پشتیبانی نشود، از زبان پیش‌فرض برای آن مجموعه کاشی استفاده خواهد شد.
region اختیاری مرزها و برچسب‌های مناسب را برای نمایش براساس حساسیت‌های جغرافیایی-سیاسی تعریف می‌کند. کد منطقه‌ای را که به‌عنوان زیربرچسب منطقه یونی‌کد دو نویسه‌ای (غیرعددی) مشخص شده است می‌پذیرد و آن را به مقادیر دو نویسه‌ای ccTLD («دامنه سطح بالا») آشنا نگاشت می‌کند. برای مناطق پشتیبانی‌شده، جزئیات پوشش پلاتفرم Google Maps را ببینید.

حالت view

مثال زیر از حالت view و پارامتر اختیاری maptype برای نمایش نمای ماهواره‌ای نقشه استفاده می‌کند:

https://www.google.com/maps/embed/v1/view
  ?key=YOUR_API_KEY
  &center=-33.8569,151.2152
  &zoom=18
  &maptype=satellite

می‌توانید از پارامترهای زیر استفاده کنید:

پارامتر نوع شرح مقادیر قابل قبول
center الزامی مرکز نمای نقشه را تعریف می‌کند. مقدار طول و عرض جغرافیایی جداشده با کاما را می‌پذیرد؛ برای مثال: 37.4218,-122.0840.
zoom اختیاری سطح بزرگ‌نمایی اولیه نقشه را تنظیم می‌کند. مقادیر از 0 (کل جهان) تا 21 (ساختمان‌های تکی) متغیر است. حد بالا ممکن است بسته به داده‌های نقشه دردسترس در مکان انتخاب‌شده متفاوت باشد.
maptype اختیاری نوع کاشی‌های نقشه را برای بار کردن تعریف می‌کند. roadmap (پیش‌فرض) یا satellite
language اختیاری زبان مورد استفاده برای عناصر میانای کاربر و نمایش برچسب‌ها روی کاشی‌های نقشه را تعریف می‌کند. به‌طور پیش‌فرض، بازدیدکنندگان نقشه را به زبان خودشان خواهند دید. این پارامتر فقط برای برخی‌از کاشی‌های کشور پشتیبانی می‌شود؛ اگر زبان خاص درخواست‌شده برای مجموعه کاشی پشتیبانی نشود، از زبان پیش‌فرض برای آن مجموعه کاشی استفاده خواهد شد.
region اختیاری مرزها و برچسب‌های مناسب را برای نمایش براساس حساسیت‌های جغرافیایی-سیاسی تعریف می‌کند. کد منطقه‌ای را که به‌عنوان برچسب فرعی منطقه یونی‌کد دو نویسه‌ای (غیرعددی) مشخص شده است می‌پذیرد و آن را به مقادیر دو نویسه‌ای ccTLD («دامنه سطح بالا») آشنا نگاشت می‌کند. برای مناطق پشتیبانی‌شده، جزئیات پوشش پلاتفرم Google Maps را ببینید.

حالت directions

مثال زیر از حالت directions برای نمایش مسیر بین اسلو و تلمارک در نروژ، مسافت، و مدت سفر بدون عوارض و بزرگراه استفاده می‌کند.

https://www.google.com/maps/embed/v1/directions
  ?key=YOUR_API_KEY
  &origin=Oslo+Norway
  &destination=Telemark+Norway
  &avoid=tolls|highways

می‌توانید از پارامترهای زیر استفاده کنید:

پارامتر نوع شرح مقادیر قابل قبول
origin الزامی نقطه شروعی را که مسیرها از آن نمایش داده می‌شود تعریف می‌کند. نام مکان، نشانی، Plus Code، مختصات طول/عرض جغرافیایی، یا شناسه مکان با نویسه گریز URL. Maps Embed API از هر دو + و %20 هنگام گریز از فاصله‌ها پشتیبانی می‌کند. برای مثال، «City Hall, New York, NY» را به City+Hall,New+York,NY، یا Plus Code «849VCWC8+R9» را به 849VCWC8%2BR9 تبدیل کنید.
destination الزامی نقطه پایان مسیر را تعریف می‌کند. نام مکان، نشانی، Plus Code، مختصات طول/عرض جغرافیایی، یا شناسه مکان با نویسه گریز URL. Maps Embed API از هر دو + و %20 هنگام گریز از فاصله‌ها پشتیبانی می‌کند. برای مثال، «City Hall, New York, NY» را به City+Hall,New+York,NY، یا Plus Code «849VCWC8+R9» را به 849VCWC8%2BR9 تبدیل کنید.
waypoints اختیاری یک یا چند مکان واسطه را برای مسیریابی بین مبدأ و مقصد مشخص می‌کند. نام، نشانی، یا شناسه مکان. بااستفاده از نویسه خط عمودی (|) برای جدا کردن مکان‌ها (مثلاً Berlin,Germany|Paris,France) می‌توانید چند نقطه‌مسیر مشخص کنید. می‌توانید حداکثر ۲۰ نقطه‌مسیر مشخص کنید.
mode اختیاری روش سفر را تعریف می‌کند. اگر هیچ حالتی مشخص نشده باشد، Maps Embed API یک یا چند مورد از مرتبط‌ترین حالت‌ها را برای مسیر مشخص‌شده نشان می‌دهد. driving، walking (که مسیرهای پیاده‌رو و پیاده‌روها را درصورت وجود ترجیح می‌دهد)، bicycling (که مسیرهای دارای مسیر دوچرخه و خیابان‌های ترجیحی را درصورت وجود ترجیح می‌دهد)، transit، یا flying.
avoid اختیاری ویژگی‌هایی را که باید در مسیرها اجتناب شود مشخص می‌کند. توجه داشته باشید که این کار مانع از نمایش مسیرهایی که شامل ویژگی(های) محدودشده هستند نمی‌شود؛ بلکه نتایج را به‌سمت مسیرهای مطلوب‌تر سوق می‌دهد. tolls، ferries و/یا highways. مقادیر متعدد را با نویسه خط عمودی از هم جدا کنید (مثلاً avoid=tolls|highways).
units اختیاری روش اندازه‌گیری، متریک یا امپریال، را هنگام نمایش فاصله‌ها در نتایج مشخص می‌کند. اگر units مشخص نشده باشد، origin کشور پُرسمان واحدهای مورداستفاده را تعیین می‌کند. ‫metric یا imperial
center اختیاری مرکز نمای نقشه را تعریف می‌کند. مقدار طول و عرض جغرافیایی جداشده با کاما را می‌پذیرد؛ برای مثال: 37.4218,-122.0840.
zoom اختیاری سطح بزرگ‌نمایی اولیه نقشه را تنظیم می‌کند. مقادیر از 0 (کل جهان) تا 21 (ساختمان‌های تکی) متغیر است. حد بالا ممکن است بسته به داده‌های نقشه دردسترس در مکان انتخاب‌شده متفاوت باشد.
maptype اختیاری نوع کاشی‌های نقشه را برای بار کردن تعریف می‌کند. roadmap (پیش‌فرض) یا satellite
language اختیاری زبان مورد استفاده برای عناصر میانای کاربر و نمایش برچسب‌ها روی کاشی‌های نقشه را تعریف می‌کند. به‌طور پیش‌فرض، بازدیدکنندگان نقشه را به زبان خودشان خواهند دید. این پارامتر فقط برای برخی‌از کاشی‌های کشور پشتیبانی می‌شود؛ اگر زبان خاص درخواست‌شده برای مجموعه کاشی پشتیبانی نشود، از زبان پیش‌فرض برای آن مجموعه کاشی استفاده خواهد شد.
region اختیاری مرزها و برچسب‌های مناسب را برای نمایش براساس حساسیت‌های جغرافیایی-سیاسی تعریف می‌کند. کد منطقه‌ای را که به‌عنوان برچسب فرعی منطقه یونی‌کد دو نویسه‌ای (غیرعددی) مشخص شده است می‌پذیرد و آن را به مقادیر دو نویسه‌ای ccTLD («دامنه سطح بالا») آشنا نگاشت می‌کند. برای مناطق پشتیبانی‌شده، جزئیات پوشش پلاتفرم Google Maps را ببینید.

حالت streetview

Maps Embed API به شما امکان می‌دهد تصاویر «نمای خیابان» را به‌صورت تمام‌نماهای تعاملی از مکان‌های تعیین‌شده در سراسر منطقه تحت پوشش آن نمایش دهید. «سپهر عکس‌های» همیاری‌شده کاربران و مجموعه‌های ویژه «نمای خیابان» نیز دردسترس است.

هر تمام‌نمای «نمای خیابان» نمای کامل ۳۶۰ درجه‌ای از یک مکان ارائه می‌دهد. تصاویر حاوی نمای افقی ۳۶۰ درجه (یک چرخش کامل) و نمای عمودی ۱۸۰ درجه (از مستقیم بالا تا مستقیم پایین) هستند. حالت streetview نمایشی ارائه می‌دهد که تمام‌نمای حاصل را به‌صورت کره‌ای با دوربینی در مرکز آن ارائه می‌کند. می‌توانید دوربین را دستکاری کنید تا بزرگ‌نمایی و جهت دوربین را کنترل کنید.

تمام‌نمای حالت streetview زیر را ببینید:

https://www.google.com/maps/embed/v1/streetview
  ?key=YOUR_API_KEY
  &location=46.414382,10.013988
  &heading=210
  &pitch=10
  &fov=35

یکی از پارامترهای نشانی وب زیر الزامی است:

  • location عرض جغرافیایی و طول جغرافیایی را به‌عنوان مقادیر جداشده با کاما (46.414382,10.013988) می‌پذیرد. میانای برنامه‌سازی کاربردی تمام‌نمای عکاسی‌شده در نزدیک‌ترین فاصله به این مکان را نمایش می‌دهد. چون تصاویر «نمای خیابان» به‌طور دوره‌ای بازآوری می‌شود و ممکن است عکس‌ها هربار از موقعیت‌های کمی متفاوت گرفته شود، ممکن است وقتی تصاویر به‌روز می‌شود، مکان شما به تمام‌نمای دیگری منتقل شود.

  • pano شناسه تمام‌نمای خاصی است. اگر pano را مشخص کنید، می‌توانید location را نیز مشخص کنید. ‫location فقط زمانی استفاده می‌شود که API نتواند شناسه تمام‌نما را پیدا کند.

پارامترهای نشانی وب زیر اختیاری هستند:

پارامتر نوع شرح مقادیر قابل قبول
heading اختیاری جهت قطب‌نمای دوربین را به‌صورت درجه ساعت‌گرد از شمال نشان می‌دهد. مقدار برحسب درجه از ۱۸۰- تا ۳۶۰ درجه
pitch اختیاری زاویه دوربین را به‌سمت بالا یا پایین مشخص می‌کند. مقادیر مثبت زاویه دوربین را به‌سمت بالا می‌برند، درحالی‌که مقادیر منفی زاویه دوربین را به‌سمت پایین می‌برند. زاویه پیش‌فرض ۰ درجه براساس موقعیت دوربین در زمان ثبت تصویر تنظیم شده است. به‌همین دلیل، زاویه گام صفر درجه اغلب، اما نه همیشه، افقی است. برای مثال، تصویری که روی تپه گرفته شده است احتمالاً گام پیش‌فرضی را نشان می‌دهد که افقی نیست. مقدار به درجه از ۹۰- تا ۹۰ درجه
fov اختیاری میدان دید افقی تصویر را مشخص می‌کند. مقدار پیش‌فرض آن ۹۰ درجه است. هنگام کار با نمای دید با اندازه ثابت، میدان دید را می‌توان به‌عنوان سطح بزرگ‌نمایی درنظر گرفت، که اعداد کوچک‌تر نشان‌دهنده سطح بزرگ‌نمایی بالاتر هستند. مقدار برحسب درجه، با محدوده ۱۰ تا ۱۰۰ درجه
center اختیاری مرکز نمای نقشه را تعریف می‌کند. مقدار طول و عرض جغرافیایی جداشده با کاما را می‌پذیرد؛ برای مثال: 37.4218,-122.0840.
zoom اختیاری سطح بزرگ‌نمایی اولیه نقشه را تنظیم می‌کند. مقادیر از 0 (کل جهان) تا 21 (ساختمان‌های تکی) متغیر است. حد بالا ممکن است بسته به داده‌های نقشه دردسترس در مکان انتخاب‌شده متفاوت باشد.
maptype اختیاری نوع کاشی‌های نقشه را برای بار کردن تعریف می‌کند. roadmap (پیش‌فرض) یا satellite
language اختیاری زبان مورد استفاده برای عناصر میانای کاربر و نمایش برچسب‌ها روی کاشی‌های نقشه را تعریف می‌کند. به‌طور پیش‌فرض، بازدیدکنندگان نقشه را به زبان خودشان خواهند دید. این پارامتر فقط برای برخی‌از کاشی‌های کشور پشتیبانی می‌شود؛ اگر زبان خاص درخواست‌شده برای مجموعه کاشی پشتیبانی نشود، از زبان پیش‌فرض برای آن مجموعه کاشی استفاده خواهد شد.
region اختیاری مرزها و برچسب‌های مناسب را برای نمایش براساس حساسیت‌های جغرافیایی-سیاسی تعریف می‌کند. کد منطقه‌ای را که به‌عنوان برچسب فرعی منطقه یونی‌کد دو نویسه‌ای (غیرعددی) مشخص شده است می‌پذیرد و آن را به مقادیر دو نویسه‌ای ccTLD («دامنه سطح بالا») آشنا نگاشت می‌کند. برای مناطق پشتیبانی‌شده، جزئیات پوشش پلاتفرم Google Maps را ببینید.

حالت search

حالت Search نتایج جستجو را در سراسر منطقه قابل‌مشاهده نقشه نمایش می‌دهد. توصیه می‌شود مکانی برای جستجو تعریف شود، یا با گنجاندن مکان در عبارت جستجو (record+stores+in+Seattle) یا با گنجاندن پارامتر center و zoom برای محدود کردن جستجو.

https://www.google.com/maps/embed/v1/search
  ?key=YOUR_API_KEY
  &q=record+stores+in+Seattle

می‌توانید از پارامترهای زیر استفاده کنید:

پارامتر نوع شرح مقادیر قابل قبول
q الزامی عبارت جستجو را تعریف می‌کند. این محدودیت می‌تواند شامل محدودیت جغرافیایی باشد، مانند in+Seattle یا near+98033.
center اختیاری مرکز نمای نقشه را تعریف می‌کند. مقدار طول و عرض جغرافیایی جداشده با کاما را می‌پذیرد؛ برای مثال: 37.4218,-122.0840.
zoom اختیاری سطح بزرگ‌نمایی اولیه نقشه را تنظیم می‌کند. مقادیر از 0 (کل جهان) تا 21 (ساختمان‌های تکی) متغیر است. حد بالا ممکن است بسته به داده‌های نقشه دردسترس در مکان انتخاب‌شده متفاوت باشد.
maptype اختیاری نوع کاشی‌های نقشه را برای بار کردن تعریف می‌کند. roadmap (پیش‌فرض) یا satellite
language اختیاری زبان مورد استفاده برای عناصر میانای کاربر و نمایش برچسب‌ها روی کاشی‌های نقشه را تعریف می‌کند. به‌طور پیش‌فرض، بازدیدکنندگان نقشه را به زبان خودشان خواهند دید. این پارامتر فقط برای برخی‌از کاشی‌های کشور پشتیبانی می‌شود؛ اگر زبان خاص درخواست‌شده برای مجموعه کاشی پشتیبانی نشود، از زبان پیش‌فرض برای آن مجموعه کاشی استفاده خواهد شد.
region اختیاری مرزها و برچسب‌های مناسب را برای نمایش براساس حساسیت‌های جغرافیایی-سیاسی تعریف می‌کند. کد منطقه‌ای را که به‌عنوان برچسب فرعی منطقه یونی‌کد دو نویسه‌ای (غیرعددی) مشخص شده است می‌پذیرد و آن را به مقادیر دو نویسه‌ای ccTLD («دامنه سطح بالا») آشنا نگاشت می‌کند. برای مناطق پشتیبانی‌شده، جزئیات پوشش پلاتفرم Google Maps را ببینید.

پارامترهای شناسه جا

‫Maps Embed API از شناسه مکان به‌جای نام یا نشانی مکان پشتیبانی می‌کند. شناسه‌های مکان روشی پایدار برای شناسایی منحصربه‌فرد مکان‌ها هستند. برای اطلاعات بیشتر، مستندات Places API (جدید) را ببینید.

‫Maps Embed API شناسه مکان را برای پارامترهای نشانی وب زیر می‌پذیرد:

  • q
  • origin
  • destination
  • waypoints

برای استفاده از شناسه مکان، ابتدا باید پیشوند place_id: را اضافه کنید. کد زیر تالار شهر نیویورک را به‌عنوان مبدأ درخواست مسیر مشخص می‌کند: origin=place_id:ChIJs--MqP1YwokRBwAhjXWIHn8.

  • radius شعاعی را برحسب متر تنظیم می‌کند که در آن برای تمام‌نما جستجو شود، و مرکز آن طول و عرض جغرافیایی داده‌شده است. مقادیر معتبر عدد صحیح غیرمنفی است. مقدار پیش‌فرض ۵۰ است.

  • source جستجوهای «نمای خیابان» را به منابع انتخاب‌شده محدود می‌کند. مقادیر معتبر عبارت‌اند از:

    • default از منابع پیش‌فرض برای «نمای خیابان» استفاده می‌کند؛ جستجوها به منابع خاصی محدود نمی‌شود.
    • outdoor جستجوها را به مجموعه‌های فضای باز محدود می‌کند. مجموعه‌های داخلی در نتایج جستجو گنجانده نمی‌شوند. توجه داشته باشید که ممکن است برای مکان مشخص‌شده تمام‌نمای فضای باز وجود نداشته باشد. همچنین توجه داشته باشید که جستجو فقط سراسرنماهایی را برمی‌گرداند که امکان تعیین اینکه در فضای بسته هستند یا فضای باز وجود داشته باشد. برای مثال، PhotoSpheres برگردانده نمی‌شود زیرا مشخص نیست که در فضای بسته است یا فضای باز.