شروع کنید

مقدمه

بااستفاده از نشانی‌های وب Maps، می‌توانید نشانی وب چندسکویی جهانی برای راه‌اندازی Google Maps و انجام جستجو، دریافت مسیر و پیمایش، و نمایش نماهای نقشه و تصاویر تمام‌نما بسازید. نحو نشانی وب صرف‌نظر از پلاتفرم مورداستفاده یکسان است.

برای استفاده از نشانی‌های وب Maps، به کلید Google API نیاز ندارید.

نحو چندسکویی جهانی

به‌عنوان توسعه‌دهنده برنامه Android، برنامه iOS، یا وب‌سایت، می‌توانید نشانی وب مشترکی بسازید، و این نشانی وب Google Maps را باز می‌کند و کنش درخواستی را انجام می‌دهد، صرف‌نظر از اینکه هنگام باز شدن نقشه از چه پلاتفرمی استفاده می‌شود.

• در دستگاه Android:
  • اگر برنامه Google Maps برای Android نصب و فعال باشد، نشانی وب Google Maps را در برنامه Maps راه‌اندازی می‌کند و کنش درخواستی را انجام می‌دهد.
  • اگر برنامه Google Maps نصب نشده باشد یا غیرفعال باشد، نشانی وب Google Maps را در مرورگر راه‌اندازی می‌کند و کنش درخواست‌شده را انجام می‌دهد.
• در دستگاه iOS:
  • اگر برنامه Google Maps برای iOS نصب شده باشد، نشانی وب Google Maps را در برنامه Maps راه‌اندازی می‌کند و کنش درخواست‌شده را انجام می‌دهد.
  • اگر برنامه Google Maps نصب نشده باشد، نشانی وب Google Maps را در مرورگر راه‌اندازی می‌کند و کنش درخواستی را انجام می‌دهد.
• در هر دستگاه دیگری، نشانی وب Google Maps را در مرورگر راه‌اندازی می‌کند و کنش درخواست‌شده را انجام می‌دهد.

توصیه می‌شود برای راه‌اندازی Google Maps از برنامه یا وب‌سایتتان از نشانی وب چندسکویی استفاده کنید، زیرا این نشانی‌های وب جهانی امکان مدیریت گسترده‌تر درخواست‌های نقشه را بدون توجه به پلاتفرم مورداستفاده فراهم می‌کنند. برای ویژگی‌هایی که ممکن است فقط در پلاتفرم تلفن همراه کار کنند (برای مثال، ناوبری گام‌به‌گام)، شاید ترجیح دهید از گزینه مختص پلاتفرم برای Android یا iOS استفاده کنید. به اسناد زیر مراجعه کنید:

• هدف‌های Google Maps برای Android — به‌طور خاص برای راه‌اندازی برنامه Google Maps برای Android
• طرح نشانی وب Google Maps برای iOS — به‌طور خاص برای راه‌اندازی برنامه Google Maps برای iOS

راه‌اندازی Google Maps و انجام کنشی خاص

برای راه‌اندازی Google Maps و به‌صورت اختیاری انجام یکی از عملکردهای پشتیبانی‌شده، بسته به کنش درخواستی، از طرح نشانی وب یکی از شکل‌های زیر استفاده کنید:

• جستجو — راه‌اندازی Google Map که سنجاقی را برای مکانی خاص نمایش می‌دهد، یا انجام جستجوی عمومی و راه‌اندازی نقشه‌ای برای نمایش نتایج:
  https://www.google.com/maps/search/?api=1&parameters
• مسیرها — درخواست مسیرها و راه‌اندازی Google Maps با نتایج:
  https://www.google.com/maps/dir/?api=1&parameters
• نمایش نقشه — راه‌اندازی Google Maps بدون نشانگر یا مسیر:
  https://www.google.com/maps/@?api=1&map_action=map&parameters
• ایجاد فهرست کوتاه — راه‌اندازی Google Maps با فهرستی از مکان‌های خاص:
  https://www.google.com/maps/@?api=1&map_action=shortlist&parameters
• نمایش تمام‌نمای «نمای خیابان» — راه‌اندازی تصویر تمام‌نمای تعاملی:
  https://www.google.com/maps/@?api=1&map_action=pano&parameters

مهم: پارامتر api=1 نسخه نشانی‌های وب Maps را که این نشانی وب برای آن درنظر گرفته شده است شناسایی می‌کند. این پارامتر در هر درخواستی الزامی است. تنها مقدار معتبر ۱ است. اگر api=1 در نشانی وب وجود نداشته باشد، همه پارامترها نادیده گرفته می‌شوند و برنامه پیش‌فرض Google Maps، بسته به پلاتفرم مورداستفاده، در مرورگر یا برنامه تلفن همراه Google Maps راه‌اندازی می‌شود (برای مثال، https://www.google.com/maps).

ساختن نشانی‌های وب معتبر

باید نشانی‌های وب را به‌درستی کدبندی کنید.

برای مثال، برخی پارامترها از نویسه خط عمودی (|) به‌عنوان جداکننده استفاده می‌کنند که باید آن را به‌صورت %7C در نشانی وب نهایی کدبندی کنید. پارامترهای دیگر از مقادیر جداشده با کاما استفاده می‌کنند، مثل مختصات عرض جغرافیایی/طول جغرافیایی یا شهر، ایالت. باید ویرگول را به‌صورت %2C کدبندی کنید. فاصله‌ها را با %20 کدگذاری کنید یا آن‌ها را با علامت جمع (+) جایگزین کنید.

علاوه‌براین، نشانی‌های وب برای هر درخواست به ۲۰۴۸ نویسه محدود است. هنگام ساختن نشانی‌های وب خود، به این محدودیت توجه داشته باشید.

کنش‌های نقشه

کنش‌های نقشه دردسترس عبارت‌اند از: جستجو، مسیرها، نمایش نقشه، ایجاد فهرست کوتاه، و نمایش پانورامای «نمای خیابان». کنش را در نشانی وب درخواست، همراه با پارامترهای الزامی و اختیاری مشخص می‌کنید. همان‌طور که در نشانی‌های وب استاندارد است، پارامترها را بااستفاده از نویسه امپرسند (&) از هم جدا می‌کنید. برای هر کنش، فهرست پارامترها و مقادیر احتمالی آن‌ها در بخش پارامترهای جستجو فهرست شده است.

جستجو

کنش جستجو نتایج جستجو را در سراسر منطقه نقشه قابل‌مشاهده نمایش می‌دهد. هنگام جستجوی مکانی خاص، نقشه حاصل سنجاقی را در مکان مشخص‌شده قرار می‌دهد و جزئیات مکان دردسترس را نمایش می‌دهد.

درحال تشکیل نشانی وب «جستجو»

https://www.google.com/maps/search/?api=1&parameters

پارامترها

• query (الزامی): مکان(های) موردنظر برای برجسته شدن در نقشه را تعریف می‌کند. پارامتر پُرسمان برای همه درخواست‌های جستجو الزامی است.
  • مکان‌ها را به‌صورت نام مکان، نشانی، یا مختصات طول/عرض جغرافیایی جداشده با کاما مشخص کنید. رشته‌ها باید با کدگذاری URL باشند، بنابراین نشانی‌ای مثل «City Hall, New York, NY» باید به City+Hall%2C+New+York%2C+NY تبدیل شود.
  • عبارت‌های جستجوی عمومی را به‌صورت رشته کدبندی‌شده با نشانی وب مشخص کنید، مثل grocery+stores یا restaurants+in+seattle+wa.
• query_place_id (اختیاری): شناسه مکان شناسه‌ای نوشتاری است که مکانی را به‌طور منحصربه‌فرد شناسایی می‌کند. برای کنش search، باید query را مشخص کنید، اما می‌توانید query_place_id را نیز مشخص کنید. اگر هر دو پارامتر را مشخص کنید، query فقط زمانی استفاده می‌شود که Google Maps نتواند شناسه مکان را پیدا کند. اگر می‌خواهید به‌طور قطعی به مؤسسه خاصی پیوند دهید، شناسه مکان بهترین تضمین برای پیوند دادن به مکان درست است. همچنین توصیه می‌شود وقتی برای مکان خاصی بااستفاده از مختصات طول/عرض جغرافیایی پُرسمان می‌کنید، query_place_id را ارسال کنید.

جستجوی نمونه‌ها

جستجوی مکان

در جستجوی مکان، مکان خاصی را بااستفاده از نام مکان، نشانی، یا مختصات طول/عرض جغرافیایی جداشده با کاما جستجو می‌کنید و نقشه حاصل سنجاقی را در آن مکان نمایش می‌دهد. این سه مثال جستجو برای مکان یکسان را بااستفاده از مقادیر مکان متفاوت نشان می‌دهد.

مثال ۱: جستجوی نام مکان «Lumen Field» به نقشه زیر منجر می‌شود:

https://www.google.com/maps/search/?api=1&query=lumen+field

مثال ۲: جستجوی «استادیوم لومن» فقط بااستفاده از مختصات عرض/طول جغرافیایی منجر به نقشه زیر می‌شود. توجه داشته باشید که سنجاقی در نقشه وجود دارد، اما هیچ اطلاعات مکانی اضافی در نقشه یا در پانل کناری ارائه نشده است:

https://www.google.com/maps/search/?api=1&query=47.5951518%2C-122.3316393

مثال ۳: جستجوی Lumen Field بااستفاده از مختصات طول/عرض جغرافیایی و همچنین شناسه مکان منجر به نقشه زیر می‌شود:

https://www.google.com/maps/search/?api=1&query=47.5951518%2C-122.3316393&query_place_id=ChIJKxjxuaNqkFQR3CK6O1HNNqY

مثال ۴: جستجوی نام مکان «Starbucks» منجر به نقشه زیر می‌شود:

https://www.google.com/maps/search/?api=1&query=starbucks

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

https://www.google.com/maps/search/?api=1&query=starbucks&query_place_id=ChIJsU30zM1qkFQRbnOm1_LBoG0

وقتی هدفتان نمایش جزئیات مکانی خاص است، «نشانی‌های وب جستجو» را بااستفاده از یکی از قالب‌های توصیه‌شده زیر بسازید:

• query=PLACE_NAME,ADDRESS
• query=PLACE_NAME&query_place_id=PLACE_ID

برای بازیابی برنامه‌ریزی‌شده «شناسه‌های جا»، می‌توانید از ویژگی‌های Places API: Text Search(ID Only) استفاده کنید. این روشی بدون هزینه برای دریافت «شناسه مکان» است. درباره شناسه مکان و درخواست Place API(جدید) بیشتر بدانید.

وقتی کاربر روی نقطه موردعلاقه در نقشه‌ها کلیک می‌کند یا تک‌ضرب می‌زند، شناسه جا نیز می‌تواند بازیابی شود. جزئیات بیشتر درباره نمادهای نقطه موردعلاقه کلیک‌کردنی را پیدا کنید (JavaScript، Android، iOS)

جستجوی دسته‌ای

در جستجوی طبقه‌ای، عبارت جستجوی کلی را ارسال می‌کنید و Google Maps تلاش می‌کند فهرستگان‌هایی را که با معیارهای شما در نزدیکی مکان مشخص‌شده مطابقت دارند پیدا کند. اگر مکانی مشخص نشده باشد، Google Maps تلاش می‌کند فهرستگان‌های نزدیک به مکان فعلی‌تان را پیدا کند. اگر ترجیح می‌دهید برای جستجوی دسته‌ای مکان ارائه دهید، مکان را در رشته جستجوی عمومی وارد کنید (برای مثال، pizza+seattle+wa).

در این مثال، جستجوی پیتزافروشی‌ها در سیاتل، واشینگتن، به نقشه زیر منجر می‌شود:

https://www.google.com/maps/search/?api=1&query=pizza+seattle+wa

---

مسیرها

کنش «مسیرها» مسیر بین دو یا چند نقطه مشخص‌شده در نقشه، و همچنین فاصله و زمان سفر را نمایش می‌دهد.

تشکیل نشانی وب «مسیرها»

https://www.google.com/maps/dir/?api=1&parameters

پارامترها

• origin: نقطه شروعی را که مسیرها از آن نمایش داده می‌شود تعریف می‌کند. به‌طور پیش‌فرض به مرتبط‌ترین مکان شروع، مانند مکان دستگاه، درصورت دردسترس بودن، می‌رود. اگر هیچ‌کدام وجود نداشته باشد، نقشه حاصل ممکن است فرم خالی‌ای ارائه دهد تا به کاربر اجازه دهد مبدأ را وارد کند. این مقدار می‌تواند نام مکان، نشانی، یا مختصات عرض جغرافیایی/طول جغرافیایی جداشده با کاما باشد. رشته باید با کدگذاری URL باشد، بنابراین نشانی‌ای مانند «City Hall, New York, NY» باید به City+Hall%2C+New+York%2C+NY تبدیل شود.

  توجه: این پارامتر اختیاری است، مگراینکه origin_place_id را در نشانی وب خود مشخص کنید. اگر تصمیم بگیرید origin_place_id را مشخص کنید، باید origin را نیز در نشانی وب اضافه کنید.

• origin_place_id (اختیاری): شناسه مکان شناسه‌ای نوشتاری است که مکانی را به‌طور منحصربه‌فرد شناسایی می‌کند. اگر می‌خواهید مؤسسه‌ای را به‌طور قطعی مشخص کنید، استفاده از شناسه مکان بهترین تضمین است که به مکان درست پیوند خواهید داد. نشانی‌های وبی که از این پارامتر استفاده می‌کنند باید حاوی origin نیز باشند.
• destination: نقطه پایان مسیرها را تعریف می‌کند. اگر هیچ‌کدام نباشد، نقشه حاصل ممکن است فرم خالی‌ای ارائه دهد تا کاربر بتواند مقصد را وارد کند. این مقدار می‌تواند نام مکان، نشانی، یا مختصات عرض جغرافیایی/طول جغرافیایی جداشده با کاما باشد. رشته باید کدبندی نشانی وب شود، بنابراین نشانی‌ای مثل «City Hall, New York, NY» باید به City+Hall%2C+New+York%2C+NY تبدیل شود.

  توجه: این پارامتر اختیاری است، مگراینکه destination_place_id را در نشانی وب خود مشخص کنید. اگر انتخاب کنید که destination_place_id را مشخص کنید، باید destination را نیز در نشانی وب اضافه کنید.

• destination_place_id (اختیاری): شناسه مکان شناسه‌ای نوشتاری است که مکانی را به‌طور منحصربه‌فرد شناسایی می‌کند. اگر می‌خواهید مؤسسه‌ای را به‌طور قطعی مشخص کنید، استفاده از شناسه مکان بهترین تضمین است که به مکان درست پیوند خواهید داد. نشانی‌های وبی که از این پارامتر استفاده می‌کنند باید destination را نیز دربر بگیرند.
• travelmode (اختیاری): روش سفر را تعریف می‌کند. فهرست گزینه‌ها:
• driving
• ‫walking: مسیرهای عابر پیاده و پیاده‌روها را درصورت وجود ترجیح می‌دهد.
• bicycling: مسیرها ازطریق مسیرهای دوچرخه، درصورت وجود. «دوچرخه‌سواری» به حالت سفر با نیروی انسانی اشاره دارد.
• ‫two-wheeler: مسیرهای خیابان‌های ترجیحی برای موتورسیکلت، درصورت دردسترس بودن. «موتورسیکلت» به وسایل نقلیه موتوری دوچرخ، مانند موتورسیکلت، اشاره دارد. برای اطلاعات بیشتر، پوشش موتورسیکلت را ببینید.
• transit
اگر هیچ travelmode مشخص نشده باشد، Google Map یک یا چند مورد از مرتبط‌ترین حالت‌ها را برای مسیر مشخص‌شده و/یا اولویت‌های کاربر نشان می‌دهد.
• dir_action=navigate (اختیاری): بسته به اینکه مبدأ دردسترس باشد یا نه، ناوبری گام‌به‌گام یا پیش‌نمایش مسیر را برای مقصد مشخص‌شده راه‌اندازی می‌کند. اگر کاربر مبدأ را مشخص کند و این مبدأ نزدیک به مکان فعلی کاربر نباشد، یا مکان فعلی دستگاه دردسترس نباشد، نقشه پیش‌نمایش مسیر را راه‌اندازی می‌کند. اگر کاربر مبدأ را مشخص نکند (که در این صورت مبدأ به‌طور پیش‌فرض مکان فعلی دستگاه خواهد بود) یا مبدأ نزدیک به مکان فعلی کاربر باشد، نقشه ناوبری گام‌به‌گام را راه‌اندازی می‌کند. توجه داشته باشید که ناوبری در همه محصولات Google Maps و/یا بین همه مقصدها دردسترس نیست؛ در این موارد، این پارامتر نادیده گرفته خواهد شد.
• waypoints: یک یا چند مکان واسطه را برای مسیریابی جهت‌ها بین origin و destination مشخص می‌کند. بااستفاده از نویسه خط عمودی (|) برای جدا کردن مکان‌ها (برای مثال، Berlin,Germany|Paris,France)، می‌توان چندین نقطه‌مسیر را مشخص کرد. تعداد نقطه‌مسیرهای مجاز بسته به پلاتفرمی که پیوند در آن باز می‌شود متفاوت است، به‌طوری‌که در مرورگرهای تلفن همراه حداکثر سه نقطه‌مسیر و درغیراین‌صورت حداکثر نه نقطه‌مسیر پشتیبانی می‌شود. نقطه‌مسیرها به همان ترتیبی که در نشانی وب فهرست شده‌اند روی نقشه نمایش داده می‌شوند. هر ایستگاه بین راهی می‌تواند نام مکان، نشانی، یا مختصات طول/عرض جغرافیایی جداشده با کاما باشد. رشته‌ها باید کدبندی‌شده با نشانی وب باشند، بنابراین نقطه‌مسیرهایی مثل «Berlin,Germany|Paris,France» باید به Berlin%2CGermany%7CParis%2CFrance تبدیل شوند.

  نکته‌ها:

  • نقاط‌مسیر در همه محصولات Google Maps پشتیبانی نمی‌شود؛ در این موارد این پارامتر نادیده گرفته خواهد شد.
  • این پارامتر اختیاری است، مگراینکه waypoint_place_ids را در نشانی وب خود مشخص کنید. اگر انتخاب کنید که waypoint_place_ids را مشخص کنید، باید waypoints را نیز در نشانی وب بگنجانید.
• waypoint_place_ids (اختیاری): شناسه مکان یک شناسه نوشتاری است که مکان را به‌صورت یکتا شناسایی می‌کند. Waypoint_place_ids به شما امکان می‌دهد فهرستی از شناسه‌های مکان را برای مطابقت با فهرست waypoints ارائه دهید. شناسه‌های مکان باید به همان ترتیب نقاط مسیر فهرست شوند و بااستفاده از نویسه خط عمودی «|» ( کدگذاری‌شده با نشانی وب به‌صورت %7C) از هم جدا شوند. اگر می‌خواهید به‌طور قطعی مؤسسات خاصی را مشخص کنید، شناسه‌های مکان بهترین تضمین برای پیوند دادن به مکان‌های درست هستند. نشانی‌های وبی که از این پارامتر استفاده می‌کنند باید waypoints را نیز دربرگیرند.
• avoid (اختیاری): ویژگی‌هایی را تنظیم می‌کند که مسیر باید سعی کند از آن‌ها اجتناب کند. می‌تواند روی یک یا چند مورد از این گزینه‌ها تنظیم شود که با نویسه ویرگول «,» از هم جدا می‌شوند ( نشانی وب کدبندی‌شده به‌عنوان %2C):
  • ferries
  • highways
  • tolls

مثال‌های مسیر

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

https://www.google.com/maps/dir/?api=1

مثال زیر نقشه‌ای را با مسیرهای دوچرخه‌سواری از «برج سوزن فضایی» به «بازار پایک پلیس» در سیاتل، واشینگتن راه‌اندازی می‌کند.

https://www.google.com/maps/dir/?api=1&origin=Space+Needle+Seattle+WA&destination=Pike+Place+Market+Seattle+WA&travelmode=bicycling

مثال زیر نقشه‌ای را با مسیرهای موتورسیکلت از Google Mumbai به فرودگاه بین‌المللی بمبئی راه‌اندازی می‌کند.

را ببینید.

https://www.google.com/maps/dir/?api=1&origin=Google+Mumbai+India&destination=Mumbai+Airport&travelmode=two-wheeler

مثال زیر نقشه‌ای را با مسیر پیاده‌روی از Google سیدنی، استرالیا به ساختمان ملکه ویکتوریا راه‌اندازی می‌کند.

https://www.google.com/maps/dir/?api=1&origin=Google+Pyrmont+NSW&destination=QVB&destination_place_id=ChIJISz8NjyuEmsRFTQ9Iw7Ear8&travelmode=walking

نمایش نقشه

کنش نقشه نقشه‌ای را بدون نشانگر یا مسیر برمی‌گرداند.

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

https://www.google.com/maps/@?api=1&map_action=map&parameters

پارامترها

• map_action=map (الزامی): نوع نمای نقشه را برای نمایش مشخص می‌کند. Maps و «نمای خیابان» نقطه پایانی یکسانی دارند. برای اطمینان از اینکه نقشه نمایش داده می‌شود، map_action باید به‌عنوان map مشخص شود.
• center (اختیاری): مرکز پنجره نقشه را تعریف می‌کند، و مختصات طول/عرض جغرافیایی را به‌عنوان مقادیر جداشده با کاما می‌پذیرد (برای مثال، -33.8569,151.2152).
• zoom (اختیاری): سطح بزرگ‌نمایی اولیه نقشه را تنظیم می‌کند. مقادیر پذیرفتنی اعداد صحیح از ۰ (کل جهان) تا ۲۱ (ساختمان‌های منفرد) است. حد بالا ممکن است بسته به داده‌های نقشه دردسترس در مکان انتخاب‌شده متفاوت باشد. پیش‌فرض ۱۵ است.
• basemap (اختیاری): نوع نقشه‌ای را که باید نمایش داده شود تعریف می‌کند. مقدار می‌تواند roadmap (پیش‌فرض)، satellite، یا terrain باشد.
• layer (اختیاری): لایه اضافه‌ای را برای نمایش در نقشه تعریف می‌کند، درصورت وجود. مقدار می‌تواند یکی از موارد زیر باشد: none (پیش‌فرض)، transit، traffic، یا bicycling.

نمونه‌های نقشه

این نشانی وب نمونه «نقشه Google» پیش‌فرض را راه‌اندازی می‌کند و در مکان کنونی کاربر متمرکز می‌شود.

https://www.google.com/maps/@?api=1&map_action=map

مثال زیر نقشه‌ای را نمایش می‌دهد که در مرکز آن کاتومبا، نیو ساوت ولز، استرالیا (در -33.712206,150.311941) قرار دارد و پارامترهای اختیاری zoom و basemap را تنظیم می‌کند.

https://www.google.com/maps/@?api=1&map_action=map&center=-33.712206%2C150.311941&zoom=12&basemap=terrain

---

نمایش تمام‌نمای «نمای خیابان»

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

«نمای خیابان Google» نماهای تمام‌نمایی از مکان‌های تعیین‌شده در سراسر منطقه پوشش خود ارائه می‌دهد. کره‌های عکس همیاری‌شده کاربر و مجموعه‌های ویژه «نمای خیابان» نیز دردسترس است.

درحال ایجاد نشانی وب «نمای خیابان»

https://www.google.com/maps/@?api=1&map_action=pano&parameters

پارامترها

• map_action=pano (الزامی): نوع نمایشی را که باید نمایش داده شود مشخص می‌کند. ‫Maps و «نمای خیابان» از نقطه پایانی یکسانی استفاده می‌کنند. برای اطمینان از نمایش تمام‌نما، action باید به‌عنوان pano مشخص شود.

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

• viewpoint: نمایشگر، تمام‌نمای عکاسی‌شده را نزدیک به مکان viewpoint نمایش می‌دهد که به‌صورت مختصات طول/عرض جغرافیایی جداشده با کاما (برای مثال ۴۶٫۴۱۴۳۸۲،۱۰٫۰۱۳۹۸۸) مشخص شده است. چون تصاویر «نمای خیابان» به‌طور دوره‌ای بازآوری می‌شود و ممکن است عکس‌ها هربار از موقعیت‌های کمی متفاوت گرفته شود، ممکن است هنگام به‌روزرسانی تصاویر، مکان شما به سراسرنمای دیگری منتقل شود.
• pano: شناسه تمام‌نمای خاص تصویری که باید نمایش داده شود. اگر pano را مشخص کنید، می‌توانید viewpoint را نیز مشخص کنید. ‫viewpoint فقط زمانی استفاده می‌شود که Google Maps نتواند شناسه تمام‌نما را پیدا کند. اگر pano مشخص شده باشد اما پیدا نشود، و viewpoint مشخص نشده باشد، هیچ تصویر پانورامایی نمایش داده نمی‌شود. درعوض، Google Maps در حالت پیش‌فرض باز می‌شود و نقشه‌ای را نشان می‌دهد که مرکز آن مکان فعلی کاربر است.

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

• heading: جهت قطب‌نمای دوربین را به‌درجه در جهت عقربه‌های ساعت از شمال نشان می‌دهد. مقادیر پذیرفته‌شده از -۱۸۰ تا ۳۶۰ درجه است. اگر حذف شود، عنوان پیش‌فرض براساس نقطه دید (درصورت مشخص شدن) پُرسمان و مکان واقعی تصویر انتخاب می‌شود.
• pitch: زاویه دوربین را به‌سمت بالا یا پایین مشخص می‌کند. زاویه گام با درجه از ۹۰- تا ۹۰ مشخص می‌شود. مقادیر مثبت دوربین را به سمت بالا و مقادیر منفی دوربین را به سمت پایین زاویه‌دار می‌کند. گام پیش‌فرض ۰ براساس موقعیت دوربین در زمان ثبت تصویر تنظیم شده است. به‌همین دلیل، زاویه صفر اغلب، اما نه همیشه، افقی است. برای مثال، تصویری که روی تپه گرفته شده است احتمالاً دارای زاویه پیش‌فرضی است که افقی نیست.
• fov: میدان دید افقی تصویر را تعیین می‌کند. میدان دید برحسب درجه بیان می‌شود و محدوده آن ۱۰ تا ۱۰۰ است. مقدار پیش‌فرض آن ۹۰ است. هنگام کار با درگاه دید ثابت، میدان دید به‌عنوان سطح بزرگ‌نمایی درنظر گرفته می‌شود، و اعداد کوچک‌تر نشان‌دهنده سطح بزرگ‌نمایی بالاتر است.

مثال‌های «نمای خیابان»

دو نمونه اول، تمام‌نمایی از برج ایفل را نمایش می‌دهند. مثال یک فقط از viewpoint برای مکان استفاده می‌کند و پارامترهای اختیاری heading، pitch، و fov را تنظیم می‌کند. برای مقایسه، مثال دوم از شناسه pano و همچنین پارامترهای یکسانی که در مثال اول تنظیم شده است استفاده می‌کند. مثال سوم تصویر تمام‌نمای فضای داخلی را نشان می‌دهد.

مثال ۱: فقط از viewpoint برای مشخص کردن مکان استفاده می‌کند.

https://www.google.com/maps/@?api=1&map_action=pano&viewpoint=48.857832%2C2.295226&heading=-45&pitch=38&fov=80

مثال ۲: از شناسه pano و همچنین مکان viewpoint استفاده می‌کند. شناسه pano بر viewpoint اولویت دارد. در این مثال، شناسه پانوراما پیدا می‌شود، بنابراین viewpoint نادیده گرفته می‌شود. توجه کنید که تصویر تمام‌نمایی که برای شناسه pano نمایش داده می‌شود کمی متفاوت است، و جدیدتر از تصویری است که فقط بااستفاده از viewpoint پیدا شده است.

https://www.google.com/maps/@?api=1&map_action=pano&pano=tu510ie_z4ptBZYo2BGEJg&viewpoint=48.857832%2C2.295226&heading=-45&pitch=38&fov=80

مثال ۳: تمام‌نمایی از فضای داخلی رستوران «ساراسترو» در لندن، بریتانیا را نمایش می‌دهد که با شناسه تمام‌نما مشخص شده است.

https://www.google.com/maps/@?api=1&map_action=pano&pano=4U-oRQCNsC6u7r8gp02sLA

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

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

• برای جاوا اسکریپت، از کلاس StreetViewPanorama استفاده کنید.
• برای Android، از کلاس عمومی StreetViewPanoramaLocation استفاده کنید.
• برای iOS، از کلاس GMSPanorama استفاده کنید.
• همچنین می‌توانید درخواست‌های فراداده را بااستفاده از Google Street View Image API انجام دهید. درخواست‌های فراداده تصویر، داده‌هایی درباره تمام‌نماهای «نمای خیابان» ارائه می‌دهند، ازجمله شناسه تمام‌نما.

---

ایجاد فهرست نهایی خرید

کنش فهرست کوتاه فهرستی از مکان‌های خاص را نمایش می‌دهد و به کاربر امکان می‌دهد آن‌ها را در نمایه Google Maps خود ذخیره کند، با دیگران هم‌رسانی کند، یا هر مکان را به‌صورت جداگانه کاوش کند.

درحال تشکیل نشانی وب «فهرست نهایی خرید»

https://www.google.com/maps/@?api=1&map_action=shortlist&parameters

پارامترها

• map_action=shortlist (الزامی): کنش فهرست کوتاه را مشخص می‌کند.
• place_ids (الزامی): مکان‌هایی را که باید در فهرست نهایی خرید اضافه شود تعریف می‌کند. این پارامتر یک یا چند شناسه مکان را به‌عنوان مقادیر جداشده با کاما می‌پذیرد. می‌توانید حداکثر ۲۰ شناسه مکان مشخص کنید.

نمونه فهرست نهایی خرید

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

https://www.google.com/maps/@?api=1&map_action=shortlist&place_ids=ChIJKxjxuaNqkFQR3CK6O1HNNqY,ChIJdWjwULVqkFQRh8ifgzporms,ChIJQ_oEiK1qkFQRg3bU4l3mmWs

---

مثال‌های بیشتر

نمونه‌های مسیر بااستفاده از نقطه‌مسیر

نمونه‌های دستورالعمل زیر Google Maps را راه‌اندازی می‌کنند و مسیرهای رانندگی از پاریس، فرانسه به شربورگ، فرانسه را نمایش می‌دهند و ازطریق ایستگاه‌های بین راه زیر هدایت می‌کنند:

شهر، کشور	نام مکان	شناسه جا
۱. ورسای، فرانسه	کاخ ورسای	ChIJdUyx15R95kcRj85ZX8H8OAU
۲. شارتر، فرانسه	کلیسای جامع شارتر	ChIJKzGHdEgM5EcR_OBTT3nQoEA
۳. لو مان، فرانسه	کلیسای جامع سنت ژولین لومان	ChIJG2LvQNCI4kcRKXNoAsPi1Mc
۴. کان، فرانسه	قلعه کان	ChIJ06tnGbxCCkgRsfNjEQMwUsc

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

مثال ۱: نقطه‌مسیرهایی که به‌صورت «شهر، کشور» تعریف شده‌اند:

https://www.google.com/maps/dir/?api=1&origin=Paris%2CFrance&destination=Cherbourg%2CFrance&travelmode=driving&waypoints=Versailles%2CFrance%7CChartres%2CFrance%7CLe+Mans%2CFrance%7CCaen%2CFrance

مثال ۲: ایستگاه‌های بین راهی که به‌عنوان نام مکان‌های خاص تعریف شده‌اند:

https://www.google.com/maps/dir/?api=1&origin=Paris%2CFrance&destination=Cherbourg%2CFrance&travelmode=driving&waypoints=Palace+of+Versailles%7CChartres+Cathedral%7CCathedral+of+Saint+Julian+of+Le+Mans%7CCaen+Castle

مثال ۳: نقاط‌مسیر به‌عنوان شهر، کشور تعریف شده‌اند و همچنین waypoint_place_ids را برای مؤسسه‌ای خاص در هر نقطه مسیر ارائه می‌دهد:

https://www.google.com/maps/dir/?api=1&origin=Paris%2CFrance&destination=Cherbourg%2CFrance&travelmode=driving&waypoints=Versailles%2CFrance%7CChartres%2CFrance%7CLe+Mans%2CFrance%7CCaen%2CFrance&waypoint_place_ids=ChIJdUyx15R95kcRj85ZX8H8OAU%7CChIJKzGHdEgM5EcR_OBTT3nQoEA%7CChIJG2LvQNCI4kcRKXNoAsPi1Mc%7CChIJ06tnGbxCCkgRsfNjEQMwUsc

مثال ۴: ایستگاه‌های بین راه را به‌عنوان «شهر، کشور» تعریف می‌کند، اما ایستگاه‌های بین راه را با ترتیبی متفاوت از مثال‌های قبلی فهرست می‌کند. نشان می‌دهد که نقشه نقاط‌مسیر را به‌ترتیبی که در نشانی وب فهرست شده‌اند نمایش می‌دهد.

https://www.google.com/maps/dir/?api=1&origin=Paris%2CFrance&destination=Cherbourg%2CFrance&travelmode=driving&waypoints=Versailles%2CFrance%7CCaen%2CFrance%7CLe+Mans%2CFrance%7CChartres%2CFrance

نمونه‌های نقشه

نقشه‌ای را با basemap (ماهواره) و layer (حمل‌ونقل عمومی) مشخص‌شده نمایش می‌دهد.

https://www.google.com/maps/@?api=1&map_action=map&center=37.7992940%2C-122.3976113&zoom=15&basemap=satellite&layer=transit

نمونه‌های «نمای خیابان»

تمام‌نمای «نمای خیابان» را بااستفاده از کلید تصویر FIFE به‌عنوان شناسه pano نمایش می‌دهد. توجه داشته باشید که شناسه pano با F: شروع می‌شود.

https://www.google.com/maps/@?api=1&map_action=pano&pano=F:-ud6AZSB-sQg/V0cfCSV3OWI/AAAAAAAAG1U/UQEoc5sXPQEIP7zzD6SWzmKb8Vbug47uQCLIB&heading=22&pitch=-5&fov=55

بهبود نشانی‌های وب Maps با پارامترهای UTM

برای کمک به Google در درک بهتر نحوه ادغام نشانی‌های وب Maps توسط توسعه‌دهندگان و اطمینان از عملکرد بهینه، توصیه می‌کنیم پارامترهای ردیابی UTM را در ساختار نشانی وب خود بگنجانید. با افزودن پارامترهای utm_source و utm_campaign، داده‌های ارزشمندی ارائه می‌دهید که به ما امکان می‌دهد الگوهای استفاده را تجزیه‌وتحلیل کنیم و محصول «نشانی‌های وب Maps» را بهبود بخشیم.

برای پارامتر utm_source، لطفاً از نام برنامه‌تان استفاده کنید. پارامتر utm_campaign باید کنش موردنظر کاربر را منعکس کند، مثلاً «location_sharing»،‏ «place_details_search»، یا «directions_request».

برای مثال، نشانی وب با پارامترهای UTM ممکن است به این شکل باشد:

https://www.google.com/maps/search/?api=1&query=Sydney+Opera+House&query_place_id=ChIJ3S-JXmauEmsRUcIaWtf4MzE&utm_source=YOUR_APP_NAME&utm_campaign=place_details_search