모든 준비를 마쳤습니다!

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

Google Maps JavaScript API 활성화

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

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

Google Maps JavaScript API 애플리케이션을 v2에서 v3으로 업그레이드

Google Maps JavaScript API 버전 2는 사용이 중단되었습니다. 이 가이드는 이미 Google Maps JavaScript API v2를 사용 중인 개발자가 버전 3으로 코드를 마이그레이션하는 것을 돕기 위해 작성되었습니다.

Google Maps JavaScript API v2와 v3 간에 많은 사항들이 변경되었습니다. 새로운 API에서 작업을 시작하면 얼마 지나지 않아 단순한 점증적 업그레이드가 아니라는 것을 깨닫게 될 것입니다. 좋은 소식이 있다면 뛰어난 기능들이 많이 추가되었고 개발자의 시점에서 API의 전반적인 사용 편의성이 개선되었다는 것입니다. Google Maps JavaScript API v2에서 Google Maps JavaScript API v3로 업그레이드하고자 하는 분들을 위해 이 가이드는 업그레이드 과정을 도와주고 v2 API 사용자를 위한 가장 일반적인 몇 가지 변경 사항을 설명합니다.

개요

모든 애플리케이션은 마이그레이션 절차가 약간씩 다릅니다. 그러나 모든 프로젝트에 공통으로 존재하는 몇 가지 단계가 있습니다.

  1. 새 키 가져오기. Google Maps JavaScript API는 Google API Console을 사용하여 키를 관리합니다. 마이그레이션을 시작하기 전에 새 API 키를 가져와야 합니다.
  2. API 부트스트랩 업데이트. 대부분 애플리케이션은 다음 코드로 Google Maps JavaScript API v3를 로드합니다.
    <script type="text/javascript" src="//maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&sensor=true_OR_false"></script>
  3. 코드 업데이트. 애플리케이션마다 변경이 필요한 정도가 다릅니다. 일반적인 변경 사항:
    • 항상 google.maps 네임스페이스를 참조합니다. v3에서 모든 Google Maps JavaScript API 코드는 전역 네임스페이스가 아니라 google.maps.* 네임스페이스에 저장됩니다. 이 과정에서 대부분 객체의 이름도 변경되었습니다. 예를 들어 이제 GMap2 대신 google.maps.Map을 로드해야 합니다.
    • 사용하지 않는 메서드에 대한 참조를 제거합니다. GDownloadURL이나 GLog 같은 범용 유틸리티 메서드가 다수 제거되었습니다. 이 기능을 타사 유틸리티 라이브러리로 대체하거나 이 참조를 코드에서 제거하세요.
    • (선택 항목) 코드에 라이브러리를 추가합니다. 많은 기능이 유틸리티 라이브러리로 이동되었기 때문에 각 앱은 사용할 API 부분만 로드하면 됩니다.
    • (선택 항목) v3 extern을 사용하도록 프로젝트를 구성합니다. v3 extern은 Closure Compiler로 코드의 유효성을 검사하거나 IDE에서 자동 완성을 트리거하는 데 사용될 수 있습니다. 고급 컴파일 및 extern에 대해 자세히 알아보세요.
  4. 테스트 및 반복. 아직 해야 할 작업이 다소 남아 있지만 이제 새로운 v3 지도 애플리케이션으로의 마이그레이션이 거의 완료되었습니다!

Google Maps JavaScript API v3 변경 사항

마이그레이션을 계획하기 전에 시간을 할애하여 Google Maps JavaScript API v2와 Google Maps JavaScript API v3의 차이점을 이해해야 합니다. Google Maps JavaScript API의 최신 버전은 최신 JavaScript 프로그래밍 기법, 라이브러리 사용 확대, 단순화된 API에 초점을 맞추고 처음부터 다시 개발되었습니다. API에 새로운 기능이 다수 추가되었고 여러 가지 익숙한 기능이 변경되거나 제거되기도 했습니다. 이 섹션에서는 두 릴리스의 핵심적 차이에 중점을 두고 설명합니다.

v3 API 변경 사항:

  • 핵심 라이브러리가 간소화되었습니다. 다수의 보조 기능을 라이브러리로 이전하여 핵심 API의 로드 및 분석 시간을 단축하고 어느 기기에서나 지도를 신속히 로드할 수 있게 했습니다.
  • 폴리곤 렌더링이나 마커 배치와 같은 여러 가지 기능의 성능이 개선되었습니다.
  • 모바일 프록시와 기업 방화벽에서 사용하는 공동 주소를 더욱 잘 수용할 수 있도록 클라이언트측 사용 제한에 새로운 방법을 도입했습니다.
  • 여러 가지 최신 브라우저와 모바일 브라우저 지원을 추가했습니다. Internet Explorer 6 지원이 중단되었습니다.
  • 범용 도우미 클래스( GLog 또는 GDownloadUrl)가 다수 제거되었습니다. 현재 유사한 기능을 제공하는 많은 뛰어난 JavaScript 라이브러리가 있습니다(예: Closure 또는 jQuery).
  • 모든 모바일 기기에서 로드되는 HTML5 스트리트 뷰가 구현되었습니다.
  • 사진을 사용한 사용자 지정 스트리트 뷰 파노라마로 스키 슬로프, 매물로 나온 주택, 기타 흥미로운 장소를 공유할 수 있습니다.
  • 스타일 지정 지도 사용자 지정으로 고유한 시각적 스타일에 맞게 기본 지도의 요소 표시 방법을 변경할 수 있습니다.
  • 여러 가지 새로운 서비스(예: ElevationService 및 Distance Matrix)를 지원합니다.
  • 길찾기 서비스를 개선하여 대체 경로, 경로 최적화(순회 세일즈맨 문제에 대한 근사 해), 자전거 길찾기(자전거 계층 사용), 대중교통 길찾기, 드래그 가능한 길찾기를 제공합니다.
  • 지오코딩 형식을 업데이트하여 Google Maps Geocoding API v2의 accuracy 값보다 더욱 정확한 유형 정보를 제공합니다.
  • 하나의 지도에서 여러 개의 정보 창을 지원합니다.

애플리케이션 업그레이드

새로운 키

Google Maps JavaScript API v3는 새로운 키 시스템을 사용합니다. v2 키는 v3 애플리케이션에서 사용할 수 없습니다. 애플리케이션을 프로덕션에 배포하기 전에 v3 키를 추가할 경우:

  • Google API Console에서 사용 보고서를 확인할 수 있습니다.
  • 필요에 따라 추가 할당량을 구매할 수 있습니다.
  • Google에서 개발자의 애플리케이션과 관련하여 연락을 취할 수 있습니다.

Google Maps JavaScript API v3를 로딩하면 키가 전달됩니다. 키 생성 방법:

  1. Google API Console을 방문하여 Google 계정으로 로그인합니다.
  2. 왼쪽 메뉴의 Services 링크를 클릭하고 Google Maps JavaScript API v3 서비스를 활성화합니다.
  3. 서비스가 활성화되면 Simple API Access 섹션의 API Access 페이지에서 API 키를 구할 수 있습니다. Maps API 애플리케이션에서는 브라우저 앱용 키을 사용합니다.

Maps APIs for Work 라이선스의 클라이언트 ID

Google Maps APIs for Work 라이선스가 있다면 키 대신 클라이언트 ID를 사용해야 합니다. 이 두 가지를 함께 사용할 수 없습니다. 클라이언트 ID는 키와 유사하지만 다음과 같은 차이가 있습니다.

  • 클라이언트 ID를 사용하는 Google Maps APIs 애플리케이션은 Maps Analytics와 같은 추가 기능이나 제한에 액세스할 수 있습니다.
  • 클라이언트 ID는 Google Cloud Support가 생성하고 Maps APIs for Work 환영 편지를 통해 제공됩니다. Google API Console을 사용하여 클라이언트 ID를 생성하거나 찾지 않습니다.
  • Google Maps JavaScript API를 로드할 때는 key 매개변수 대신 client 매개변수를 사용합니다. 예: 
    <script src="//maps.googleapis.com/maps/api/js?v=3&client=gme-yourclientid&sensor=true_or_false" type="text/javascript"></script>

    • 클라이언트 ID는 언제나 gme-라는 접두사가 붙습니다.

API 로드

코드에서 처음으로 수정해야 할 부분은 API 로드 방법과 관련이 있습니다. v2에서는 http://maps.google.com/maps를 요청하여 Google Maps JavaScript API를 로드했습니다. Google Maps JavaScript API v3를 로드할 때 변경 사항:

  1. //maps.googleapis.com/maps/api/js에서 API를 로드합니다.
  2. file 매개변수를 제거합니다.
  3. 필수 sensor 매개변수를 포함합니다.
  4. 새로운 v3 키로 key 매개변수를 업데이트합니다. Google Maps APIs for Work 고객은 client 매개변수를 사용해야 합니다.
  5. (Google Maps API 프리미엄 플랜만 해당) client 매개변수가 Google Maps API 프리미엄 플랜 개발자 가이드에서 설명한 대로 제공되어야 합니다.
  6. v 매개변수를 제거하고 최신 릴리스 버전을 요청하거나 v3 버전 관리 구성표에 따라 값을 변경합니다.
  7. (선택 항목) hl 매개변수를 language로 교체하고 값을 보존합니다.
  8. (선택 항목) libraries 매개변수를 추가하여 옵션 라이브러리를 로드합니다.

가장 단순하게는 v3 부트스트랩이 API 키와 센서 매개변수만 지정합니다.

<script type="text/javascript" src="//maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&sensor=false"></script>

아래 예시에서는 Maps JavaScript API v2의 최신(시험용) 독일어 버전을 요청합니다.

<script type="text/javascript" src="//maps.google.com/maps?file=api&v=2.x&sensor=false&key=YOUR_API_KEY&hl=de"></script>

아래 예시는 v3 요청과 같습니다.

<script type="text/javascript" src="//maps.googleapis.com/maps/api/js?v=3.exp&sensor=false&key=YOUR_API_KEY&language=de"></script>

버전 관리

v3에서는 특정 버전을 로드할 필요가 없습니다. 버전 매개변수를 생략하면 가장 최신의 시험용 API 버전을 받습니다. 개발자가 원할 경우, 특정 버전 번호나 최신(시험용) 버전, 가장 안정적인 동결 버전을 지정할 수 있습니다.

아래 표는 v2 버전 구성표를 v3에 매핑합니다.

v2 v3 사용 사례
2.s 3.0 동결 버전. 현재 가장 오래된 버전.
2 3 릴리스 버전. 가장 최신의 안정적인 버전.
2.x 3.exp 시험용 버전.

중요: Google Maps API 프리미엄 플랜 SLA는 시험용 버전에는 적용되지 않습니다. Google Maps API 프리미엄 플랜 애플리케이션은 최신 릴리스 또는 동결 버전을 사용해야 SLA를 적용할 수 있습니다.

google.maps 네임스페이스 도입

Google Maps JavaScript API v3에서 가장 눈에 띄는 변화는 google.maps 네임스페이스를 도입한 것입니다. v2 API는 기본적으로 모든 객체를 전역 네임스페이스에 넣어서 이름에 충돌이 발생했습니다. v3에서는 모든 객체가 google.maps 네임스페이스에 들어갑니다.

애플리케이션을 v3으로 마이그레이션할 때는 새로운 네임스페이스를 사용할 수 있도록 코드를 변경해야 합니다. 안타깝게도 "G"를 검색해서 "google.maps."로 교체하는 것만으로는 완전하지 못하지만 코드를 검토할 때 적용할 만한 좋은 방법입니다. 다음은 v2와 v3에서 해당 클래스의 예시입니다.

v2 v3
GMap2 google.maps.Map
GLatLng google.maps.LatLng
GInfoWindow google.maps.InfoWindow
GMapOptions google.map.MapOptions
G_API_VERSION google.maps.version
GPolyStyleOptions google.maps.PolygonOptions
또는 google.maps.PolylineOptions

사용하지 않는 코드 제거

Google Maps JavaScript API v3는 v2와 대부분 기능이 동일하지만 일부 클래스는 지원이 중단되었습니다. 마이그레이션할 때는 지원이 중단된 클래스를 타사 유틸리티 라이브러리로 대체하거나 코드에서 참조를 제거해야 합니다. 유사한 기능을 제공하는 많은 뛰어난 JavaScript 라이브러리가 있습니다(예: Closure 또는 jQuery).

Google Maps JavaScript API v3에서 지원이 중단된 클래스:

GBoundsGLanguage
GBrowserIsCompatibleGLayer
GControlGLog
GControlAnchorGMercatorProjection
GControlImplGNavLabelControl
GControlPositionGObliqueMercator
GCopyrightGOverlay
GCopyrightCollectionGPhotoSpec
GDownloadUrlGPolyEditingOptions
GDraggableObjectGScreenOverlay
GDraggableObjectOptionsGStreetviewFeatures
GFactualGeocodeCacheGStreetviewLocation
GGeoAddressAccuracyGStreetviewOverlay
GGeocodeCacheGStreetviewUserPhotosOptions
GGoogleBarGTileLayerOptions
GGoogleBarAdsOptionsGTileLayerOverlayOptions
GGoogleBarLinkTargetGTrafficOverlayOptions
GGoogleBarListingTypesGUnload
GGoogleBarOptionsGXml
GGoogleBarResultListGXmlHttp
GInfoWindowTabGXslt
GKeyboardHandler

코드 비교

v2와 v3 API로 작성한 다소 단순한 애플리케이션 2개를 비교하겠습니다.

<!DOCTYPE html>
<html>
  <head>
    <script src="//maps.google.com/maps?file=api&v=2&key=YOUR_API_KEY&sensor=false"
        type="text/javascript"></script>
    <style type="text/css">
      html, body, #map { height: 100%; margin: 0; }
    </style>
    <script type="text/javascript">
    function initialize() {
      if (GBrowserIsCompatible()) {
        var map = new GMap2(
            document.getElementById('map'));
        map.setCenter(new GLatLng(37.4419, -122.1419), 13);
        map.setUIToDefault();

        map.addOverlay(new GMarker(new GLatLng(37.4419, -122.1419)));

      }
    }
    </script>
  </head>
  <body onload="initialize()" onunload="GUnload()">
    <div id="map"></div>
  </body>
</html>
    
<!DOCTYPE html>
<html>
  <head>
    <script src="//maps.googleapis.com/maps/api/js?sensor=false"
        type="text/javascript"></script>
    <style type="text/css">
      html, body, #map { height: 100%; margin: 0; }
    </style>
    <script type="text/javascript">
    function initialize() {
      var map = new google.maps.Map(
        document.getElementById('map'), {
          center: new google.maps.LatLng(37.4419, -122.1419),
          zoom: 13,
          mapTypeId: google.maps.MapTypeId.ROADMAP
      });

      var marker = new google.maps.Marker({
            position: new google.maps.LatLng(37.4419, -122.1419),
            map: map
      });

    }
    google.maps.event.addDomListener(window, 'load', initialize);
    </script>
  </head>
  <body>
    <div id="map"></div>
  </body>
</html>

보다시피 두 애플리케이션은 여러 가지 차이가 있습니다. 눈에 띄는 변경 사항:

  • API를 로드하는 주소가 변경되었습니다.
  • v3에서 GBrowserIsCompatible()와 GUnload() 메서드가 필요 없어져서 API에서 제거되었습니다.
  • GMap2 객체는 API의 중심 객체로 google.maps.Map으로 대체되었습니다.
  • 속성이 옵션 클래스를 통해 로드됩니다. 위의 예시에서는 지도를 로드하는 데 필요한 3가지 속성(center, zoom 및 mapTypeId)을 인라인 처리된 MapOptions 객체를 통해 설정했습니다.
  • v3에서는 기본 UI가 기본값입니다. MapOptions 객체에서 disableDefaultUI 속성을 true로 설정하면 비활성화할 수 있습니다.

요약

이제 Google Maps JavaScript API v2에서 Google Maps JavaScript API v3로의 마이그레이션과 관련된 요점을 어느 정도 파악하셨을 것입니다. 여러분이 알아야 할 정보가 더 많이 있을 수도 있지만, 이는 여러분의 애플리케이션에 달려 있습니다. 다음 섹션에는 여러분이 마주할 만한 특정 사례와 관련된 마이그레이션 지침이 포함되어 있습니다. 또한, 업그레이드 과정에서 유용하게 사용할 만한 자료가 여러 가지 있습니다.

이 문서와 관련된 문제나 질문이 있다면 이 페이지 상단에 있는 이 문서에 대한 피드백 링크를 사용하세요.

상세 참조

이 섹션은 Google Maps JavaScript API v2와 v3의 가장 인기 있는 기능을 상세하게 비교합니다. 참조의 각 섹션은 개별적으로 읽어야 합니다. 이 참조 전체를 읽기보다는 각 사례에 따라 마이그레이션을 돕는 자료로 사용하는 것이 좋습니다.

  • 이벤트 - 이벤트 등록 및 처리.
  • 컨트롤 - 지도에 나타나는 내비게이션 컨트롤 조작.
  • 오버레이 - 지도에 객체 추가 및 편집.
  • 지도 유형 - 기본 지도를 구성하는 타일
  • 레이어 - KML이나 교통 계층 등과 같이 그룹으로 콘텐츠 추가 및 편집.
  • 서비스 - Google의 지오코딩, 길찾기, 스트리트 뷰 서비스 작업.

이벤트

Google Maps JavaScript API v3의 이벤트 모델은 v2와 유사하지만 자세히 들여다보면 v2에서 많은 변화가 있었습니다.

컨트롤

Google Maps JavaScript API는 사용자가 지도와 상호작용할 수 있는 UI 컨트롤을 표시합니다. API를 사용하여 컨트롤이 나타나는 모습을 사용자 지정할 수 있습니다.

오버레이

오버레이는 점이나 선, 영역, 객체 컬렉션을 지정하기 위해 지도에 "추가"하는 객체를 나타냅니다.

지도 유형

v2와 v3에서 사용할 수 있는 지도 유형은 다소 차이가 있지만 모든 기본 지도 유형은 두 API 버전에서 모두 사용할 수 있습니다. 기본적으로 v2는 "색이 칠해진" 표준 도로 지도 타일을 사용합니다. 그러나 v3는 google.maps.Map 객체를 생성할 때 특정 지도 유형을 지정해야 합니다.

계층

계층은 하나 이상의 오버레이로 구성된 지도상의 객체입니다. 하나의 유닛으로 조작할 수 있고 일반적으로는 객체 컬렉션을 나타냅니다.

서비스

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

이 페이지
문서에 대한 의견
Google Maps JavaScript API
Google Maps JavaScript API
제품에 대한 의견
도움이 필요하시나요? 지원 페이지를 방문하세요.