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

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

ایجاد URL API جاسازی نقشه‌ها

در زیر یک نمونه URL که API مربوط به Maps Embed را بارگذاری می‌کند، مشاهده می‌کنید:

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

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

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

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

برای استفاده از 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 را متناسب با ساختار و طراحی وب‌سایت خود تغییر دهید، اما ما متوجه شده‌ایم که بازدیدکنندگان معمولاً با نقشه‌های بزرگتر راحت‌تر تعامل می‌کنند. توجه داشته باشید که نقشه‌های جاسازی شده در هر دو بعد، با اندازه کمتر از ۲۰۰ پیکسل پشتیبانی نمی‌شوند.

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

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

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

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

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

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

حالت directions

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

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

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

پارامتر نوع توضیحات مقادیر پذیرفته شده
origin مورد نیاز نقطه شروع نمایش مسیرها را تعریف می‌کند. نام مکان، آدرس، کد پلاس، مختصات طول/عرض جغرافیایی یا شناسه مکان که با URL اسکیپ شده‌اند. API نقشه‌های جاسازی‌شده از هر دو + و %20 هنگام اسکیپ کردن فاصله‌ها پشتیبانی می‌کند. برای مثال، "City Hall, New York, NY" را به City+Hall,New+York,NY یا کدهای پلاس "849VCWC8+R9" را به 849VCWC8%2BR9 تبدیل کنید.
destination مورد نیاز نقطه پایانی مسیرها را تعریف می‌کند. نام مکان، آدرس، کد پلاس، مختصات طول/عرض جغرافیایی یا شناسه مکان که با URL اسکیپ شده‌اند. API نقشه‌های جاسازی‌شده از هر دو + و %20 هنگام اسکیپ کردن فاصله‌ها پشتیبانی می‌کند. برای مثال، "City Hall, New York, NY" را به City+Hall,New+York,NY یا کدهای پلاس "849VCWC8+R9" را به 849VCWC8%2BR9 تبدیل کنید.
waypoints اختیاری یک یا چند مکان واسطه را برای مسیریابی بین مبدا و مقصد مشخص می‌کند. نام مکان، آدرس یا شناسه مکان . با استفاده از کاراکتر پایپ (|) برای جدا کردن مکان‌ها، می‌توان چندین نقطه مسیر مشخص کرد (مثلاً Berlin,Germany|Paris,France ). می‌توانید تا 20 نقطه مسیر مشخص کنید.
mode اختیاری روش سفر را تعریف می‌کند. اگر هیچ حالتی مشخص نشده باشد، 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 ("دامنه سطح بالا") معروف نگاشت می‌شود. برای مناطق پشتیبانی شده به جزئیات پوشش پلتفرم نقشه‌های گوگل مراجعه کنید.

حالت streetview

API نقشه‌های جاسازی‌شده به شما امکان می‌دهد تصاویر نمای خیابان را به صورت پانوراماهای تعاملی از مکان‌های تعیین‌شده در سراسر منطقه تحت پوشش آن نمایش دهید. تصاویر کروی (Photosphere) که توسط کاربران ارائه می‌شوند و مجموعه‌های ویژه نمای خیابان نیز در دسترس هستند.

هر پانورامای نمای خیابان، یک نمای کامل ۳۶۰ درجه از یک مکان واحد ارائه می‌دهد. تصاویر شامل ۳۶۰ درجه نمای افقی (یک پوشش کامل) و ۱۸۰ درجه نمای عمودی (از مستقیم به بالا تا مستقیم به پایین) هستند. حالت 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، پانورامای عکاسی شده در نزدیکترین فاصله به این مکان را نمایش می‌دهد. از آنجا که تصاویر Street View به صورت دوره‌ای به‌روزرسانی می‌شوند و عکس‌ها ممکن است هر بار از موقعیت‌های کمی متفاوت گرفته شوند، این امکان وجود دارد که مکان شما هنگام به‌روزرسانی تصاویر، پانورامای متفاوتی را نمایش دهد.

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

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

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

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

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

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

API نقشه‌های جاسازی‌شده، شناسه‌های مکان را برای پارامترهای URL زیر می‌پذیرد:

  • q
  • origin
  • destination
  • waypoints

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

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

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

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