پیام های خطا

به کمک انسانی نیاز دارید؟
به صفحه پشتیبانی Google Maps Platform بروید.
این صفحه پیام‌های خطا فقط برای مرجع است. اینجا است تا به شما کمک کند خطاهای Maps JavaScript API را خودتان عیب‌یابی کنید. اگر بخواهید با ارسال بازخورد ازطریق این صفحه از یک انسان کمک بگیرید، به کسی که بتواند به شما کمک کند دسترسی پیدا نخواهید کرد. بااین‌حال، اگر مشکلی در محتوای این صفحه پیدا کردید، لطفاً ازطریق پیوند بازخورد به ما اطلاع دهید. متشکریم!

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

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

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

عیب‌یابی

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

جریان زیر به شما کمک می‌کند مشکل را عیب‌یابی کنید.

آیا از کلید میانای API استفاده می‌کنید؟

مطمئن نیستم. چگونه می‌توانم بررسی کنم که آیا از کلید میانای API استفاده می‌کنم؟

کلید میانای برنامه‌سازی کاربردی به‌عنوان پارامتر key در نشانی وبی که برای بار کردن Maps JavaScript API استفاده می‌شود ارسال می‌شود. در اینجا چند گزینه برای بررسی اینکه آیا از کلید API استفاده می‌کنید یا نه ارائه شده است:

• از افزونه Chrome Google Maps Platform API Checker استفاده کنید. این کار به شما امکان می‌دهد تعیین کنید که آیا وب‌سایتتان به‌درستی از میاناهای برنامه‌سازی کاربردی Maps دارای پروانه Google استفاده می‌کند یا نه.
• اگر از کتابخانه یا افزونه‌ای برای بار کردن Maps JavaScript API استفاده می‌کنید، تنظیمات آن کتابخانه را بررسی کنید و به‌دنبال گزینه کلید API بگردید.
• خطاهای مرورگر را بررسی کنید. اگر پیام‌های زیر را می‌بینید، از کلید میانای برنامه‌سازی کاربردی به‌درستی استفاده نمی‌کنید:
  • هشدار Google Maps JavaScript API: NoApiKeys
  • خطای Google Maps JavaScript API: MissingKeyMapError

برای توسعه‌دهندگان وب:

• اگر به کد منبع برنامه‌تان دسترسی دارید، به‌دنبال برچسب <script> بگردید که برای بار کردن Maps JavaScript API استفاده می‌شود. هنگام بار کردن Maps JavaScript API،‏ YOUR_API_KEY را در کد زیر با کلید API خود جایگزین کنید.

    <script async defer
      src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap">
    </script>

• ترافیک شبکه تولیدشده توسط وب‌سایتتان را در مرورگر بررسی کنید. در Chrome، این مورد را می‌توان بااستفاده از برگه DevTools شبکه مشاهده کرد. در اینجا درخواست‌های شبکه‌ای را که وب‌سایت شما ایجاد کرده است مشاهده خواهید کرد. درخواست‌های انجام‌شده بااستفاده از Maps JavaScript API تحت مسیر maps/api/js خواهد بود. در اینجا می‌توانید تأیید کنید که آیا درخواست‌ها از پارامتر key استفاده می‌کنند یا نه. فیلتر کردن ترافیک شبکه براساس maps/api/js هنگام مشاهده برگه شبکه می‌تواند مفید باشد.

نه، از کلید میانای API استفاده نمی‌کنم.

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

بله، از کلید میانای API استفاده می‌کنم.

عالی! بیایید ادامه دهیم و بررسی کنیم که آیا حساب صورت‌حساب به پروژه شما پیوست شده است یا نه.

آیا حساب صورت‌حساب به پروژه‌تان پیوست شده است؟

مطمئن نیستم. چگونه می‌توانم بررسی کنم که آیا حساب صورت‌حساب به پروژه من پیوست شده است یا نه؟

به صفحه صورت‌حساب در کنسول Google Cloud بروید و پروژه‌ای را که کلید میانای API شما تحت آن ایجاد شده است انتخاب کنید. برای تأیید اینکه کلید با پروژه مرتبط است:

1. به بخش اعتبارنامه‌ها بروید که از نوار کناری سمت راست در زیر پلاتفرم Google Maps > اعتبارنامه‌ها قابل‌دسترسی است.
2. بررسی کنید کلید میانای API که درحال‌حاضر در وب‌سایتتان استفاده می‌کنید در فهرست باشد. اگر این‌طور نیست، به پروژه دیگری بروید و اعتبارنامه‌ها را در آنجا بررسی کنید.
3. اگر نمی‌توانید پروژه کلید میانای API خود را پیدا کنید، ممکن است دسترسی به این پروژه را ازدست داده باشید. از دیگران در سازمانتان کمک بخواهید. اگر پروژه اصلی پیدا نشد، باید:
   1. پروژه جدیدی ایجاد کنید. این کار را می‌توانید با انتخاب پروژه جدید از فهرست پروژه‌ها، یا با انتخاب ایجاد پروژه ازطریق صفحه مدیر منابع انجام دهید.
   2. کلید میانای API جدیدی ایجاد کنید. این کار را می‌توانید در صفحه اطلاعات اعتباری انجام دهید. پس‌از رفتن به آنجا، روی ایجاد اطلاعات کاربری کلیک کنید و سپس کلید میانای API را انتخاب کنید.

وقتی پروژه‌تان را در کنسول Cloud پیدا کردید، با رفتن به بخش صورت‌حساب در منو سمت راست، بررسی کنید که آیا حساب صورت‌حساب پیوست شده است یا نه.

نه، حساب صورت‌حساب به پروژه من پیوست نشده است.

به صفحه فعال کردن صورت‌حساب در کنسول Cloud بروید و حساب صورت‌حسابی به پروژه‌تان اضافه کنید. برای اطلاعات بیشتر، به شروع به کار با Google Maps Platform مراجعه کنید.

بله، حساب صورت‌حساب به پروژه من پیوست شده است.

عالی! بیایید مطمئن شویم روش صدور صورت‌حساب ارائه‌شده معتبر است.

آیا روش صدور صورت‌حساب ارائه‌شده دیگر معتبر نیست (برای مثال، کارت اعتباری منقضی‌شده)؟

می‌توانید روش پرداخت را در کنسول Cloud اضافه، حذف، یا به‌روز کنید.

آیا حد روزانه خودتحمیلی در API فراتر رفته است؟

اگر برای هرکدام از میاناهای برنامه‌سازی کاربردی‌تان حد روزانه تنظیم کرده‌اید، که برای جلوگیری از افزایش‌های غیرمنتظره رایج است، می‌توانید این مشکل را با افزایش حد روزانه برطرف کنید.

می‌توانید با رفتن به داشبورد میاناهای برنامه‌سازی کاربردی و سرویس‌ها در کنسول Cloud، محدودیت‌های روزانه‌تان را بررسی کنید. وقتی به آنجا رسیدید:

1. اگر درخواست شد، پروژه‌ای را انتخاب کنید.
2. یک API را از فهرست انتخاب کنید، سپس روی برگه سهمیه‌ها کلیک کنید.

آیا کلید میانای API شما محدودیت نشانی IP دارد؟

کلیدهای API با محدودیت نشانی‌های IP فقط با سرویس‌های وبی قابل‌استفاده هستند که برای استفاده از سمت سرور درنظر گرفته شده‌اند (مانند Geocoding API و دیگر میاناهای برنامه‌سازی کاربردی سرویس وب). Most of these web services have equivalent services within the Maps JavaScript API (for example, see the Geocoding Service). برای استفاده از سرویس‌های سمت کارخواه Maps JavaScript API، باید کلید API جداگانه‌ای ایجاد کنید که می‌توان آن را با محدودیت ارجاع‌دهنده‌های HTTP ایمن کرد (به دریافت، افزودن، و محدود کردن کلید API مراجعه کنید).

کدهای خطای Maps JavaScript API برای توسعه‌دهندگان و مالکان سایت

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

خطاهای بار کردن نقشه

اگر هنگام بار کردن Maps JavaScript API با خطایی مواجه شدید، برای یافتن توضیحات مربوط به کدهای خطا، جدول زیر را ببینید.

کد خطا	پیام	شرح
NotLoadingAPIFromGoogleMapsError	‫Maps JavaScript API باید مستقیماً از سرورهای Google بارگیری شود.	عنصر متن که Maps JavaScript API را بار می‌کند به‌درستی در صفحه‌تان گنجانده نشده است. برای اینکه API به‌درستی کار کند، باید مستقیماً از https://maps.googleapis.com بار شود. بار کردن Maps JavaScript API را ببینید.
TOSViolationMapError	به‌نظر می‌رسد این وب‌سایت «شرایط خدمات Google Maps API» را نقض می‌کند. Google Maps API برای این وب‌سایت غیرفعال شده است.	برنامه‌تان به‌دلیل عدم رعایت «شرایط خدمات Google Maps Platform» مسدود شد. پیش‌از این، چند اعلان ایمیلی برایتان ارسال شده بود. برای پژوهش‌خواهی کردن درباره مسدود شدن و بازبینی پیاده‌سازی‌تان، فرم پژوهش‌خواهی شرایط خدمات «پلاتفرم Google Maps» را تکمیل کنید. ظرف چند روز کاری پاسخی ازطریق ایمیل دریافت خواهید کرد. لطفاً برای برطرف کردن این خطا، از کلید میانای برنامه‌سازی کاربردی یا اطلاعات کاربری شناسه کارخواه استفاده کنید. راهنمای کلیدهای میانای برنامه‌سازی کاربردی و شناسه‌های کارخواه را ببینید.
UnauthorizedURLForClientIdMapError	این نشانی وب برای استفاده از «شناسه کارخواه Google Maps» ارائه‌شده مجاز نیست.	شناسه کارخواه موجود در بارگذاری متن نامعتبر یا منقضی‌شده است، یا نشانی فعلی بارگذاری Maps JavaScript API به فهرست نشانی‌های وب مجاز اضافه نشده است. ثبت نشانی‌های وب مجاز را ببینید.

کدهای خطای Maps JavaScript API

اگر در کنسول جاوا اسکریپت Chrome، کنسول وب Firefox، یا هر ابزار معادل دیگری در مرورگرهایتان خطایی پیدا کردید، برای یافتن توضیحات مربوط به کدهای خطا، جدول زیر را ببینید.

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

کد خطای توسعه‌دهنده	نوع	شرح
ApiNotActivatedMapError	خطا	‫Maps JavaScript API در پروژه API شما فعال نشده است. ممکن است لازم باشد Maps JavaScript API را در بخش «میاناهای برنامه‌سازی کاربردی» در کنسول Google Cloud فعال کنید. برای فعال کردن Maps JavaScript API برای پروژه‌تان، روی دکمه زیر کلیک کنید. آشنایی با نحوه کار
ApiTargetBlockedMapError	خطا	این کلید میانای برنامه‌سازی کاربردی برای استفاده از این سرویس یا میانای برنامه‌سازی کاربردی مجاز نیست. لطفاً تنظیمات محدودیت‌های API کلید API خود را در کنسول Google Cloud بررسی کنید تا مطمئن شوید که همه APIها و سرویس‌هایی که باید استفاده کنید به‌درستی در فهرست APIهای فعال‌شده مشخص شده‌اند. کلیدهای میانای برنامه‌سازی کاربردی را در کنسول Cloud ببینید. برای اطلاعات بیشتر، روال‌های مطلوب امنیتی API را ببینید.
DeletedApiProjectMapError	خطا	ممکن است پروژه API شما از کنسول Cloud حذف شده باشد. لطفاً پروژه‌ای را که برای آن کلید میانای API تولید کرده‌اید و در بارکننده میانای برنامه‌سازی کاربردی جاوا اسکریپت گنجانده شده است بررسی کنید. می‌توانید پروژه API جدیدی ایجاد کنید و کلید جدیدی در کنسول Cloud دریافت کنید. برای ایجاد پروژه جدید و دریافت کلید میانای API برای پروژه، روی دکمه زیر کلیک کنید. آشنایی با نحوه کار
ClientBillingNotEnabledMapError	خطا	صدور صورت‌حساب را در پروژه‌تان فعال نکرده‌اید. باید صدور صورت‌حساب را در پروژه Google Cloud مرتبط با این شناسه کارخواه فعال کنید.
BillingNotEnabledMapError	خطا	صدور صورت‌حساب را در پروژه‌تان فعال نکرده‌اید و این باعث بروز این خطا شده است. باید صدور صورت‌حساب را در پروژه Google Cloud فعال کنید. بیشتر بدانید
ExpiredKeyMapError	خطا	کلید میانای برنامه‌سازی کاربردی موجود در عنصر متن که میانای برنامه‌سازی کاربردی را بار می‌کند منقضی شده است یا توسط سیستم شناسایی نمی‌شود. اگر پس‌از ایجاد کلید میانای برنامه‌سازی کاربردی جدید، قبل‌از اینکه سیستم آن را شناسایی کند از آن استفاده کنید، ممکن است این خطا را دریافت کنید. چند دقیقه صبر کنید و دوباره امتحان کنید، یا شاید لازم باشد کلید میانای برنامه‌سازی کاربردی جدیدی در کنسول Cloud ایجاد کنید. برای دریافت کلید میانای API، روی دکمه زیر کلیک کنید. شروع به کار
InvalidAppCheckTokenMapError	خطا	کد «بررسی برنامه» ارائه‌شده نامعتبر یا منقضی شده است. این خطا فقط زمانی رخ می‌دهد که درستی‌سنجی «بررسی برنامه» درحال استفاده باشد. راهنمای درستی‌سنجی «بررسی برنامه» را ببینید.
InvalidClientIdMapError	خطا	برای افزایش امنیت و قابلیت اطمینان اصالت‌سنجی، شناسه‌های کارخواه Maps Platform از ۲۶ مه ۲۰۲۵ منسوخ شده‌اند و دیگر نمی‌توان از آن‌ها پس‌از ۳۱ مه ۲۰۲۶ استفاده کرد. به‌جای استفاده از شناسه کارخواه، باید از اعتبارنامه کلید میانای برنامه‌سازی کاربردی برای اصالت‌سنجی ترافیک سرویس Google Maps API استفاده کنید. برای اطلاعات بیشتر، به راهنمای انتقال شناسه مشتری مراجعه کنید. مراحل ذکرشده در راهنما را برای بازیابی موقت شناسه کارخواه دنبال کنید.
InvalidKeyMapError	خطا	کلید میانای برنامه‌سازی کاربردی موجود در عنصر متن که میانای برنامه‌سازی کاربردی را بار می‌کند پیدا نشد. لطفاً مطمئن شوید که از کلید میانای API درست استفاده می‌کنید. می‌توانید کلید میانای API جدیدی در کنسول Cloud ایجاد کنید. برای دریافت کلید میانای API، روی دکمه زیر کلیک کنید. شروع به کار
MalformedCredentialsMapError	خطا	برنامه شما از طرح‌واره URI پشتیبانی‌نشده‌ای استفاده می‌کند. تأیید کنید که برنامه از قالب URI معتبر همان‌گونه که در RFC 3986 تعریف شده است استفاده می‌کند.
MissingKeyMapError	خطا	عنصر متن که API را بار می‌کند فاقد پارامتر اصالت‌سنجی الزامی است. اگر از Maps JavaScript API استفاده می‌کنید، باید از پارامتر key با کلید API معتبر استفاده کنید. برای اطلاعات بیشتر، به شروع به کار با Google Maps Platform مراجعه کنید. اگر از شناسه کارخواه استفاده می‌کنید، باید از پارامتر client با شناسه کارخواه خود یا پارامتر key با کلید API معتبر استفاده کنید. برای اطلاعات بیشتر، راهنمای کلیدهای API و شناسه‌های مشتری را ببینید. اگر مالک وب‌سایت نیستید، هیچ اقدامی برای رفع این خطا نمی‌توانید انجام دهید. بااین‌حال، درصورت امکان بهتر است به مالک سایت اطلاع دهید.
ProjectDeniedMapError	خطا	درخواستتان تکمیل نشده است. شاید بتوانید جزئیات بیشتری درباره این خطا در کنسول Cloud پیدا کنید. کنسول Cloud را ببینید.
RefererDeniedMapError	خطا	برنامه‌تان به‌دلیل عدم رعایت «شرایط خدمات Google Maps Platform» مسدود شد. پیش‌از این، چند اعلان ایمیلی برایتان ارسال شده بود. برای پژوهش‌خواهی کردن درباره مسدود شدن و بازبینی پیاده‌سازی‌تان، فرم پژوهش‌خواهی شرایط خدمات «پلاتفرم Google Maps» را تکمیل کنید. ظرف چند روز کاری پاسخی ازطریق ایمیل دریافت خواهید کرد.
RefererNotAllowedMapError	خطا	نشانی وب فعلی که Maps JavaScript API را بار می‌کند به فهرست ارجاع‌دهنده‌های مجاز اضافه نشده است. لطفاً تنظیمات ارجاع‌دهنده کلید میانای برنامه‌سازی کاربردی خود را در کنسول Cloud بررسی کنید. به Maps JavaScript API و دریافت کلید میانای برنامه‌سازی کاربردی مراجعه کنید.
OverQuotaMapError	خطا	تعداد درخواست‌ها از حد استفاده برای Maps JavaScript API فراتر رفته است. درخواست‌های برنامه‌تان در بازنشانی سهمیه روزانه بعدی دوباره کار خواهد کرد. اگر مالک وب‌سایت نیستید، هیچ اقدامی برای رفع این خطا نمی‌توانید انجام دهید. بااین‌حال، درصورت امکان بهتر است به مالک سایت اطلاع دهید. برای جزئیات بیشتر، راهنمای حدود استفاده را ببینید. این صفحه همچنین توضیح می‌دهد که چگونه می‌توانید حد استفاده بالاتری دریافت کنید.
ApiProjectMapError	خطا	کلید میانای API ارائه‌شده یا پروژه میانای API مرتبط با آن حل‌وفصل نشد. این خطا ممکن است موقتی باشد. اگر این پیام خطا برطرف نشد، ممکن است لازم باشد کلید میانای برنامه‌سازی کاربردی جدیدی دریافت کنید یا پروژه میانای برنامه‌سازی کاربردی جدیدی ایجاد کنید. برای اطلاعات بیشتر، به شروع به کار با Google Maps Platform مراجعه کنید.
ClientIdLooksLikeCryptoKey	هشدار	ممکن است کلید رمزنگاری‌شده‌ای را در پارامتر client ارائه کرده باشید. لطفاً شناسه کارخواهتان را به‌عنوان پارامتر client مشخص کنید. نیازی نیست از کلید رمزنگاری‌شده برای Maps JavaScript API استفاده کنید. راهنمای شناسه‌های کارخواه را ببینید.
ClientIdLooksLikeKey	هشدار	ممکن است کلید میانای API را در پارامتر client ارائه کرده باشید. لطفاً شناسه مشتری‌تان را به‌عنوان پارامتر client مشخص کنید، یا به‌جای پارامتر client، از پارامتر key با کلید میانای برنامه‌سازی کاربردی معتبر استفاده کنید. راهنمای کلیدهای میانای برنامه‌سازی کاربردی و شناسه‌های کارخواه را ببینید.
InvalidChannel	هشدار	ممکن است پارامتر channel نامعتبری ارائه کرده باشید. کانال باید یک رشته الفباعددی ASCII باشد که می‌تواند شامل نقطه (.)، زیرخط (_) و خط تیره (-) باشد. لطفاً مطمئن شوید که پارامتر channel معتبری را مشخص می‌کنید. گزارش‌دهی | Google Maps Platform را ببینید.
InvalidClientId	هشدار	به‌نظر نمی‌رسد پارامتر client حاوی شناسه مشتری صحیح باشد. شناسه مشتری باید با «gme-» شروع شود. راهنمای کلیدهای میانای برنامه‌سازی کاربردی و شناسه‌های کارخواه را ببینید.
InvalidKey	هشدار	کلید میانای برنامه‌سازی کاربردی موجود در عنصر متن که میانای برنامه‌سازی کاربردی را بار می‌کند درست به‌نظر نمی‌رسد. لطفاً مطمئن شوید که از کلید میانای API درست استفاده می‌کنید. می‌توانید کلید میانای برنامه‌سازی کاربردی جدیدی در کنسول Cloud ایجاد کنید. برای دریافت کلید میانای API، روی دکمه زیر کلیک کنید. شروع به کار
InvalidVersion	هشدار	ممکن است شماره نسخه نادرستی را در عنصر دستورگان خود ارائه کرده باشید. لطفاً مطمئن شوید که از شماره نسخه صحیح استفاده می‌کنید. نسخه‌بندی | Google Maps JavaScript API را ببینید.
KeyLooksLikeClientId	هشدار	ممکن است شناسه کارخواه را به‌عنوان پارامتر key ارائه کرده باشید. لطفاً شناسه مشتری‌تان را به‌جای پارامتر key به‌عنوان پارامتر client مشخص کنید، یا از پارامتر key با کلید میانای برنامه‌سازی کاربردی معتبر استفاده کنید. راهنمای کلیدهای میانای برنامه‌سازی کاربردی و شناسه‌های کارخواه را ببینید.
KeyLooksLikeCryptoKey	هشدار	ممکن است کلید رمزنگاری‌شده یا رمز امضا را به‌عنوان پارامتر key ارائه کرده باشید. لطفاً شناسه مشتری‌تان را به‌عنوان پارامتر client مشخص کنید، و پارامتر key را از عنصر اسکریپتتان بردارید. کلید رمزنگاری‌شده برای Maps JavaScript API لازم نیست. یا می‌توانید کلید میانای برنامه‌سازی کاربردی را در کنسول Cloud دریافت کنید و از پارامتر key استفاده کنید. راهنمای مشخص کردن شناسه کارخواه هنگام بار کردن API را ببینید.
KeyLooksLikeProjectNumber	هشدار	ممکن است شماره پروژه را به‌عنوان پارامتر key ارائه کرده باشید. لطفاً مطمئن شوید که از کلید میانای API درست استفاده می‌کنید. می‌توانید کلید میانای API جدیدی در کنسول Cloud ایجاد کنید. با نحوه دریافت کلید API آشنا شوید.
NoApiKeys	هشدار	عنصر دستورگانی که میانای برنامه‌سازی کاربردی را بار می‌کند کلید میانای برنامه‌سازی کاربردی ندارد. لطفاً مطمئن شوید کلید میانای API معتبری را به‌عنوان پارامتر key اضافه کرده‌اید. می‌توانید کلید میانای برنامه‌سازی کاربردی جدیدی در کنسول Cloud ایجاد کنید. برای دریافت کلید میانای برنامه‌سازی کاربردی، روی دکمه زیر کلیک کنید تا شروع کنید. شروع به کار اگر Maps JavaScript API را از مسیر منسوخ‌شده v2 بار می‌کنید، هشدار NoApiKeys را دریافت خواهید کرد، حتی اگر پارامتر key را مشخص کرده باشید. لطفاً راهنمای ارتقا از نسخه ۲ به نسخه ۳ را بررسی کنید و برنامه خود را به نسخه ۳ API جاوا اسکریپت Maps منتقل کنید.
RetiredVersion	هشدار	ممکن است نسخه‌ای قدیمی را در عنصر اسکریپت خود ارائه کرده باشید. لطفاً برنامه‌تان را به‌روز کنید تا از یکی از نسخه‌های دردسترس استفاده کنید. نسخه‌بندی | Google Maps JavaScript API را ببینید.
SensorNotRequired	هشدار	پارامتر sensor دیگر برای Maps JavaScript API لازم نیست. این کار مانع از عملکرد صحیح Maps JavaScript API نمی‌شود، اما توصیه می‌کنیم پارامتر sensor را از عنصر اسکریپت بردارید.
SignatureNotRequired	هشدار	پارامتر signature برای میانای برنامه‌سازی کاربردی جاوا اسکریپت در Maps لازم نیست. این کار مانع از عملکرد صحیح Maps JavaScript API نمی‌شود، اما ممکن است مخاطرات امنیتی ایجاد کند. لطفاً آن را از عنصر اسکریپت خود بردارید.
SignedInNotSupported	هشدار	پارامتر signed_in منسوخ شده است و در نسخه‌ای از Maps JavaScript API که استفاده می‌کنید پشتیبانی نمی‌شود. این کار مانع از عملکرد Maps JavaScript API نمی‌شود، اما اگر به ویژگی‌های ورود به سیستم متکی باشید، ممکن است رفتار برنامه‌تان تغییر کند.
UrlAuthenticationCommonError	خطا	خطایی رخ داده است که در دسته‌های دیگر این صفحه قرار نمی‌گیرد. ممکن است دلیل آن مشکلی موقت باشد. لطفاً پس‌از وقفه‌ای کوتاه، درخواست را دوباره امتحان کنید. اگر با این کار مشکل برطرف نشد، لطفاً راهنمای توسعه‌دهنده را مرور کنید تا مطمئن شوید درخواست قالب مناسبی دارد.

بررسی خطاها در مرورگر

‫Maps JavaScript API پیام‌های خطا را در window.console می‌نویسد. این بخش توضیح می‌دهد که چگونه می‌توانید خروجی window.console را در Google Chrome بررسی کنید. اگر از مرورگر دیگری استفاده می‌کنید، اسناد توسعه‌دهنده مرورگرتان را بررسی کنید. برای اطلاع شما، این فهرست ابزارهایی برای بررسی خروجی window.console در برخی مرورگرهای دیگر است.

• کنسول وب برای Firefox.
• اشکال‌زدایی از راه دور برای Android.
• Web Inspector برای iOS.

در Chrome، می‌توانید از کنسول جاوا اسکریپت برای بررسی برونداد window.console به‌صورت زیر استفاده کنید.

1. برای باز کردن «ابزارهای توسعه‌دهندگان»، نماد منو > ابزارهای بیشتر > ابزارهای توسعه‌دهندگان را انتخاب کنید.
2. برای باز کردن «کنسول جاوا اسکریپت»، کلید ESC را در صفحه‌کلید فشار دهید. کلید ESC «کنسول جاوا اسکریپت» را روشن/خاموش می‌کند. اگر کنسول را ببندید، برای باز کردن آن، کلید ESC را دوباره فشار دهید.

اگر هنگام بار کردن Maps JavaScript API خطا یا هشداری رخ دهد، به‌صورت یک یا چند خط در کنسول نشان داده می‌شود. پیام خطا یا هشدار قالب زیر را دارد:

Google Maps API error: [ERROR CODE] [Link to API document]
یا
Google Maps API warning: [ERROR CODE] [Link to API document]

می‌توانید جدول کدهای خطا را در بالا بررسی کنید تا کد خطا را در پیام خطا پیدا کنید. همچنین می‌توانید جزئیات مربوط به پیام خطا را در سند میانای برنامه‌سازی کاربردی که از پیام پیوند داده شده است پیدا کنید.

توجه: می‌توانید خطاهای اصالت‌سنجی را به‌صورت برنامه‌نویسی‌شده گوش دهید.

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

مطمئن شوید که نسخه مرورگری که استفاده می‌کنید توسط میانای برنامه‌سازی کاربردی جاوا اسکریپت در Maps پشتیبانی می‌شود.

اگر درحال توسعه برنامه میزکار Windows هستید که در «وب‌نما» اجرا می‌شود، مطمئن شوید که از WebView2 مبتنی بر Edge استفاده می‌کنید. نسخه‌های قبلی WebView، براساس Internet Explorer، دیگر پشتیبانی نمی‌شوند.

اگر کدتان هنوز کار نمی‌کند

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

• غلط املایی را بررسی کنید. به‌خاطر داشته باشید که جاوا اسکریپت زبانی حروف‌حساس است.
• موارد پایه را بررسی کنید - برخی‌از رایج‌ترین مشکلات در ایجاد نقشه اولیه رخ می‌دهد. برای مثال:
  • تأیید کنید که ویژگی‌های zoom و center را در گزینه‌های نقشه مشخص کرده‌اید.
  • مطمئن شوید که عنصر div را که نقشه در آن روی صفحه ظاهر می‌شود اعلام کرده‌اید.
  • مطمئن شوید که عنصر div برای نقشه دارای ارتفاع باشد. به‌طور پیش‌فرض، عناصر div با ارتفاع ۰ ایجاد می‌شوند و بنابراین نامرئی هستند.
  برای پیاده‌سازی مرجع به نمونه‌های ما مراجعه کنید.
• برای کمک به شناسایی مشکلات، از اشکال‌زدای جاوا اسکریپت استفاده کنید، مثل اشکال‌زدایی که در ابزارهای توسعه‌دهنده Chrome دردسترس است. با جستجوی خطاها در کنسول جاوا اسکریپت شروع کنید.
• سؤالات را در Stack Overflow پست کنید. دستورالعمل‌های مربوط به نحوه پست کردن سؤالات عالی در صفحه پشتیبانی دردسترس است.