모든 준비를 마쳤습니다!

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

Google Maps JavaScript API 활성화

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

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

마커

소개

마커는 지도에서 위치를 식별합니다. 기본적으로, 마커는 표준 이미지를 사용합니다. 마커가 사용자 지정 이미지를 표시할 수 있는데, 이러한 경우 대개 "아이콘"으로 불립니다. 마커와 아이콘은 Marker 유형의 객체입니다. 마커의 생성자 내에서 또는 마커에서 setIcon()을 호출하여 사용자 지정 아이콘을 설정할 수 있습니다. 아래에서 마커 이미지 사용자 지정에 대해 자세히 알아보세요.

넓게 보면 마커는 오버레이의 일종입니다. 다른 유형의 오버레이에 관한 내용은 지도에 그리기를 참조하세요.

마커는 상호작용이 가능하도록 설계되었습니다. 예를 들어, 마커는 기본적으로 'click' 이벤트를 수신하므로, 이벤트 리스너를 추가하여 사용자 지정 정보를 표시하는 정보 창을 열 수 있습니다. 마커의 draggable 속성을 true로 설정하여 사용자가 지도에서 마커를 이동하게 수 있게 할 수 있습니다. 드래그 가능한 마커에 대한 자세한 정보는 아래를 참조하세요.

마커 추가

google.maps.Marker 생성자는 단일 Marker options 객체 리터럴을 취하고, 마커의 초기 속성을 지정합니다.

다음 필드는 특히 중요하며, 주로 마커를 생성할 때 설정됩니다.

  • position(필수)은 마커의 처음 위치를 나타내는 LatLng를 지정합니다. LatLng지오코딩 서비스를 사용하여 검색할 수 있습니다.
  • map(선택 항목)은 마커를 배치할 Map을 지정합니다. 마커 생성 시에 지도를 지정하지 않으면 마커가 생성되지만 지도에 첨부(표시)되지 않습니다. 나중에 마커의 setMap() 메서드를 호출하여 마커를 추가할 수 있습니다.

다음 예시는 오스트레일리아 중앙의 울루루 지도에 간단한 마커를 추가합니다.

function initMap() {
  var myLatLng = {lat: -25.363, lng: 131.044};

  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 4,
    center: myLatLng
  });

  var marker = new google.maps.Marker({
    position: myLatLng,
    map: map,
    title: 'Hello World!'
  });
}
<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 async defer
src="https://maps.googleapis.com/maps/api/js?key=AIzaSyCkUOdZ5y7hMm0yrcCQoCvLwzdM6M8s5qk&callback=initMap">
</script>
function initMap() {
  var myLatLng = {lat: -25.363, lng: 131.044};

  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 4,
    center: myLatLng
  });

  var marker = new google.maps.Marker({
    position: myLatLng,
    map: map,
    title: 'Hello World!'
  });
}

위의 예시에서 마커는 생성될 때 마커 옵션의 map 속성을 사용하여 지도에 배치됩니다. 또는, 아래 예시와 같이 마커의 setMap() 메서드를 사용하여 지도에 직접 마커를 추가할 수 있습니다.

var myLatlng = new google.maps.LatLng(-25.363882,131.044922);
var mapOptions = {
  zoom: 4,
  center: myLatlng
}
var map = new google.maps.Map(document.getElementById("map"), mapOptions);

var marker = new google.maps.Marker({
    position: myLatlng,
    title:"Hello World!"
});

// To add the marker to the map, call setMap();
marker.setMap(map);

마커의 title은 툴팁으로 나타납니다.

마커 생성자에 Marker options을 전달하고 싶지 않다면, 대신 생성자의 마지막 인수에서 빈 객체 {}를 전달합니다.

예시 보기(marker-simple.html).

마커 제거

지도에서 마커를 제거하려면 setMap() 메서드를 호출하고 null을 인수로 전달합니다.

marker.setMap(null);

이 메서드는 마커를 삭제하지 않습니다. 단지 지도에서 마커를 제거할 뿐입니다. 마커를 삭제하려면 지도에서 삭제한 다음 마커 자체를 null로 설정해야 합니다.

마커 집합을 관리하려면 마커를 고정하는 배열을 생성해야 합니다. 또한 마커를 제거해야 하는 경우 배열의 각 마커에서 setMap()을 호출하면 됩니다. 지도에서 마커를 삭제하고 배열의 length0으로 설정하면 마커에 대한 모든 참조가 제거되므로 마커를 삭제할 수 있습니다.

예시 보기(marker-remove.html).

마커 애니메이트

마커가 다양한 상황에서 동적인 움직임을 보이도록 마커를 애니메이트할 수 있습니다. 마커가 애니메이트되는 방식을 지정하려면 google.maps.Animation 유형의 마커의 animation 속성을 사용합니다. 다음 Animation 값이 지원됩니다.

  • DROP은 마커가 지도에 처음 배치될 때 지도 맨 위에서 마지막 위치로 떨어져야 함을 나타냅니다. 마커가 멈추면 애니메이션이 중단되고 animationnull로 돌아갑니다. 대개 애니메이션 유형은 Marker 생성 시에 지정됩니다.
  • BOUNCE는 마커가 제자리에서 튀어올라야 함을 나타냅니다. 튀어오르는 마커는 animation 속성이 명시적으로 null로 설정될 때까지 튀어오르는 동작을 지속합니다.

Marker 객체에서 setAnimation()을 호출하여 기존 마커에서 애니메이션을 시작할 수 있습니다.

// The following example creates a marker in Stockholm, Sweden using a DROP
// animation. Clicking on the marker will toggle the animation between a BOUNCE
// animation and no animation.

var marker;

function initMap() {
  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 13,
    center: {lat: 59.325, lng: 18.070}
  });

  marker = new google.maps.Marker({
    map: map,
    draggable: true,
    animation: google.maps.Animation.DROP,
    position: {lat: 59.327, lng: 18.067}
  });
  marker.addListener('click', toggleBounce);
}

function toggleBounce() {
  if (marker.getAnimation() !== null) {
    marker.setAnimation(null);
  } else {
    marker.setAnimation(google.maps.Animation.BOUNCE);
  }
}
<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 async defer
src="https://maps.googleapis.com/maps/api/js?key=AIzaSyCkUOdZ5y7hMm0yrcCQoCvLwzdM6M8s5qk&callback=initMap">
</script>
// The following example creates a marker in Stockholm, Sweden using a DROP
// animation. Clicking on the marker will toggle the animation between a BOUNCE
// animation and no animation.

var marker;

function initMap() {
  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 13,
    center: {lat: 59.325, lng: 18.070}
  });

  marker = new google.maps.Marker({
    map: map,
    draggable: true,
    animation: google.maps.Animation.DROP,
    position: {lat: 59.327, lng: 18.067}
  });
  marker.addListener('click', toggleBounce);
}

function toggleBounce() {
  if (marker.getAnimation() !== null) {
    marker.setAnimation(null);
  } else {
    marker.setAnimation(google.maps.Animation.BOUNCE);
  }
}

예시 보기(marker-animations.html).

다수의 마커가 있는 경우, 한 번에 모두 지도에 투입하고 싶지 않을 수도 있습니다. setTimeout()을 사용하여 아래와 같은 패턴으로 마커의 애니메이션 간격을 지정할 수 있습니다.

function drop() {
  for (var i =0; i < markerArray.length; i++) {
    setTimeout(function() {
      addMarkerMethod();
    }, i * 200);
  }
}

예시 보기(marker-animations-iteration.html).

마커 이미지 사용자 지정

마커에 문자 또는 숫자를 표시하려는 경우, 마커 레이블을 사용할 수 있습니다. 더 큰 사용자 지정이 필요할 경우, 기본 마커 이미지 대신 표시할 아이콘을 정의할 수도 있습니다. 아이콘을 정의할 때는 마커의 시각적 동작을 결정하는 다양한 속성도 설정합니다.

아래 섹션에서는 마커 레이블, 간단한 아이콘, 복잡한 아이콘, 기호(벡터 아이콘)를 설명합니다.

마커 레이블

마커 레이블은 마커 안에 나타나는 문자 또는 숫자입니다. 이 섹션의 마커 이미지는 문자 'B'가 있는 마커 레이블을 표시합니다. 마커 레이블은 문자열 또는 문자열과 다른 레이블 속성을 포함하는 MarkerLabel 객체로 지정할 수 있습니다.

마커를 생성할 때 MarkerOptions 객체의 label 속성을 지정할 수 있습니다. 또는, Marker 객체에서 setLabel()을 호출하여 기존 마커에 레이블을 설정해도 됩니다.

다음 예시는 사용자가 지도를 클릭하면 레이블이 달린 마커를 표시합니다.

// In the following example, markers appear when the user clicks on the map.
// Each marker is labeled with a single alphabetical character.
var labels = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ';
var labelIndex = 0;

function initialize() {
  var bangalore = { lat: 12.97, lng: 77.59 };
  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 12,
    center: bangalore
  });

  // This event listener calls addMarker() when the map is clicked.
  google.maps.event.addListener(map, 'click', function(event) {
    addMarker(event.latLng, map);
  });

  // Add a marker at the center of the map.
  addMarker(bangalore, map);
}

// Adds a marker to the map.
function addMarker(location, map) {
  // Add the marker at the clicked location, and add the next-available label
  // from the array of alphabetical characters.
  var marker = new google.maps.Marker({
    position: location,
    label: labels[labelIndex++ % labels.length],
    map: map
  });
}

google.maps.event.addDomListener(window, 'load', initialize);
<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"></script>
// In the following example, markers appear when the user clicks on the map.
// Each marker is labeled with a single alphabetical character.
var labels = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ';
var labelIndex = 0;

function initialize() {
  var bangalore = { lat: 12.97, lng: 77.59 };
  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 12,
    center: bangalore
  });

  // This event listener calls addMarker() when the map is clicked.
  google.maps.event.addListener(map, 'click', function(event) {
    addMarker(event.latLng, map);
  });

  // Add a marker at the center of the map.
  addMarker(bangalore, map);
}

// Adds a marker to the map.
function addMarker(location, map) {
  // Add the marker at the clicked location, and add the next-available label
  // from the array of alphabetical characters.
  var marker = new google.maps.Marker({
    position: location,
    label: labels[labelIndex++ % labels.length],
    map: map
  });
}

google.maps.event.addDomListener(window, 'load', initialize);

예시 보기(marker-labels.html).

간단한 아이콘

가장 기본적인 경우, 아이콘은 단순히 기본 Google 지도 푸시핀 아이콘 대신 사용할 이미지를 나타낼 수 있습니다. 이러한 아이콘을 지정하려면 마커의 icon 속성을 이미지의 URL로 설정합니다. Google Maps JavaScript API는 아이콘의 크기를 자동으로 조정합니다.

// This example adds a marker to indicate the position of Bondi Beach in Sydney,
// Australia.
function initMap() {
  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 4,
    center: {lat: -33, lng: 151}
  });

  var image = 'https://developers.google.com/maps/documentation/javascript/examples/full/images/beachflag.png';
  var beachMarker = new google.maps.Marker({
    position: {lat: -33.890, lng: 151.274},
    map: map,
    icon: image
  });
}
<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 async defer
src="https://maps.googleapis.com/maps/api/js?key=AIzaSyCkUOdZ5y7hMm0yrcCQoCvLwzdM6M8s5qk&callback=initMap">
</script>
// This example adds a marker to indicate the position of Bondi Beach in Sydney,
// Australia.
function initMap() {
  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 4,
    center: {lat: -33, lng: 151}
  });

  var image = 'https://developers.google.com/maps/documentation/javascript/examples/full/images/beachflag.png';
  var beachMarker = new google.maps.Marker({
    position: {lat: -33.890, lng: 151.274},
    map: map,
    icon: image
  });
}

예시 보기(icon-simple.html).

복잡한 아이콘

복잡한 셰이프를 지정하여 클릭 가능한 영역을 나타내고, 아이콘이 어떤 방식으로 다른 오버레이에 대해 상대적으로 나타나야 하는지("스택 순서")를 지정할 수 있습니다. 이러한 방식으로 지정된 아이콘은 icon 속성을 Icon 유형의 객체로 설정해야 합니다.

Icon 객체는 이미지를 정의합니다. 또한 아이콘의 size, 아이콘의 origin(예를 들어, 원하는 이미지가 스프라이트에서 더 큰 이미지의 일부인 경우), 아이콘의 핫스팟이 배치될 (원점에 기반을 둔) anchor도 정의합니다.

사용자 지정 마커와 함께 label을 사용 중이라면, Icon 객체의 labelOrigin 속성으로 레이블 위치를 지정할 수 있습니다.

// The following example creates complex markers to indicate beaches near
// Sydney, NSW, Australia. Note that the anchor is set to (0,32) to correspond
// to the base of the flagpole.

function initMap() {
  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 10,
    center: {lat: -33.9, lng: 151.2}
  });

  setMarkers(map);
}

// Data for the markers consisting of a name, a LatLng and a zIndex for the
// order in which these markers should display on top of each other.
var beaches = [
  ['Bondi Beach', -33.890542, 151.274856, 4],
  ['Coogee Beach', -33.923036, 151.259052, 5],
  ['Cronulla Beach', -34.028249, 151.157507, 3],
  ['Manly Beach', -33.80010128657071, 151.28747820854187, 2],
  ['Maroubra Beach', -33.950198, 151.259302, 1]
];

function setMarkers(map) {
  // Adds markers to the map.

  // Marker sizes are expressed as a Size of X,Y where the origin of the image
  // (0,0) is located in the top left of the image.

  // Origins, anchor positions and coordinates of the marker increase in the X
  // direction to the right and in the Y direction down.
  var image = {
    url: 'https://developers.google.com/maps/documentation/javascript/examples/full/images/beachflag.png',
    // This marker is 20 pixels wide by 32 pixels high.
    size: new google.maps.Size(20, 32),
    // The origin for this image is (0, 0).
    origin: new google.maps.Point(0, 0),
    // The anchor for this image is the base of the flagpole at (0, 32).
    anchor: new google.maps.Point(0, 32)
  };
  // Shapes define the clickable region of the icon. The type defines an HTML
  // <area> element 'poly' which traces out a polygon as a series of X,Y points.
  // The final coordinate closes the poly by connecting to the first coordinate.
  var shape = {
    coords: [1, 1, 1, 20, 18, 20, 18, 1],
    type: 'poly'
  };
  for (var i = 0; i < beaches.length; i++) {
    var beach = beaches[i];
    var marker = new google.maps.Marker({
      position: {lat: beach[1], lng: beach[2]},
      map: map,
      icon: image,
      shape: shape,
      title: beach[0],
      zIndex: beach[3]
    });
  }
}
<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 async defer
src="https://maps.googleapis.com/maps/api/js?key=AIzaSyCkUOdZ5y7hMm0yrcCQoCvLwzdM6M8s5qk&callback=initMap">
</script>
// The following example creates complex markers to indicate beaches near
// Sydney, NSW, Australia. Note that the anchor is set to (0,32) to correspond
// to the base of the flagpole.

function initMap() {
  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 10,
    center: {lat: -33.9, lng: 151.2}
  });

  setMarkers(map);
}

// Data for the markers consisting of a name, a LatLng and a zIndex for the
// order in which these markers should display on top of each other.
var beaches = [
  ['Bondi Beach', -33.890542, 151.274856, 4],
  ['Coogee Beach', -33.923036, 151.259052, 5],
  ['Cronulla Beach', -34.028249, 151.157507, 3],
  ['Manly Beach', -33.80010128657071, 151.28747820854187, 2],
  ['Maroubra Beach', -33.950198, 151.259302, 1]
];

function setMarkers(map) {
  // Adds markers to the map.

  // Marker sizes are expressed as a Size of X,Y where the origin of the image
  // (0,0) is located in the top left of the image.

  // Origins, anchor positions and coordinates of the marker increase in the X
  // direction to the right and in the Y direction down.
  var image = {
    url: 'https://developers.google.com/maps/documentation/javascript/examples/full/images/beachflag.png',
    // This marker is 20 pixels wide by 32 pixels high.
    size: new google.maps.Size(20, 32),
    // The origin for this image is (0, 0).
    origin: new google.maps.Point(0, 0),
    // The anchor for this image is the base of the flagpole at (0, 32).
    anchor: new google.maps.Point(0, 32)
  };
  // Shapes define the clickable region of the icon. The type defines an HTML
  // <area> element 'poly' which traces out a polygon as a series of X,Y points.
  // The final coordinate closes the poly by connecting to the first coordinate.
  var shape = {
    coords: [1, 1, 1, 20, 18, 20, 18, 1],
    type: 'poly'
  };
  for (var i = 0; i < beaches.length; i++) {
    var beach = beaches[i];
    var marker = new google.maps.Marker({
      position: {lat: beach[1], lng: beach[2]},
      map: map,
      icon: image,
      shape: shape,
      title: beach[0],
      zIndex: beach[3]
    });
  }
}

예시 보기(icon-complex.html).

MarkerImage 객체를 Icon 유형으로 변환

Google Maps JavaScript API 3.10 버전까지 복잡한 아이콘은 MarkerImage 객체로 정의되었습니다. Icon 객체 리터럴이 3.10 버전에서 추가되었고 3.11 버전부터는 MarkerImage를 대체합니다. Icon 객체 리터럴은 MarkerImage와 동일한 매개변수를 지원하므로, 생성자를 제거하고, 이전 매개변수를 {}로 묶고, 각 매개변수 이름을 추가하면 MarkerImageIcon으로 쉽게 변환할 수 있습니다. 예:

var image = new google.maps.MarkerImage(
    place.icon,
    new google.maps.Size(71, 71),
    new google.maps.Point(0, 0),
    new google.maps.Point(17, 34),
    new google.maps.Size(25, 25));

다음과 같이 변환:

var image = {
  url: place.icon,
  size: new google.maps.Size(71, 71),
  origin: new google.maps.Point(0, 0),
  anchor: new google.maps.Point(17, 34),
  scaledSize: new google.maps.Size(25, 25)
};

기호

마커는 래스터 이미지 이외에도 Symbols라는 벡터 경로 표시를 지원합니다. 벡터 경로를 표시하려면 원하는 경로가 포함된 Symbol 객체 리터럴을 마커의 icon 속성에 전달합니다. google.maps.SymbolPath에서 사전 정의된 경로 중 하나를 사용하거나 SVG 경로 표기법을 사용하여 사용자 지정 경로를 정의할 수 있습니다.

자세한 내용은 기호 문서를 참조하세요.

드래그 가능한 마커

사용자가 지도의 다른 위치로 마커를 드래그할 수 있게 하려면 마커 옵션에서 draggabletrue로 설정합니다.

var myLatlng = new google.maps.LatLng(-25.363882,131.044922);
var mapOptions = {
  zoom: 4,
  center: myLatlng
}
var map = new google.maps.Map(document.getElementById("map"), mapOptions);

// Place a draggable marker on the map
var marker = new google.maps.Marker({
    position: myLatlng,
    map: map,
    draggable:true,
    title:"Drag me!"
});

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

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