모든 준비를 마쳤습니다!

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

Google Maps JavaScript API 활성화

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

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

KML 및 GeoRSS 계층

KmlLayer는 KML 및 GeoRSS 요소를 Google Maps JavaScript API 타일 오버레이로 렌더링합니다.

개요

Google Maps JavaScript API는 지리 정보를 표시하기 위한 KML 및 GeoRSS 데이터 형식을 지원합니다. 이러한 데이터 형식은 KmlLayer 객체를 이용하여 지도에 표시됩니다. 이 객체 생성자는 공개적으로 액세스할 수 있는 KML이나 GeoRSS 파일의 URL을 취합니다.

Maps JavaScript API는 제공된 지리적 XML 데이터를 Maps JavaScript API 타일 오버레이로 지도에 표시되는 KML 표시로 변환합니다. 이 KML의 형태와 동작은 익숙한 Maps JavaScript API 오버레이 요소와 유사합니다. KML <Placemark>와 GeoRSS point 요소는 마커로 렌더링됩니다. 예를 들어, <LineString> 요소는 폴리라인으로 렌더링되고 <Polygon> 요소는 폴리곤으로 렌더링됩니다. 마찬가지로 <GroundOverlay> 요소는 지도에서 사각형 이미지로 렌더링됩니다. 그러나 이러한 객체는 Google Maps JavaScript API Markers, Polylines, Polygons 또는 GroundOverlays아니며 지도에 단일 객체로 렌더링됩니다.

KmlLayer 객체는 map 속성이 설정되면 지도에 나타납니다. setMap()을 호출하고 null을 전달하여 지도에서 객체를 제거할 수 있습니다. KmlLayer 객체는 지도의 주어진 경계에서 적절한 지형지물을 자동으로 검색하여 이러한 하위 요소의 렌더링을 관리합니다. 경계가 변경되면, 현재 뷰포트의 지형지물이 자동으로 렌더링됩니다.

KmlLayer 내부의 구성 요소는 주문에 따라 렌더링되므로, 계층에서 수천 개의 마커, 폴리라인, 폴리곤의 렌더링을 관리할 수 있습니다. 이러한 구성 객체는 각각 개별 객체에서 데이터를 반환하는 클릭 이벤트를 제공하지만, 직접 액세스할 수 없다는 점에 유의하세요.

KML 계층 옵션

KmlLayer() 생성자는 선택적으로 다수의 KmlLayerOptions를 전달합니다.

  • mapKmlLayer를 렌더링할 Map을 지정합니다. setMap() 메서드 내에서 이 값을 null로 설정하여 KmlLayer를 숨길 수 있습니다.
  • preserveViewport는 계층을 표시할 때 지도가 KmlLayer 콘텐츠의 경계에 맞게 조정되지 않도록 지정합니다. 기본적으로, KmlLayer를 표시할 때, 계층의 콘텐츠를 모두 볼 수 있도록 지도의 확대/축소 수준과 위치가 조정됩니다.
  • suppressInfoWindowsKmlLayer 내부의 클릭 가능한 지형지물이 InfoWindow 객체를 표시해서는 안된다는 것을 나타냅니다.

또한, KmlLayer이 렌더링되면 KmlLayerMetadata 객체 리터럴 안에 계층 이름, 설명, 스니펫, 저자를 포함하는 변경 불가능한 metadata 속성이 포함됩니다. getMetadata() 메서드를 사용하여 이 정보를 검사할 수 있습니다. KmlLayer 객체를 렌더링할 때 외부 서버와 비동기 통신이 필요하므로, metadata_changed 이벤트를 수신하기를 원할 수도 있습니다. 이 이벤트는 속성이 채워졌음을 나타냅니다.

다음 예시는 주어진 GeoRSS 피드에서 KmlLayer를 생성합니다.

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

  var georssLayer = new google.maps.KmlLayer({
    url: 'http://api.flickr.com/services/feeds/geo/?g=322338@N20&lang=en-us&format=feed-georss'
  });
  georssLayer.setMap(map);
}
<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 map = new google.maps.Map(document.getElementById('map'), {
    zoom: 4,
    center: {lat: 49.496675, lng: -102.65625}
  });

  var georssLayer = new google.maps.KmlLayer({
    url: 'http://api.flickr.com/services/feeds/geo/?g=322338@N20&lang=en-us&format=feed-georss'
  });
  georssLayer.setMap(map);
}

GeoRSS 예시 보기

다음 예시는 주어진 KML 피드에서 KmlLayer를 생성합니다.

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

  var ctaLayer = new google.maps.KmlLayer({
    url: 'http://googlemaps.github.io/js-v2-samples/ggeoxml/cta.kml',
    map: map
  });
}
<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 map = new google.maps.Map(document.getElementById('map'), {
    zoom: 11,
    center: {lat: 41.876, lng: -87.624}
  });

  var ctaLayer = new google.maps.KmlLayer({
    url: 'http://googlemaps.github.io/js-v2-samples/ggeoxml/cta.kml',
    map: map
  });
}

KML 예시 보기

KML 지형지물 상세정보

KML에는 다수의 지형지물이 포함될 수 있으므로 KmlLayer 객체에서 직접 지형지물 데이터에 액세스하지 못할 수도 있습니다. 대신, 지형지물은 표시될 때 클릭 가능한 Maps JavaScript API 오버레이와 유사하게 렌더링됩니다. 기본적으로 개별 지형지물을 클릭하면 주어진 지형지물에 대한 KML <title><description> 정보가 포함된 InfoWindow가 나타납니다. 또한, KML 지형지물을 클릭하면 KmlMouseEvent가 발생하고, 이 이벤트가 다음 정보를 전달합니다.

  • position은 이 KML 지형지물의 InfoWindow를 고정하는 위도/경도 좌표를 나타냅니다. 일반적으로 이 위치는 폴리곤, 폴리라인, GroundOverlay의 경우 클릭된 위치이지만, 마커의 경우 실제 원점입니다.
  • pixelOffsetInfoWindow “꼬리”를 고정하는 위의 position부터의 오프셋을 나타냅니다. 폴리곤 객체의 경우, 일반적으로 이 오프셋은 0,0이지만 마커의 경우 마커 높이가 포함됩니다.
  • featureData에는 KmlFeatureData의 JSON 구조가 포함됩니다.

다음은 샘플 KmlFeatureData 객체입니다.

{
  author: {
    email: "nobody@google.com",
    name: "Mr Nobody",
    uri: "http://example.com"
  },
  description: "description",
  id: "id",
  infoWindowHtml: "html",
  name: "name",
  snippet: "snippet"
}

다음 예시는 지형지물을 클릭하면 측면 <div> 내부에 KML 지형지물 <Description> 텍스트를 표시합니다.

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

  var kmlLayer = new google.maps.KmlLayer({
    url: 'http://googlemaps.github.io/kml-samples/kml/Placemark/placemark.kml',
    suppressInfoWindows: true,
    map: map
  });

  kmlLayer.addListener('click', function(kmlEvent) {
    var text = kmlEvent.featureData.description;
    showInContentWindow(text);
  });

  function showInContentWindow(text) {
    var sidediv = document.getElementById('content-window');
    sidediv.innerHTML = text;
  }
}
<div id="map"></div>
<div id="content-window"></div>
html, body {
  height: 100%;
  margin: 0;
  padding: 0;
}
#map {
  float: left;
  height: 100%;
  width: 79%;
}
#content-window {
  float: left;
  font-family: 'Roboto','sans-serif';
  height: 100%;
  line-height: 30px;
  padding-left: 10px;
  width: 19%;
}
 <!-- 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 map = new google.maps.Map(document.getElementById('map'), {
    zoom: 12,
    center: {lat: 37.06, lng: -95.68}
  });

  var kmlLayer = new google.maps.KmlLayer({
    url: 'http://googlemaps.github.io/kml-samples/kml/Placemark/placemark.kml',
    suppressInfoWindows: true,
    map: map
  });

  kmlLayer.addListener('click', function(kmlEvent) {
    var text = kmlEvent.featureData.description;
    showInContentWindow(text);
  });

  function showInContentWindow(text) {
    var sidediv = document.getElementById('content-window');
    sidediv.innerHTML = text;
  }
}

KML 예시 보기

KML 렌더링의 크기 및 복잡성 제한

Google Maps JavaScript API는 로드된 KML 파일의 크기와 복잡성에 제한이 있습니다. 다음은 현재 제한의 요약입니다.

참고: 이 제한은 언제든지 변경될 수 있습니다.

가져온 최대 파일 크기(원시 KML, 원시 GeoRSS 또는 압축된 KMZ)
3MB
압축되지 않은 최대 KML 파일 크기
10MB
최대 네트워크 링크 수
10
문서 전체의 총 지형지물의 최대 수
1.000
KML 계층 수
단일 Google 지도에 표시 할 수 있는 KML 계층 수에 제한이 있습니다. 이 제한을 초과하면 지도에 계층이 표시되지 않으며 웹 브라우저의 JavaScript 콘솔에 오류가 보고됩니다. 이 제한은 생성된 KMLLayer 클래스 수와 해당 계층을 만드는 데 사용된 모든 URL의 총 길이의 조합을 기준으로 합니다. 생성하는 각각의 새로운 KMLLayer는 KML 파일이 로드된 URL의 길이에 따라 계층의 제한 부분과 제한의 나머지 부분을 차지합니다. 결과적으로 추가할 수 있는 계층의 수는 애플리케이션에 따라 다릅니다. 제한을 넘지 않고 평균 10-20개의 계층을 로드할 수 있습니다. 여전히 제한에 도달하면 URL 단축기(예: https://goo.gl)를 사용하여 KML URL을 줄입니다. 또는 개별 KML URL에 대한 NetworkLink로 구성된 단일 KML 파일을 만듭니다.

지원되는 KML 요소

Google Maps JavaScript API는 다음 KML 요소를 지원합니다. 일반적으로 KML 파서는 이해하지 못하는 XML 태그를 자동으로 무시합니다.

  • 장소 마크
  • 아이콘
  • 폴더
  • 설명이 포함된 HTML—<BalloonStyle> 및 <text>을 통한 엔터티 교체
  • KMZ(첨부한 이미지를 포함한 압축된 KML)
  • 폴리라인 및 폴리곤
  • 색, 채우기 및 불투명도를 포함하는 폴리라인 및 폴리곤의 스타일
  • 데이터를 동적으로 가져오는 네트워크 링크
  • 그라운드 오버레이 및 화면 오버레이

다음 표는 지원되는 KML 요소에 대한 자세한 정보를 제공합니다.

KML 요소 API에서 지원 여부 설명
<address> 아니요
<AddressDetails> 아니요
<Alias> 해당 없음 <Model>은 지원되지 않음
<altitude> 아니요
<altitudeMode> 아니요
<atom:author>
<atom:link>
<atom:name>
<BalloonStyle> 일부 <text>만 지원
<begin> 해당 없음 <TimeSpan>은 지원되지 않음
<bgColor> 아니요
<bottomFov> 해당 없음 <PhotoOverlay>는 지원되지 않음
<Camera> 아니요
<Change> 일부 스타일 변경만 지원
<color> 일부 #AABBGGRR 및 #BBGGRR 포함. <IconStyle>, <ScreenOverlay> 및 <GroundOverlay>에서는 지원되지 않음
<colorMode> 아니요
<cookie> 아니요
<coordinates>
<Create> 아니요
<Data>
<Delete> 아니요
<description> HTML 콘텐츠는 허용되지만 브라우저 간 공격으로부터 보호하기 위해 삭제됩니다. 형식 $[dataName]의 엔터티 교체는 지원되지 않습니다.
<displayMode> 아니요
<displayName> 아니요
<Document> 일부 암시적으로 하위 요소가 지원됩니다. 다른 기능의 하위 요소는 영향을 받지 않습니다.
<drawOrder> 아니요
<east>
<end> 해당 없음 <TimeSpan>은 지원되지 않음
<expires> 자세한 내용은 요약 섹션 참조
<ExtendedData> 일부 형식이 없는 <Data>만 지원. <SimpleData> 또는 <Schema> 및 형식 $[dataName]의 엔터티 교체는 지원되지 않음.
<extrude> 아니요
<fill>
<flyToView> 아니요
<Folder>
<geomColor> 아니요 지원 중단됨
<GeometryCollection> 아니요 지원 중단됨
<geomScale> 아니요 지원 중단됨
<gridOrigin> 해당 없음 <PhotoOverlay>는 지원되지 않음
<GroundOverlay> 회전할 수 없음
<h> 지원 중단됨
<heading>
hint target=... 지원됨
<hotSpot>
<href>
<httpQuery> 아니요
<Icon> 회전할 수 없음
<IconStyle>
<ImagePyramid> 해당 없음 <PhotoOverlay>는 지원되지 않음
<innerBoundaryIs> <LinearRing> 순서에 따라 암시적으로
<ItemIcon> 해당 없음 <ListStyle>은 지원되지 않음
<key> 해당 없음 <StyleMap>은 지원되지 않음
<kml>
<labelColor> 아니요 지원 중단됨
<LabelStyle> 아니요
<latitude>
<LatLonAltBox>
<LatLonBox>
<leftFov> 해당 없음 <PhotoOverlay>는 지원되지 않음
<LinearRing>
<LineString>
<LineStyle>
<Link>
<linkDescription> 아니요
<linkName> 아니요
<linkSnippet> 아니요
<listItemType> 해당 없음 <ListStyle>은 지원되지 않음
<ListStyle> 아니요
<Location> 해당 없음 <Model>은 지원되지 않음
<Lod>
<longitude>
<LookAt> 아니요
<maxAltitude>
<maxFadeExtent>
<maxHeight> 해당 없음 <PhotoOverlay>는 지원되지 않음
<maxLodPixels>
<maxSessionLength> 아니요
<maxWidth> 해당 없음 <PhotoOverlay>는 지원되지 않음
<message> 아니요
<Metadata> 아니요 지원 중단됨
<minAltitude>
<minFadeExtent>
<minLodPixels>
<minRefreshPeriod> 아니요 <NetworkLink>
<Model> 아니요
<MultiGeometry> 일부 렌더링되지만 왼쪽 패널의 별도 기능으로 표시됨
<name>
<near> 해당 없음 <PhotoOverlay>는 지원되지 않음
<NetworkLink>  
<NetworkLinkControl> 일부 <Update> 및 <expires>는 부분적으로 지원됩니다. API는 HTTP 헤더의 만료 설정은 무시하지만 KML에 지정된 만료 설정은 사용합니다. 만료 설정이 없거나 유효 기간이 지나지 않은 경우 Google 지도는 지정되지 않은 기간 동안 인터넷에서 가져온 데이터를 캐시할 수 있습니다. 문서의 이름을 바꿔 다른 URL로 가져오거나 문서에 적절한 만료 설정이 있는지 확인하여 인터넷에서 데이터를 다시 가져올 수 있습니다.
<north>
<open>
<Orientation> 해당 없음 <Model>은 지원되지 않음
<outerBoundaryIs> <LinearRing> 순서에 따라 암시적으로
<outline>
<overlayXY> 아니요
<Pair> 해당 없음 <StyleMap>은 지원되지 않음
<phoneNumber> 아니요
<PhotoOverlay> 아니요
<Placemark>
<Point>
<Polygon>
<PolyStyle>
<range>
<refreshInterval> 일부 <Link>만 적용되고 <Icon>에는 적용 안 됨.
<refreshMode> HTTP 헤더는 "onExpire" 모드에서 지원되지 않습니다. 위의 <Update> 및 <expires>에 대한 내용을 참조하세요.
<refreshVisibility> 아니요
<Region>
<ResourceMap> 해당 없음 <Model>은 지원되지 않음
<rightFov> 해당 없음 <PhotoOverlay>는 지원되지 않음
<roll> 해당 없음 <Camera>와 <Model>은 지원되지 않음
<rotation> 아니요
<rotationXY> 아니요
<Scale> 해당 없음 <Model>은 지원되지 않음
<scale> 아니요
<Schema> 아니요
<SchemaData> 아니요
<ScreenOverlay> 회전할 수 없음
<screenXY> 아니요
<shape> 해당 없음 <PhotoOverlay>는 지원되지 않음
<SimpleData> 해당 없음 <SchemaData>는 지원되지 않음
<SimpleField> 해당 없음 <Schema>는 지원되지 않음
<size>
<Snippet>
<south>
<state> 해당 없음 <ListStyle>은 지원되지 않음
<Style>
<StyleMap> 아니요 롤오버(강조 표시) 효과는 지원되지 않음
<styleUrl> 해당 없음 <StyleMap>은 지원되지 않음
<targetHref> 일부 <Update>에는 지원되지만 <Alias>에는 지원되지 않음
<tessellate> 아니요
<text> $[geDirections]의 교체는 지원되지 않음
<textColor> 아니요
<tileSize> 해당 없음 <PhotoOverlay>는 지원되지 않음
<tilt> 아니요
<TimeSpan> 아니요
<TimeStamp> 아니요
<topFov> 해당 없음 <PhotoOverlay>는 지원되지 않음
<Update> 일부 스타일 변경에만 적용되고 <Create> 또는 <Delete>에는 적용 안 됨
<Url> 지원 중단됨
<value>
<viewBoundScale> 아니요
<viewFormat> 아니요
<viewRefreshMode> 일부 "onStop"이 지원됨
<viewRefreshTime>
<ViewVolume> 해당 없음 <PhotoOverlay>는 지원되지 않음
<visibility> 일부 <Folder>에 적용됨. 자식 placemark는 표시 여부(visibility)를 상속함
<w> 지원 중단됨
<west>
<when> 해당 없음 <TimeStamp>는 지원되지 않음
<width>
<x> 지원 중단됨
<y> 지원 중단됨

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

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