مرجع سریع Maps JavaScript API

‫Maps JavaScript API یک میانای برنامه‌سازی کاربردی وب سمت کارخواه برای ایجاد نقشه‌های دوبعدی و سه‌بعدی در صفحه‌های وب، افزودن نشانگرها، گرافیک‌های سفارشی، پویانمایی‌ها، و لایه‌های داده تعاملی، و ساختن ویژگی‌های مکان با کتابخانه «جاها» است.

Maps JavaScript API: key facts

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

Maps JavaScript API: زمان استفاده از آن

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

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

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

  • باید نقشه مکان کسب‌وکار یا پیوند مسیرها را بدون نوشتن جاوا اسکریپت سفارشی جاسازی کنید. به‌جای آن از Maps Embed API استفاده کنید.
  • فقط به پیوندی نیاز دارید که Google Maps را با مکان، جستجو، یا مسیر باز کند. درعوض از نشانی‌های وب Maps استفاده کنید.
  • به ردیابی ناوگان تحویل زمان‌بندی‌شده یا هم‌سفری ادغام‌شده با Driver SDK تلفن همراه و اصالت‌سنجی JWT باطن نیاز دارید. درعوض از سرویس Fleet Engine استفاده کنید.

Maps JavaScript API: setup

بسته‌های رسمی Maps JavaScript API:

  • npm: @googlemaps/js-api-loader
  • npm: @types/google.maps
  • npm: @googlemaps/markerclusterer
  • اغلب با این میانای برنامه‌سازی کاربردی استفاده می‌شود: Places API (جدید)

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

  • مشکل: وقتی کلید میانای برنامه‌سازی کاربردی یا صورت‌حساب به‌درستی پیکربندی نشده باشد، به‌جای خطا، نقشه تاریک یا تصویر منفی «نمای خیابان» با ته‌نقش «فقط برای اهداف توسعه» نشان داده می‌شود. راه‌حل: صورت‌حساب را در پروژه Cloud فعال کنید، کلید API معتبری را در هر درخواست اضافه کنید، و کنسول مرورگر را برای کد خطای خاص بررسی کنید. /maps/documentation/javascript/error-messages را ببینید.
  • مشکل: سرویس‌های قدیمی مانند PlacesService،‏ DirectionsService، و DistanceMatrixService در پروژه‌های جدیدی که API قدیمی در آن‌ها فعال نیست، LegacyApiNotActivatedMapError را برمی‌گردانند. اصلاح: از معادل‌های جدید (کلاس Place، کلاس Route، کلاس RouteMatrix) که توسط Places API (جدید) و Routes API پشتیبانی می‌شوند استفاده کنید. /maps/legacy#LegacyApiNotActivatedMapError را ببینید.
  • مشکل: از نسخه ۳.۶۵، نقشه‌های ماهواره‌ای و ترکیبی دیگر به تصاویر ۴۵ درجه تغییر نمی‌کنند و map.setTilt(45) تأثیری ندارد. راه‌حل: به‌جای تصاویر ۴۵ درجه، از نقشه‌های سه‌بعدی استفاده کنید. /maps/deprecations را ببینید.
  • مشکل: «نشانگرهای پیشرفته» به شناسه نقشه نیاز دارند؛ نقشه‌هایی که بدون شناسه نقشه ایجاد شده‌اند نمی‌توانند از AdvancedMarkerElement استفاده کنند. رفع مشکل: شناسه نقشه در کنسول Cloud ایجاد کنید (یا از DEMO_MAP_ID برای آزمایش استفاده کنید) و mapId را در نقشه تنظیم کنید. /maps/documentation/javascript/advanced-markers/start را ببینید.

Maps JavaScript API: legacy and deprecated features

  • سرویس مسیرها (google.maps.DirectionsService): از ۲۰۲۵/۰۳/۰۱ قدیمی شده است. جایگزین: کلاس Route. نشانه: LegacyApiNotActivatedMapError در پروژه‌هایی که Directions API قدیمی در آن‌ها فعال نیست. راهنمای انتقال را ببینید.
  • سرویس ماتریس فاصله (google.maps.DistanceMatrixService): از ۲۰۲۵/۰۳/۰۱ قدیمی شده است. جایگزین: کلاس RouteMatrix. نشانه: LegacyApiNotActivatedMapError در پروژه‌هایی که Distance Matrix API قدیمی در آن‌ها فعال نیست. راهنمای انتقال را ببینید.
  • سرویس Places‏ (google.maps.places.PlacesService): از ۲۰۲۵/۰۳/۰۱ قدیمی شده است. جایگزین: کلاس Place (Places API (New)). نشانه: LegacyApiNotActivatedMapError در پروژه‌هایی که Places API قدیمی در آن‌ها فعال نیست. راهنمای انتقال را ببینید.
  • google.maps.Marker: منسوخ‌شده از ۲۰۲۴-۰۲-۲۲. جایگزین: google.maps.marker.AdvancedMarkerElement. نشانه: هنوز کار می‌کند و برای توقف دائم زمان‌بندی نشده است؛ اشکال‌های موجود برطرف نخواهد شد. راهنمای انتقال را ببینید.
  • KmlLayer: منسوخ‌شده از ۲۰۲۶/۰۴/۳۰. جایگزین: سبک‌بندی داده‌محور برای مجموعه‌داده‌ها، یا تجزیه‌کننده‌های KML طرف سوم با لایه «داده». نشانه: KmlLayer در نسخه ۳.۶۶ و نسخه‌های جدیدتر دردسترس نیست؛ نسخه ۳.۶۵، آخرین نسخه‌ای که از آن پشتیبانی می‌کند، در مه ۲۰۲۷ از رده خارج می‌شود. راهنمای انتقال را ببینید.
  • لایه نقشه حرارتی (کتابخانه دیداری‌سازی): از ۲۰۲۶/۰۵/۲۰ از رده خارج شده است. جایگزین: کتابخانه‌های طرف سوم مانند deck.gl HeatmapLayer. نشانه: از مه ۲۰۲۶ دردسترس نیست. راهنمای انتقال را ببینید.
  • کتابخانه Drawing: از ۲۰۲۶/۰۶/۰۴ از رده خارج شده است. جایگزین: Terra Draw. نشانه: از مه ۲۰۲۶ دردسترس نیست. راهنمای انتقال را ببینید.
  • تصاویر ۴۵ درجه: از کار افتاده از ۲۰۲۶-۰۵-۲۰. جایگزین: نقشه‌های سه‌بعدی. نشانه: map.setTilt(45) بی‌تأثیر است؛ نمای ماهواره‌ای از بالا به پایین باقی می‌ماند. راهنمای انتقال را ببینید.
  • google.maps.event.addDomListener() و addDomListenerOnce(): از ۲۰۲۲/۰۴/۰۷ منسوخ شده است. جایگزین: DOM استاندارد addEventListener().
  • گزینه‌های bounds، location، و radius در «سرویس تکمیل خودکار جا»: منسوخ‌شده از ۲۰۲۳/۰۵/۱۸. جایگزین: locationBias و locationRestriction.
  • gmp-place-content-config (PlaceContentConfigElement) در کیت میانای کاربر «جاها»: منسوخ‌شده. جایگزین: عناصر محتوا را مستقیماً به عناصر «جزئیات جا» یا در پیکربندی «جستجوی جاها» اضافه کنید.
  • کتابخانه بافت محلی: از رده خارج شد. جایگزین: Places Library.

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

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

Maps JavaScript API: Address validation

‫Maps JavaScript API: سبک‌بندی داده‌محور برای مرزها

‫Maps JavaScript API: سبک‌بندی داده‌محور برای مجموعه‌داده‌ها

Maps JavaScript API: Datasets

  • افزودن لایه KML به نقشه. توجه: در Maps JavaScript API،‏ KmlLayer منسوخ شده است (آخرین پشتیبانی در نسخه ۳.۶۵، از رده خارج شدن در مه ۲۰۲۷)؛ به «سبک‌بندی داده‌محور» برای مرزها یا مجموعه‌داده‌ها مهاجرت کنید، یا GeoJSON را در لایه «داده» بار کنید. لایه‌های KML همچنان در Android و iOS ازطریق «کتابخانه‌های کاروری‌های کیت توسعه نرم‌افزار Maps» پشتیبانی می‌شوند.
  • افزودن لایه GeoRSS به نقشه. توجه: در Maps JavaScript API منسوخ شده است (KmlLayer آخرین‌بار در نسخه ۳.۶۵ پشتیبانی شده است و در مه ۲۰۲۷ از رده خارج می‌شود)؛ فیدهای GeoRSS را به GeoJSON تبدیل کنید و آن‌ها را با map.data.addGeoJson() در لایه «داده» بار کنید.
  • افزودن داده‌های GeoJSON به نقشه.

Maps JavaScript API: Directions and Routing

Maps JavaScript API: Elevation

Maps JavaScript API: Fleet Engine

Maps JavaScript API: Geocoding

Maps JavaScript API: Maps

Maps JavaScript API: Maps annotations

Maps JavaScript API: Maps styling

Maps JavaScript API: Other

Maps JavaScript API: Photorealistic 3D maps

Maps JavaScript API: Places

‫Maps JavaScript API: کیت میانای کاربر «جاها»

  • عنصر میانای کاربری را که خلاصه‌ها و مرورهای تولیدشده با هوش مصنوعی درباره مکان‌های خاص را نمایش می‌دهد به صفحه وب یا برنامه تلفن همراه اضافه کنید. توجه: فقط در وب پشتیبانی می‌شود (کیت میانای کاربر «جاها» در Maps JavaScript API)؛ کیت‌های میانای کاربر «جاها» در تلفن همراه عنصر خلاصه هوش مصنوعی ندارند. الزام رعایت مقررات منطقه اقتصادی اروپا: برای نمایش داده‌های مکان روی نقشه در منطقه اقتصادی اروپا (EEA)، از مؤلفه‌های «کیت میانای کاربر جاها» در سمت کارخواه در Maps JavaScript API استفاده کنید، نه اینکه سرویس‌های وب Places API را از سرور زیرینه فراخوانی کنید. پرسشگان و شرایط کامل: https://developers.google.com/maps/comms/eea/faq
  • سبک CSS را بر عنصر میانای کاربر داده‌های مکان اعمال کنید. توجه: ویژگی‌های سفارشی CSS برای عناصر «کیت میانای کاربر جاها» در Maps JavaScript API اعمال می‌شود؛ «کیت توسعه نرم‌افزار جاها» برای Android و «کیت توسعه نرم‌افزار جاها» برای iOS نماهای «کیت میانای کاربر جاها» را به‌صورت برنامه‌نویسی‌شده بااستفاده از مشخصه‌های طرح‌واره و سبک، سبک‌بندی می‌کنند. الزامات رعایت مقررات منطقه اقتصادی اروپا: برای نمایش داده‌های مکان روی نقشه در منطقه اقتصادی اروپا (EEA)، سرویس‌های وب Places API را از سرور زیرینه فراخوانی نکنید. از مؤلفه‌های «کیت میانای کاربر جاها» سمت کارخواه در پلاتفرم هدف (Maps JavaScript API در وب، Places SDK for Android در Android، یا Places SDK for iOS در iOS) استفاده کنید. پرسشگان و شرایط کامل: https://developers.google.com/maps/comms/eea/faq
  • با ابزار سفارشی‌سازی عنصر میانای کاربر، پیکربندی‌ها و سبک عنصر میانای کاربر داده‌های مکان را سفارشی‌سازی کنید. توجه: الزامات رعایت مقررات منطقه اقتصادی اروپا: برای نمایش داده‌های مکان روی نقشه در منطقه اقتصادی اروپا (EEA)، وب‌سرویس‌های Places API را از سرور زیرینه فراخوانی نکنید. از مؤلفه‌های «کیت میانای کاربر جاها» سمت کارخواه در پلاتفرم هدف (Maps JavaScript API در وب، Places SDK for Android در Android، یا Places SDK for iOS در iOS) استفاده کنید. پرسشگان و شرایط کامل: https://developers.google.com/maps/comms/eea/faq
  • عنصر میانای کاربری را که اطلاعات مربوط به مکان خاصی را نمایش می‌دهد به صفحه وب یا برنامه تلفن همراه اضافه کنید. توجه: الزامات رعایت مقررات منطقه اقتصادی اروپا: برای نشان دادن داده‌های مکان روی نقشه در منطقه اقتصادی اروپا (EEA)، وب‌سرویس‌های Places API را از سرور زیرینه فراخوانی نکنید. از مؤلفه‌های «کیت میانای کاربر جاها» سمت کارخواه در پلاتفرم هدف (Maps JavaScript API در وب، Places SDK for Android در Android، یا Places SDK for iOS در iOS) استفاده کنید. پرسشگان و شرایط کامل: https://developers.google.com/maps/comms/eea/faq
  • عنصر میانای کاربری را که فهرستی از مکان‌ها را براساس رشته پُرسمان نمایش می‌دهد به صفحه وب اضافه کنید. توجه: هم در صفحه‌های وب (میانای برنامه‌سازی کاربردی جاوا اسکریپت Maps) و هم در برنامه‌های تلفن همراه (کیت توسعه نرم‌افزار Places برای Android و کیت توسعه نرم‌افزار Places برای iOS) پشتیبانی می‌شود. الزامات رعایت مقررات منطقه اقتصادی اروپا: برای نمایش داده‌های مکان روی نقشه در منطقه اقتصادی اروپا (EEA)، سرویس‌های وب Places API را از سرور زیرینه فراخوانی نکنید. از مؤلفه‌های «کیت میانای کاربر جاها» سمت کارخواه در پلاتفرم هدف (Maps JavaScript API در وب، Places SDK for Android در Android، یا Places SDK for iOS در iOS) استفاده کنید. پرسشگان و شرایط کامل: https://developers.google.com/maps/comms/eea/faq
  • عنصر میانای کاربری را که فهرستی از مکان‌های نزدیک به یک مکان خاص را نمایش می‌دهد به صفحه وب اضافه کنید. توجه: هم در صفحه‌های وب (Maps JavaScript API) و هم در برنامه‌های تلفن همراه (Places SDK for Android و Places SDK for iOS) پشتیبانی می‌شود. الزامات رعایت مقررات منطقه اقتصادی اروپا: برای نمایش داده‌های مکان روی نقشه در منطقه اقتصادی اروپا (EEA)، سرویس‌های وب Places API را از سرور زیرینه فراخوانی نکنید. از مؤلفه‌های «کیت میانای کاربر جاها» سمت کارخواه در پلاتفرم هدف (Maps JavaScript API در وب، Places SDK for Android در Android، یا Places SDK for iOS در iOS) استفاده کنید. پرسشگان و شرایط کامل: https://developers.google.com/maps/comms/eea/faq
  • افزودن عنصر میانای کاربر تکمیل خودکار پایه به صفحه وب یا برنامه‌ای که شناسه‌های «مکان Google» را براساس رشته پُرسمان برمی‌گرداند. توجه: الزامات رعایت مقررات منطقه اقتصادی اروپا: برای نمایش داده‌های مکان روی نقشه در منطقه اقتصادی اروپا (EEA)، وب‌سرویس‌های Places API را از سرور زیرینه فراخوانی نکنید. از مؤلفه‌های «کیت میانای کاربر جاها» سمت کارخواه در پلاتفرم هدف (Maps JavaScript API در وب، Places SDK for Android در Android، یا Places SDK for iOS در iOS) استفاده کنید. پرسشگان و شرایط کامل: https://developers.google.com/maps/comms/eea/faq

Maps JavaScript API: Street View