특정 상황에서는 '개발 전용'이라는 워터마크가 표시된 어두운 지도 또는 '음화' 스트리트 뷰 이미지가 표시될 수도 있습니다.
이 동작은 일반적으로 API 키 또는 청구 관련 문제를 나타냅니다.
Google Maps Platform 제품을 사용하려면 계정에서 결제를 사용 설정해야 하고 모든 요청에 유효한 API 키를 포함해야 합니다. 다음 단계에 따라 이 문제를 해결할 수 있습니다.
API 키를 사용하고 있나요?
잘 모르겠습니다. API 키를 사용 중인지 어떻게 확인할 수 있나요?
API 키는 Maps JavaScript API를 로드하는 데 사용되는 URL의 key 매개변수로 전달됩니다. 다음 방법으로 API 키를 사용하고 있는지 확인할 수 있습니다.
브라우저에서 웹사이트가 생성한 네트워크 트래픽을 확인합니다.
Chrome에서는 DevTools네트워크 탭을 사용하여 네트워크 트래픽을 확인할 수 있습니다.
여기에 웹사이트에서 요청한 네트워크 요청이 표시됩니다. Maps JavaScript API를 사용하여 한 요청은 maps/api/js 경로 아래 표시됩니다.
여기에서는 요청이 key 매개변수를 사용하는지 확인할 수 있습니다.
네트워크 탭을 볼 때 maps/api/js를 기준으로 네트워크 트래픽을 필터링하면 도움이 될 수도 있습니다.
예기치 않은 사용량 증가를 방지하기 위해 API에 일일 한도를 설정한 경우 일일 한도를 늘려 이 문제를 해결할 수 있습니다.
Cloud 콘솔의 API 및 서비스 대시보드로 이동하여 일일 한도를 확인할 수 있습니다. 이 대시보드로 이동한 후 다음 단계를 따르세요.
메시지가 표시되면 프로젝트를 선택합니다.
목록에서 API를 선택한 다음 할당량 탭을 클릭합니다.
API 키에 IP 주소 제한이 있나요?
IP 주소 제한이 있는 API 키는 서버 측에서 사용할 웹 서비스(예: Geocoding API 및 기타 Web Service API)와 함께만 사용할 수 있습니다.
이러한 웹 서비스 대부분에는 Maps JavaScript API 내에 동일한 서비스가 있습니다(예: 지오코딩 서비스 참고).
Maps JavaScript API 클라이언트 측 서비스를 사용하려면
HTTP 리퍼러 제한으로 보호할 수 있는 별도의 API 키를 만들어야 합니다
(API 키 가져오기, 추가하기, 제한하기 참고).
코드가 작동하지 않는 경우:
지도 코드를 작성하고 실행하는 데 도움이 되도록 Brendan Kenny와 Mano Marks가 다음 동영상에서 일반적인 실수 및 해결 방법을 알려줍니다.
오타를 찾습니다. JavaScript는 대소문자를 구분하는 언어입니다.
기본 사항을 확인합니다. 처음 지도를 만들 때 가장 일반적인 문제가 발생하는 경우가 있습니다. 예를 들면 다음과 같습니다.
지도 옵션에서 zoom 및 center 속성을 지정했는지 확인합니다.
화면에 지도를 표시할 div 요소를 선언했는지 확인합니다.
지도의 div 요소에 높이가 있는지 확인합니다. 기본적으로 div 요소는 높이가 0으로 생성되므로 표시되지 않습니다.
[null,null,["최종 업데이트: 2025-08-31(UTC)"],[[["\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."]]
