تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
أخطاء مفتاح واجهة برمجة التطبيقات والفوترة
في ظروف معيّنة، قد يتم عرض خريطة مظلمة أو صورة "سلبية" من "التجوّل الافتراضي"،
عليها علامة مائية تتضمّن النص "لأغراض التطوير فقط".
يشير هذا السلوك عادةً إلى مشاكل في مفتاح واجهة برمجة التطبيقات أو الفوترة.
لاستخدام منتجات Google Maps Platform، يجب تفعيل ميزة الفوترة في حسابك،
ويجب أن تتضمّن جميع الطلبات مفتاح واجهة برمجة تطبيقات صالحًا. ستساعدك الخطوات التالية في تحديد المشاكل وحلّها:
هل تستخدم مفتاح واجهة برمجة التطبيقات؟
ليس لدي جواب أكيد. كيف يمكنني التحقّق مما إذا كنت أستخدم مفتاح واجهة برمجة التطبيقات؟
يتم تمرير مفتاح واجهة برمجة التطبيقات كمَعلمة key في عنوان URL المستخدَم لتحميل
Google Maps JavaScript API. في ما يلي بعض الخيارات للتحقّق مما إذا كنت تستخدم مفتاح واجهة برمجة التطبيقات:
استخدِم إضافة
Google Maps Platform API Checker في Chrome. يتيح لك ذلك تحديد ما إذا كان
موقعك الإلكتروني ينفِّذ واجهات برمجة تطبيقات "خرائط Google" المرخّصة من Google بشكلٍ سليم.
إذا كنت تستخدم مكتبة أو مكوّنًا إضافيًا لتحميل واجهة برمجة التطبيقات JavaScript خرائط Google،
تحقَّق من إعدادات هذه المكتبة وابحث عن خيار مفتاح واجهة برمجة التطبيقات.
تحقّق من الأخطاء في المتصفّح.
إذا ظهرت لك الرسائل التالية، يعني ذلك أنّك لا تستخدم مفتاح واجهة برمجة التطبيقات بشكل صحيح:
إذا كان بإمكانك الوصول إلى رمز المصدر لتطبيقك، ابحث عن علامة
<script> التي تُستخدَم لتحميل واجهة برمجة التطبيقات JavaScript لخرائط Google.
عند تحميل واجهة برمجة تطبيقات JavaScript لخرائط Google، استبدِل YOUR_API_KEY
في الرمز البرمجي أدناه بمفتاح واجهة برمجة التطبيقات.
تحقّق من عدد زيارات الشبكة التي يجريها موقعك الإلكتروني في المتصفّح.
في Chrome، يمكن الاطّلاع على ذلك باستخدام علامة التبويب
الشبكة في DevTools.
ستظهر لك هنا طلبات الشبكة التي يقدّمها موقعك الإلكتروني. ستتم إضافة الطلبات التي يتم إجراؤها باستخدام
Maps JavaScript API ضمن المسار maps/api/js.
يمكنك هنا التأكّد مما إذا كانت الطلبات تستخدِم المَعلمة key.
قد يكون من المفيد
فلترة حركة بيانات الشبكة حسب maps/api/js عند عرض علامة التبويب الشبكة.
لا، لا أستخدم مفتاح واجهة برمجة التطبيقات.
للحصول على مفتاح واجهة برمجة التطبيقات، انقر على الزر أدناه. إذا لم يظهر لك الإعداد الإرشادي، اتّبِع
التعليمات الكاملة في مقالة البدء باستخدام Google Maps
Platform.
البدء
نعم، أستخدم مفتاح واجهة برمجة التطبيقات.
رائع! لننتقل إلى الخطوة التالية ونتحقق مما إذا كان حساب فوترة مرتبطًا بمشروعك.
هل تم إرفاق حساب فوترة بمشروعك؟
ليس لدي جواب أكيد. كيف يمكنني التحقّق مما إذا كان حساب الفوترة مرتبطًا بمشروعي؟
انتقِل إلى
صفحة "الفوترة" في وحدة تحكّم Google Cloud واختَر المشروع الذي تم إنشاء مفتاح واجهة برمجة التطبيقات بموجبه.
للتأكّد من أنّ المفتاح مرتبط بالمشروع:
انتقِل إلى قسم بيانات الاعتماد، والذي يمكن الوصول إليه من الشريط الجانبي الأيمن ضمن
منصة خرائط Google > بيانات الاعتماد.
تأكَّد من أنّ مفتاح واجهة برمجة التطبيقات الذي تستخدمه حاليًا على موقعك الإلكتروني مُدرَج.
إذا لم يكن الأمر كذلك، يمكنك التبديل إلى مشروع مختلف والتحقّق من بيانات الاعتماد هناك.
إذا تعذّر عليك العثور على مشروع مفتاح واجهة برمجة التطبيقات، قد يعني ذلك أنّك فقدت إمكانية الوصول إلى هذا المشروع.
اطلب المساعدة من مستخدمين آخرين في مؤسستك. إذا تعذّر العثور على المشروع الأصلي، عليك إجراء ما يلي:
أنشئ مشروعًا جديدًا. يمكن إجراء ذلك من خلال اختيار مشروع جديد
من قائمة المشاريع، أو من خلال اختيار إنشاء مشروع من
صفحة "مدير الموارد".
أنشئ مفتاح واجهة برمجة تطبيقات جديدًا. ويمكن إجراء ذلك في صفحة بيانات الاعتماد.
بعد ذلك، انقر على إنشاء بيانات اعتماد، ثم اختَر مفتاح واجهة برمجة التطبيقات.
بعد تحديد موقع مشروعك في وحدة تحكّم Cloud،
تحقّق مما إذا كان حساب فوترة مرفقًا من خلال الانتقال إلى قسم الفوترة في القائمة على يمين الصفحة.
هل تم تجاوز حدّ يومي ذاتيًا تم فرضه على واجهة برمجة التطبيقات؟
إذا كنت قد حدّدت حدًا يوميًا لأيّ من واجهات برمجة التطبيقات، وهو إجراء شائع لمنع الزيادات غير المتوقّعة،
يمكنك حلّ هذه المشكلة من خلال زيادة الحدّ اليومي.
اختَر واجهة برمجة تطبيقات من القائمة، ثم انقر على علامة التبويب الحصص.
هل يتضمّن مفتاح واجهة برمجة التطبيقات قيودًا على عناوين IP؟
لا يمكن استخدام مفاتيح واجهة برمجة التطبيقات التي تتضمّن قيودًا على عناوين IP إلا مع خدمات الويب التي
تكون مخصّصة للاستخدام من جهة الخادم (مثل
Geocoding API
وWeb Service APIs الأخرى).
توفّر معظم خدمات الويب هذه خدمات مماثلة ضمن واجهة برمجة التطبيقات Maps JavaScript API (على سبيل المثال، اطّلِع على
خدمة ترميز المواقع الجغرافية).
لاستخدام خدمات جهة العميل في واجهة برمجة التطبيقات JavaScript API، عليك إنشاء مفتاح واجهة برمجة تطبيقات منفصل يمكن
تأمينه من خلال تقييد مُحيلي HTTP (اطّلِع على
الحصول على مفتاح واجهة برمجة تطبيقات وإضافته وحظره).
إذا لم يعمل الرمز:
لمساعدتك في إعداد رمز الخرائط وتشغيله، يوضّح "براندان كينيدي" و"مانو ماركس" في هذا الفيديو
بعض الأخطاء الشائعة وكيفية حلّها.
ابحث عن الأخطاء الإملائية. تذكَّر أنّ JavaScript هي لغة
حسّاسة لحالة الأحرف.
التحقّق من الأساسيات: تحدث بعض المشاكل الأكثر شيوعًا عند
إنشاء الخريطة الأولية. على سبيل المثال:
تأكَّد من تحديد السمتَين zoom
وcenter في خيارات
الخريطة.
تأكَّد من أنّك قد أعلنت عن عنصر div الذي ستظهر فيه الخريطة
على الشاشة.
تأكَّد من أنّ عنصر div للخريطة له ارتفاع. يتم تلقائيًا إنشاء عناصر DIV
بارتفاع 0، وبالتالي فهي
غير مرئية.
استخدِم أداة تصحيح أخطاء JavaScript للمساعدة في تحديد المشاكل، مثل الأداة المتاحة
في أدوات
مطوّري برامج Chrome. ابدأ بالبحث عن الأخطاء في وحدة تحكّم JavaScript.
يمكنك نشر الأسئلة على Stack
Overflow. تتوفّر إرشادات حول كيفية نشر أسئلة رائعة في
صفحة الدعم.
تاريخ التعديل الأخير: 2025-08-31 (حسب التوقيت العالمي المتفَّق عليه)
[null,null,["تاريخ التعديل الأخير: 2025-08-31 (حسب التوقيت العالمي المتفَّق عليه)"],[[["\u003cp\u003eTo use the Google Maps JavaScript API, you must include an API key and enable billing for your project.\u003c/p\u003e\n"],["\u003cp\u003eIf you see a darkened map or a negative Street View image watermarked with "for development purposes only", you might have an issue with your API key or billing.\u003c/p\u003e\n"],["\u003cp\u003eTroubleshooting steps involve verifying your API key implementation, checking billing account attachment, ensuring billing method validity, and reviewing daily usage limits and IP restrictions.\u003c/p\u003e\n"],["\u003cp\u003eThis page offers solutions to common billing and API errors, and links to resources for further assistance.\u003c/p\u003e\n"]]],["Using the Maps JavaScript API requires a valid API key and enabled billing. Issues like a darkened map typically stem from these. Verify API key usage via browser checks, source code, or network traffic. Ensure the project linked to your API key has an active billing account. Check for invalid payment methods or exceeded API daily limits. If restricted by IP address, create a key with HTTP referrers. Troubleshoot by checking for typos, verifying map element properties, or using a JavaScript debugger.\n"],null,["# Troubleshooting\n\n| **Reminder:** To use the Maps JavaScript API:\n|\n| - All Maps JavaScript API requests must include an API key; we no longer support keyless access.\n| - You must [enable billing](https://console.cloud.google.com/project/_/billing/enable?utm_source=Docs_BillingNudge) on each of your projects.\n\n### API Key and Billing Errors\n\n\nUnder certain circumstances, a darkened map, or 'negative' Street View image,\nwatermarked with the text \"for development purposes only\", may be displayed.\nThis behavior typically indicates issues with either an API key or billing.\nIn order to use Google Maps Platform products, billing must be enabled on your account,\nand all requests must include a valid API key. The following flow will help troubleshoot this:\n\n#### Are you using an API key?\n\n#### I'm not sure. How can I check if I am using an API key?\n\nAn API key is passed as the `key` parameter in the URL that is used to load the\nMaps JavaScript API. Here are a few options to check if you are using an API key:\n\n- Use the [Google Maps Platform API Checker](https://chrome.google.com/webstore/detail/google-maps-platform-api/mlikepnkghhlnkgeejmlkfeheihlehne) Chrome extension. This allows you to determine if your website is properly implementing Google's licensed Maps APIs.\n- If you are using a library or plugin to load the Maps JavaScript API, check the settings for that library and look for an API key option.\n- Check [errors in your browser](/maps/documentation/javascript/error-messages#checking-errors). If you see the following messages, you are not using your API key correctly:\n - Google Maps JavaScript API warning: [NoApiKeys](/maps/documentation/javascript/error-messages#no-api-keys)\n - Google Maps JavaScript API error: [MissingKeyMapError](/maps/documentation/javascript/error-messages#missing-key-map-error)\n\n#### For web developers:\n\n- If you have access to the source code of your application, look for the `\u003cscript\u003e` tag which is used to load the Maps JavaScript API. When loading the Maps JavaScript API, substitute `YOUR_API_KEY` in the code below with your API key. \n\n ```html\n \u003cscript async defer\n src=\"https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap\"\u003e\n \u003c/script\u003e\n ```\n- Check the network traffic generated by your website in the browser. In Chrome, this can be viewed using the [DevTools](/web/tools/chrome-devtools) **Network** tab. Here you will see the network requests made by your website. Requests made using the Maps JavaScript API will be under the path `maps/api/js`. Here you can confirm if the requests are using the `key` parameter. It may be helpful to [filter your network traffic](/web/tools/chrome-devtools/console#filtering_the_console_output) by `maps/api/js` when viewing the **Network** tab.\n\n#### No, I am not using an API key.\n\nTo get an API key, click the button below. If you do not see a guided setup, follow the\nfull instructions at [Get Started with Google Maps\nPlatform](/maps/get-started#procedures).\n\n\n[Get Started](/maps/get-started)\n\n#### Yes, I am using an API key.\n\nGreat! Let's move on and check if a billing account is attached to your project.\n\n#### Is a billing account attached to your project?\n\n#### I'm not sure. How can I check if billing account is attached to my project?\n\nGo to the [Billing page](https://console.cloud.google.com/project/_/billing/enable?utm_source=Docs_BillingNudge) in the Google Cloud console and select the project under which your API key was created.\nTo confirm the key is associated with the project:\n\n1. Go to the **Credentials** section, which can be accessed from the left side bar under **Google Maps Platform \\\u003e Credentials**.\n2. Check that the API key you currently use on your website is listed. If that's not the case, switch to a different project, and check the credentials there.\n3. If you cannot locate the project for your API key, you may have lost access to this project. Ask others in your organization for help. If the original project cannot be located, you should:\n 1. Create a new project. This can be done by selecting **New Project** from the projects list, or by selecting **Create Project** via the [Resource Manager page](https://console.cloud.google.com/cloud-resource-manager).\n 2. Create a new API key. This can be done on the **Credentials** page. Once there click **Create credentials** and then select **API key**.\n\n\nOnce you have located your project in the Cloud console,\ncheck if a billing account is attached by navigating to the [Billing](https://console.cloud.google.com/project/_/billing) section in the left side menu.\n\n#### No, a billing account is not attached to my project.\n\nGo to the [Enable Billing](https://console.cloud.google.com/project/_/billing/enable?utm_source=Docs_BillingNudge) page in the Cloud console\nand add a billing account to your project. For additional information, see\n[Get Started with Google Maps Platform](/maps/get-started).\n\n#### Yes, a billing account is attached to my project.\n\nGreat! Let's make sure the provided billing method is valid.\n\n#### Is the provided billing method no longer valid (for example an expired credit card)?\n\nYou [can add, remove, or update a payment method](https://cloud.google.com/billing/docs/how-to/payment-methods) in the Cloud console.\n\n#### Is there an exceeded self-imposed daily limit on the API?\n\nIf you have set a daily limit on any of your APIs, which is common to prevent unexpected increases,\nyou can resolve this by [increasing your daily limit](/maps/faq#usage_cap).\n\nYou can check your daily limits by going to the\n[APIs \\& Services Dashboard](https://console.cloud.google.com/project/_/apiui/apis/enabled?utm_source=Docs_EnabledAPIsView) in the\nCloud console. Once there:\n\n1. Select a project if prompted.\n2. Select an API from the list, then click the **Quotas** tab.\n\n#### Does your API key have an IP addresses restriction?\n\nAPI keys with an **IP addresses** restriction can only be used with web services that are\nintended for use from the server side (such as the\n[Geocoding API](/maps/documentation/geocoding/start)\nand other [Web Service APIs](/maps/apis-by-platform)).\nMost of these web services have equivalent services within the Maps JavaScript API (for example, see the\n[Geocoding Service](/maps/documentation/javascript/geocoding)).\nTo use the Maps JavaScript API client side services, you will need to create a separate API key which\ncan be secured with an **HTTP referrers** restriction (see\n[Get, add, and restrict an API key](/maps/get-started#api-key)).\n\n### If your code isn't working:\n\nTo help you get your maps code up and running, Brendan Kenny and Mano Marks point out\nsome common mistakes and how to fix them in this video. \n\n- Look for typos. Remember that JavaScript is a case-sensitive language.\n- Check the basics - some of the most common problems occur with the initial map creation. Such as:\n - Confirm that you've specified the `zoom` and `center` properties in your map options.\n - Ensure that you have declared a div element in which the map will appear on the screen.\n - Ensure that the div element for the map has a height. By default, div elements are created with a height of 0, and are therefore invisible.\n\n Refer to our examples for a [reference\n implementation](/maps/documentation/javascript/examples/map-simple).\n- Use a JavaScript debugger to help identify problems, like the one available in the [Chrome\n Developer Tools](/chrome-developer-tools/docs/javascript-debugging). Start by looking in the JavaScript console for errors.\n- Post questions to [Stack\n Overflow](https://stackoverflow.com/questions/ask?tags=google-maps-api-3,google-maps). Guidelines on how to post great questions are available on the [Support](/maps/support) page."]]
