جاسازی یک نقشه

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

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

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

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

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

  • MAP_MODE با حالت نقشه شما.
  • YOUR_API_KEY با کلید API شما. برای اطلاعات بیشتر، به دریافت کلید API مراجعه کنید.
  • PARAMETERS با پارامترهای مورد نیاز و اختیاری برای حالت نقشه شما.

اضافه کردن URL به iframe

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

<iframe
  width="450"
  height="250"
  frameborder="0" style="border:0"
  referrerpolicy="no-referrer-when-downgrade"
  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="no-referrer-when-downgrade" به مرورگر اجازه می دهد تا URL کامل را به عنوان سرصفحه Referer همراه با درخواست ارسال کند تا محدودیت های کلید API به درستی کار کند.

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

محدودیت های کلید API

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

تبلیغات روی نقشه

Maps Embed API ممکن است شامل تبلیغات روی نقشه باشد. قالب تبلیغات و مجموعه تبلیغات نشان داده شده در هر نقشه ممکن است بدون اطلاع قبلی تغییر کند.

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

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

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

حالت place

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

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

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

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

حالت directions

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

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

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

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

حالت streetview

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

هر پانورامای نمای خیابان یک نمای کامل 360 درجه را از یک مکان ارائه می دهد. تصاویر شامل 360 درجه نمای افقی (یک دور کامل) و 180 درجه نمای عمودی (از مستقیم به بالا تا مستقیم به پایین) هستند. حالت 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

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

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

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

پارامترهای URL زیر اختیاری هستند:

پارامتر تایپ کنید توضیحات ارزش های پذیرفته شده
heading اختیاری سمت قطب نما دوربین را بر حسب درجه در جهت عقربه های ساعت از شمال نشان می دهد. مقدار در درجه از -180 درجه تا 360 درجه
pitch اختیاری زاویه بالا یا پایین دوربین را مشخص می کند. مقادیر مثبت دوربین را به سمت بالا زاویه می دهند، در حالی که مقادیر منفی دوربین را به سمت پایین زاویه می دهند. گام پیش فرض 0 درجه بر اساس موقعیت دوربین در هنگام ثبت تصویر تنظیم می شود. به همین دلیل، گام صفر درجه اغلب، اما نه همیشه، افقی است. به عنوان مثال، تصویری که روی یک تپه گرفته شده است، احتمالاً یک زمین پیش فرض را نشان می دهد که افقی نیست. مقدار در درجه از -90 درجه تا 90 درجه
fov اختیاری میدان دید افقی تصویر را تعیین می کند. به طور پیش فرض روی 90 درجه تنظیم می شود. هنگامی که با یک درگاه دید با اندازه ثابت سروکار دارید، میدان دید را می توان سطح بزرگنمایی در نظر گرفت، با اعداد کوچکتر نشان دهنده سطح بالاتری از زوم است. مقدار بر حسب درجه، با دامنه 10 تا 100 درجه
center اختیاری مرکز نمای نقشه را مشخص می کند. مقدار طول و عرض جغرافیایی جدا شده با کاما را می پذیرد. به عنوان مثال: 37.4218,-122.0840 .
zoom اختیاری سطح بزرگنمایی اولیه نقشه را تنظیم می کند. مقادیر متغیر از 0 (کل جهان) تا 21 (ساختمان های فردی). حد بالایی بسته به داده های نقشه موجود در مکان انتخاب شده می تواند متفاوت باشد.
maptype اختیاری نوع کاشی های نقشه را برای بارگذاری تعریف می کند. roadmap (پیش فرض) یا satellite
language اختیاری زبان مورد استفاده برای عناصر UI و برای نمایش برچسب ها بر روی کاشی های نقشه را تعریف می کند. به طور پیش فرض، بازدیدکنندگان نقشه ای را به زبان خود می بینند. این پارامتر فقط برای برخی از کاشی های کشور پشتیبانی می شود. اگر زبان خاص درخواست شده برای مجموعه کاشی پشتیبانی نمی شود، از زبان پیش فرض برای آن مجموعه کاشی استفاده می شود.
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 اختیاری زبان مورد استفاده برای عناصر UI و برای نمایش برچسب ها بر روی کاشی های نقشه را تعریف می کند. به طور پیش فرض، بازدیدکنندگان نقشه ای را به زبان خود می بینند. این پارامتر فقط برای برخی از کاشی های کشور پشتیبانی می شود. اگر زبان خاص درخواست شده برای مجموعه کاشی پشتیبانی نمی شود، از زبان پیش فرض برای آن مجموعه کاشی استفاده می شود.
region اختیاری بر اساس حساسیت های ژئوپلیتیکی، مرزها و برچسب های مناسب را برای نمایش تعریف می کند. کد منطقه ای را می پذیرد که به عنوان نگاشت زیربرچسب منطقه یونیکد دو کاراکتری (غیر عددی) به مقادیر دو نویسه ccTLD ("دامنه سطح بالا") آشنا است. جزئیات پوشش پلت فرم Google Maps را برای مناطق پشتیبانی شده ببینید.

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

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

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

  • q
  • origin
  • destination
  • waypoints

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

  • radius شعاع مشخص شده بر حسب متر را تعیین می کند که در آن می توان یک پانوراما را با محوریت طول و عرض جغرافیایی معین جستجو کرد. مقادیر معتبر اعداد صحیح غیر منفی هستند. مقدار پیش فرض 50 است.

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

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