모든 준비를 마쳤습니다!

개발을 시작하려면 개발자 문서로 이동하세요.

Google Maps JavaScript API 활성화

개발을 시작하기 위해 Google Developers Console에서 우선적으로 해야 할 일을 몇 가지 소개하겠습니다.

  1. 프로젝트 생성 또는 선택
  2. Google Maps JavaScript API 및 관련 서비스 활성화
  3. 적합한 키 생성
계속

시작하기

대상

이 문서는 JavaScript 프로그래밍 및 객체 지향 프로그래밍 개념에 익숙한 사람들을 대상으로 작성되었습니다. 또한,사용자의 관점에서 Google 지도에도 익숙해야 합니다. 웹에서 이용할 수 있는 많은 JavaScript 튜토리얼이 있습니다.

본 문서는Google Maps JavaScript API로 신속히 애플리케이션 탐색과 개발을 시작할 수 있도록 구성되었습니다. Google Maps JavaScript API 참조도 게시되어 있습니다.

Hello, World

Google Maps JavaScript API에 대해 배우는 가장 쉬운 방법은 간단한 예시를 보는 것입니다. 다음 웹 페이지는 오스트레일리아 뉴사우스 웨일즈에 있는 시드니를 중심으로 하는 지도를 표시합니다.

var map;
function initMap() {
  map = new google.maps.Map(document.getElementById('map'), {
    center: {lat: -34.397, lng: 150.644},
    zoom: 8
  });
}
<div id="map"></div>
/* Always set the map height explicitly to define the size of the div
 * element that contains the map. */
#map {
  height: 100%;
}
/* Optional: Makes the sample page fill the window. */
html, body {
  height: 100%;
  margin: 0;
  padding: 0;
}
<!-- Replace the value of the key parameter with your own API key. -->
<script src="https://maps.googleapis.com/maps/api/js?key=AIzaSyCkUOdZ5y7hMm0yrcCQoCvLwzdM6M8s5qk&callback=initMap" async defer></script>
<!DOCTYPE html>
<html>
  <head>
    <title>Simple Map</title>
    <meta name="viewport" content="initial-scale=1.0">
    <meta charset="utf-8">
    <style>
      /* Always set the map height explicitly to define the size of the div
       * element that contains the map. */
      #map {
        height: 100%;
      }
      /* Optional: Makes the sample page fill the window. */
      html, body {
        height: 100%;
        margin: 0;
        padding: 0;
      }
    </style>
  </head>
  <body>
    <div id="map"></div>
    <script>
      var map;
      function initMap() {
        map = new google.maps.Map(document.getElementById('map'), {
          center: {lat: -34.397, lng: 150.644},
          zoom: 8
        });
      }
    </script>
    <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap"
    async defer></script>
  </body>
</html>

예시 보기(map-simple.html)

간단한 예시지만 유의해야 몇 가지 사항이 있습니다.

  1. <!DOCTYPE html> 선언을 사용하여 애플리케이션을 HTML5로 선언합니다.
  2. 지도를 고정하기 위해 "map"이라는 div 요소를 생성합니다.
  3. div에서 지도를 생성하는 JavaScript 함수를 정의합니다.
  4. script 태그를 사용하여 Maps JavaScript API를 로드합니다.

이러한 단계는 아래에 설명되어 있습니다.

HTML5로 애플리케이션 선언

웹 애플리케이션 내에 실제 DOCTYPE을 선언하는 것이 좋습니다. 이 예시에서는 아래와 같이 간단한 HTML5 DOCTYPE을 사용하여 애플리케이션을 HTMML5로 선언했습니다.

<!DOCTYPE html>

대부분 최신 브라우저는 "표준 모드"에서 이 DOCTYPE으로 선언된 콘텐츠를 렌더링합니다. 즉, 여러분의 애플리케이션은 브라우저 간 호환성이 강화되어야 합니다. 또한, DOCTYPE은 적절히 디그레이드되도록 설계되었습니다. Doctype을 이해하지 못하는 브라우저는 이를 무시하고 "쿼크 모드"를 사용하여 콘텐츠를 렌더링합니다.

쿼크 모드에서 작동하는 일부 CSS는 표준 모드에서 유효하지 않습니다. 특히, 모든 비율을 기반으로 하는 크기는 상위 블록 요소에서 상속해야 하며, 상위 요소가 크기를 지정하지 못하면 0 x 0 픽셀로 간주됩니다. 이러한 이유로 우리는 다음 <style> 선언을 포함합니다.

<style>
  #map {
    height: 100%;
  }
  html, body {
    height: 100%;
    margin: 0;
    padding: 0;
  }
</style>

이 CSS 선언은 지도 컨테이너 <div>(map ID 포함)가 HTML 본문 높이의 100%를 차지해야 한다는 것을 나타냅니다. <body><html>에서도 이 비율을 명시적으로 선언해야 합니다.

Google Maps JavaScript API 로드

Google Maps JavaScript API를 로드하려면 다음 예시와 같이 script 태그를 사용합니다.
    <script async defer
      src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap">
    </script>

script 태그에 포함된 URL은 Maps JavaScript API를 사용하는 데 필요한 모든 기호와 정의를 로드하는 JavaScript 파일의 위치입니다. 이 script 태그는 필수입니다.

async 특성을 사용하면 Maps JavaScript API가 로드되는 동안 브라우저가 나머지 웹사이트를 렌더링할 수 있습니다. API가 준비되면 callback 매개변수를 사용하여 지정된 함수를 호출합니다.

key 매개변수는 개발자 애플리케이션의 API 키를 포함합니다. 자세한 내용은 키 가져오기를 참조하세요.

참고: Google Maps API 프리미엄 플랜 고객은 API를 로드할 때 API 키 또는 유효한 클라이언트 ID를 사용할 수 있습니다. 자세한 내용은 프리미엄 플랜 고객의 인증 매개변수를 참조하세요.

HTTPS 또는 HTTP

우리는 웹에서의 보안을 상당히 중요하게 생각하며, 가능하면 HTTPS를 사용하도록 권장합니다. 웹을 더욱 안전하게 만들기 위한 노력의 일환으로 모든 Maps JavaScript API를 HTTPS를 통해 이용할 수 있게 했습니다. HTTPS 암호화를 사용하면 사이트가 더욱 안전해지고 스누핑이나 변조에 대한 저항력이 강화됩니다.

위에 제공된 <script> 태그를 사용하여 HTTPS를 통해 Maps JavaScript API를 로드하도록 권장합니다.

필요한 경우 http://maps.googleapis.com/ 또는 중국 사용자의 경우 http://maps.google.cn을 요청하여 HTTP를 통해 Maps JavaScript API를 로드할 수 있습니다.

라이브러리

URL을 통해 Maps JavaScript API를 로드할 때 libraries URL 매개변수를 사용하여 추가 라이브러리를 선택적으로 로드할 수 있습니다. 라이브러리는 코드로 구성된 모듈로, 메인 Maps JavaScript API에 추가 기능을 제공하지만 명시적으로 요청하지 않으면 로드되지 않습니다. 자세한 내용은 Maps JavaScript API 라이브러리를 참조하세요.

동기적으로 API 로드

Maps JavaScript API를 로드하는 script 태그에서 async 특성과 callback 매개변수를 생략할 수 있습니다. 그러면 API가 다운로드될 때까지 API 로드가 차단됩니다.

따라서 페이지 로드가 느려질 수 있습니다. 그러나 이는 API가 이미 로드되었다고 가정하고 후속 스크립트 태그를 작성할 수 있다는 의미입니다.

Map DOM 요소

<div id="map"></div>

웹 페이지에 지도를 표시하려면 표시할 자리를 예약해야 합니다. 일반적으로 이 작업은 div라는 요소를 생성하고 브라우저 문서 객체 모델(DOM)에서 이 요소에 대한 참조를 획득하는 방식으로 수행됩니다.

위의 예시에서 우리는 CSS를 사용하여 map div의 높이를 "100%"로 설정했습니다. 그러면 모바일 기기의 크기에 맞게 확장됩니다. 브라우저의 화면 크기와 여백에 따라 너비와 높이를 조절해야 할 수도 있습니다. 일반적으로 div는 포함된 요소에서 너비를 가져오며, 비어 있는 div는 대개 높이가 0입니다. 그러므로 <div>에서는 항상 높이를 명시적으로 설정해야 합니다.

지도 옵션

모든 지도에는 centerzoom이라는 두 가지 필수 옵션이 있습니다.

map = new google.maps.Map(document.getElementById('map'), {
  center: {lat: -34.397, lng: 150.644},
  zoom: 8
});

확대/축소 수준

지도를 표시하는 초기 해상도는 zoom 속성을 통해 설정됩니다. zoom이 0이면 완전히 축소된 지도이고, 확대/축소 수준이 높아질수록 더 높은 해상도로 화면이 확대됩니다. 확대/축소 수준을 정수로 지정합니다.

zoom: 8

지구 전체 지도를 단일 이미지로 제공하려면 거대한 지도나 해상도가 매우 낮은 작은 지도가 필요합니다. 따라서 Google 지도와 Maps JavaScript API 안의 지도 이미지는 지도 "타일"과 "확대/축소 수준"으로 나눠집니다. 낮은 확대/축소 수준에서는 작은 지도 타일 집합이 넓은 영역을 덮고, 높은 확대/축소 수준에서는 타일 해상도가 높아지고 더 작은 영역을 덮습니다. 다음 목록은 각 확대/축소 수준에서 기대할 수 있는 세밀한 정도를 보여줍니다.

  • 1: 세계
  • 5: 대륙
  • 10: 구/군/시
  • 15: 도로
  • 20: 건물

다음 세 이미지는 도쿄의 동일한 장소를 확대/축소 수준 0, 7, 18로 나타낸 것입니다.

현재 확대/축소 수준에 따라 Maps JavaScript API가 타일을 로드하는 방법에 대한 내용은 지도 유형 문서의 타일 좌표를 참조하세요.

지도 객체

map = new google.maps.Map(document.getElementById("map"), {...});

지도를 나타내는 JavaScript 클래스는 Map 클래스입니다. 이 클래스의 객체는 한 페이지에 하나의 지도를 정의합니다. (이 클래스의 인스턴스를 하나 이상 생성할 수 있습니다. 각 객체는 페이지에서 별개의 지도를 정의합니다.) JavaScript new 연산자를 사용하여 이 클래스의 새로운 인스턴스를 생성합니다.

새 지도 인스턴스를 생성할 때 페이지의 <div> HTML 요소를 지도의 컨테이너로 지정합니다. HTML 노드는 JavaScript document 객체의 하위 요소이고, 우리는 document.getElementById() 메서드를 통해 이 요소에 대한 참조를 획득합니다.

이 코드는 map 이라는 변수를 정의하고 이 변수를 새 Map 객체에 할당합니다. Map() 함수는 생성자로 알려져 있고, 그 정의는 아래와 같습니다.

생성자 설명
Map(mapDiv:Node, opts?:MapOptions ) 전달되는 모든 (선택적) 매개변수를 사용하여 주어진 HTML 컨테이너(일반적으로 DIV 요소) 내부에 새로운 지도를 생성합니다.

문제 해결

여러분의 지도 코드가 작동하도록 돕기 위해 이 동영상에서 Brendan KennyMano Marks가 몇 가지 흔히 저지르는 실수와 이를 해결하는 방법을 알려줍니다.

코드가 작동하지 않는 경우:

  • 오타를 찾습니다. JavaScript는 대소문자를 구분하는 언어입니다.
  • 기본 사항들을 확인합니다. 처음 지도를 생성할 때 가장 일반적인 문제가 많이 발생합니다. 예:
    • 지도 옵션에서 zoomcenter 속성을 지정했는지 확인합니다.
    • 화면에 지도를 표시할 div 요소를 선언했는지 확인합니다.
    • 지도의 div 요소에 높이가 있는지 확인합니다. 기본적으로, div 요소는 높이가 0으로 생성되므로 보이지 않습니다.
    참조 구현에 대한 예시를 참조하세요.
  • Chrome 개발자 도구 등에서 제공되는 JavaScript 디버거를 사용하여 문제를 식별할 수 있습니다. 먼저 JavaScript 콘솔에서 오류를 찾습니다.
  • Stack Overflow에 질문을 올립니다. 지원 페이지에서 좋은 질문을 게시하는 방법에 대한 지침이 제공됩니다.

다음에 대한 의견 보내기...

Google Maps JavaScript API
Google Maps JavaScript API
도움이 필요하시나요? 지원 페이지를 방문하세요.