공지사항: 새로운 기본 지도 스타일이 곧 Google Maps Platform에 제공될 예정입니다. 이 지도 스타일 지정 업데이트에는 새로운 기본 색상 팔레트, 현대화된 핀, 지도 환경 및 사용성 개선사항이 포함됩니다. 모든 지도 스타일이 2025년 3월에 자동으로 업데이트됩니다. 사용 가능 여부 및 더 일찍 선택하는 방법에 대한 자세한 내용은 Google Maps Platform용 새로운 지도 스타일을 참고하세요.

이 페이지는 Cloud Translation API를 통해 번역되었습니다.

버전 관리

Maps JavaScript API팀은 새로운 기능, 버그 수정, 성능 개선사항을 반영하여 API를 정기적으로 업데이트합니다. 이 페이지에서는 애플리케이션에서 사용할 수 있는 API의 버전을 설명합니다.

출시 채널 및 버전 번호

애플리케이션에 다음 방법으로 출시 채널 또는 버전 번호를 지정할 수 있습니다.

주간 채널은 v=weekly로 지정됩니다.
이 채널은 일주일에 한 번 업데이트되며 최신 버전입니다.
분기별 채널은 v=quarterly로 지정됩니다.
이 채널은 분기에 한 번 업데이트되며 예상하기가 가장 쉽습니다.
베타 채널은 v=beta로 지정됩니다.
이 채널은 weekly 채널을 기반으로 하며 일주일에 한 번 업데이트됩니다. 여기에는 초기 테스트 및 의견 제공을 위한 추가 변경사항이 포함됩니다.
알파 채널은 v=alpha로 지정됩니다.
이 채널은 beta 채널을 기반으로 하며 일주일에 한 번 업데이트됩니다. 여기에는 프로토타입에 대한 고객 의견을 위한 실험이 포함됩니다. 개발 전용이며 프로덕션에 사용해서는 안 됩니다.
버전 번호는 v=n.nn으로 지정됩니다.
v=3.59, v=3.58, v=3.57 또는 v=3.56을 선택할 수 있습니다.
버전 번호는 분기에 한 번 업데이트됩니다(분기별 업데이트 참고).

채널이나 버전을 명시적으로 지정하지 않으면 기본적으로 주간 채널이 제공됩니다. 프리미엄 플랜에서 이전했고 채널이나 버전을 명시적으로 지정하지 않은 경우 기본적으로 분기별 채널이 제공됩니다. 잘못된 버전을 지정하면 기본 채널이 제공됩니다.

주간 채널 선택

대부분 애플리케이션의 경우 주간 채널이 권장됩니다. 주간 채널이 가장 최신 버전이며 최신 버그 수정 및 성능 개선사항이 포함됩니다. 다음 스크립트 태그로 Maps JavaScript API를 로드하여 주간 채널을 지정할 수 있습니다.

  <script>
    (g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})({
      key: "YOUR_API_KEY",
      v: "weekly",
    });
  </script>

현재 주간 채널은 버전 3.59입니다. 이 버전은 매주 새로운 기능, 버그 수정, 성능 개선사항을 반영하여 업데이트됩니다.

2월 중순에 주간 채널이 버전 3.60으로 업데이트됩니다. 이때 새 버전에서 지원 중단된 기능이 삭제되거나 이전 버전과의 비호환성 문제가 발생할 수 있습니다.

분기별 채널 선택

일부 애플리케이션의 경우 업데이트의 빈도는 적지만 한번에 큰 업데이트가 진행되는데, 이 경우 예측 가능성이 더 높다는 이점이 있습니다. 이러한 애플리케이션에서는 분기별 채널을 사용해야 합니다. 예상되는 시점에 버그 수정 및 성능 개선사항을 받으려면 이 방법을 사용하세요(분기별 업데이트 참고). 다음 스크립트 태그로 Maps JavaScript API를 로드하여 분기별 채널을 지정할 수 있습니다.

  <script>
  (g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})({
    key: "YOUR_API_KEY",
    v: "quarterly",
  });
  </script>

현재 분기별 채널은 버전 3.58입니다. 분기 중에는 이 버전에 새로운 기능, 버그 수정 또는 성능 개선사항이 추가되지 않습니다. 이 버전에 보안 버그 수정이 때때로 포함될 수 있습니다.

2월 중순에 분기별 채널이 버전 3.59로 업데이트됩니다. 새 버전에서는 새 기능이 추가되고 지원 중단된 기능이 삭제되거나 지난 3개월 동안의 버전과 비호환성 문제가 발생할 수 있습니다.

2월 초에 v=3.59을 사용하여 애플리케이션을 테스트하시기 바랍니다.

베타 채널 선택

베타 채널을 통해 새로운 베타 기능 및 변경사항을 이용해 보세요. 베타 기능은 완전한 기능을 갖추고 있지만 해결되지 않은 문제가 있을 수 있습니다(Issue Tracker를 사용하여 문제를 신고하고 의견을 제공하세요). 베타 채널에는 SLA 또는 지원 중단 정책이 적용되지 않으며 일부 변경사항은 이전 버전과 호환되지 않을 수도 있습니다.

이 채널은 weekly 채널을 기반으로 하며 일주일에 한 번 업데이트됩니다.

다음 스크립트 태그로 Maps JavaScript API를 로드하여 베타 채널을 지정할 수 있습니다.

  <script>
  (g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})({
    key: "YOUR_API_KEY",
    v: "beta",
  });
  </script>

알파 채널 선택

알파 채널을 통해 새로운 실험용 기능과 변경사항을 이용해 보세요. Issue Tracker를 사용하여 문제를 신고하고 의견을 제공하세요. 알파 채널에는 SLA 또는 지원 중단 정책이 적용되지 않으며 일부 변경사항은 이전 버전과 호환되지 않을 수도 있습니다. 개발 전용이며 프로덕션에 사용해서는 안 됩니다.

이 채널은 beta 채널을 기반으로 하며 일주일에 한 번 업데이트됩니다.

다음 스크립트 태그로 Maps JavaScript API를 로드하여 알파 채널을 지정할 수 있습니다.

  <script>
  (g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})({
    key: "YOUR_API_KEY",
    v: "alpha",
  });
  </script>

버전 번호 선택

애플리케이션을 정기적으로 테스트하고 업데이트하는 경우에만 번호로 버전을 지정하세요. 번호가 매겨진 버전은 매 분기 새 버전이 생성될 때 삭제되기 때문입니다. 다음 스크립트 태그로 Maps JavaScript API를 로드하여 버전 번호를 지정할 수 있습니다.

  <script>
  (g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})({
    key: "YOUR_API_KEY",
    v: 3.58,
  });
  </script>

현재 v=3.59, v=3.58, v=3.57 또는 v=3.56을 지정할 수 있습니다.

버전 3.59에는 새로운 기능, 버그 수정, 성능 개선사항이 반영된 주간 업데이트가 추가됩니다.
버전 3.58에는 주간 업데이트가 추가되지 않습니다.
버전 3.57에는 주간 업데이트가 추가되지 않습니다.
버전 3.56에는 주간 업데이트가 추가되지 않습니다.
이 버전에 보안 버그 수정이 때때로 포함될 수 있습니다.
새 버전을 만들 때 이전 버전과 더 이상 호환되지 않는 변경사항이 포함될 수 있습니다.

2월 중순 이후에는 v=3.60, v=3.59, v=3.58 또는 v=3.57를 지정할 수 있습니다.

버전 3.60에는 새로운 기능, 버그 수정, 성능 개선사항이 반영된 주간 업데이트가 추가됩니다.
버전 3.59에는 더 이상 주간 업데이트가 추가되지 않습니다.
버전 3.58에는 더 이상 주간 업데이트가 추가되지 않습니다.
버전 3.57에는 더 이상 주간 업데이트가 추가되지 않습니다.
이 버전에 보안 버그 수정이 때때로 포함될 수 있습니다.
버전 3.56은 더 이상 사용할 수 없습니다. 이 버전을 로드하려고 하면 무시되고 대신 기본 채널이 제공됩니다.

v=3.57 또는 v=3.56을 사용 중인 경우 2월 중순 이전에 v=3.59 또는 v=3.58으로 업그레이드하시기 바랍니다. 최신 버전으로 전환하면 지원 중단된 기능이 삭제되거나 이전 버전과 더 이상 호환되지 않을 수도 있습니다.

아래 다이어그램에는 내년에 각 채널에서 사용할 수 있는 버전이 나와 있습니다.

업데이트가 내 애플리케이션에 영향을 미침

출시 채널을 업데이트할 때 애플리케이션이 영향을 받을 수 있습니다. 이 문제는 애플리케이션이 문서화되지 않았거나 지원 중단된 기능을 사용하기 때문에 또는 버그 발생이나 버그 수정으로 인해 발생할 수 있습니다.

임시 해결 방법으로 이전 버전을 사용하도록 애플리케이션을 재구성할 수 있습니다.

브라우저 개발자 도구에서 콘솔을 열고 google.maps.version의 값을 확인합니다.
API를 로드하는 스크립트 태그를 업데이트하고 이전 버전 번호를 요청합니다.
예를 들어 google.maps.version이 '3.59.2'이면 스크립트 태그에 v=3.58를 사용합니다.
이 임시 해결 방법은 제한된 기간 동안만 작동합니다.

임시 해결 방법을 적용하고 난 후 애플리케이션을 업데이트할 시간(일반적으로 3~6개월)이 제공되므로, 문서화되지 않았거나 지원 중단된 기능을 사용하지 않도록 업데이트하고 버그나 버그 수정을 반영할 수 있습니다.

그런 다음 원본 스크립트 태그로 되돌려 API를 로드해야 합니다.

지원 케이스를 만들거나 문제를 신고할 수도 있습니다.

분기별 업데이트

Maps JavaScript API팀은 분기에 한 번 새 버전을 출시합니다. 2월 중순, 5월 중순, 8월 중순, 11월 중순에 새 버전이 출시됩니다. 다음 업데이트는 2월 중순에 출시됩니다. 새 주간 채널은 버전 3.60을 제공할 예정이며 그때 다른 채널도 업데이트됩니다.

주간 채널 업데이트

주간 채널은 현재 버전 3.59입니다.

2월 중순에 주간 채널이 버전 3.59에서 버전 3.60으로 업데이트됩니다. 새 버전에서는 새 기능이 추가되고 지원 중단된 기능이 삭제되거나 이전 버전과의 비호환성 문제가 발생할 수 있습니다. 채널이 업데이트되면 이러한 변경사항을 테스트해야 할 수도 있습니다.

분기 동안 새 버전은 매주 새로운 기능, 버그 수정, 성능 개선사항을 반영하여 업데이트됩니다. 지원 중단된 기능은 삭제되지 않으며 이전 버전과의 호환성 문제가 발생하지 않습니다.

분기별 채널 업데이트

현재 분기별 버전은 버전 3.58입니다.

2월 중순에 분기별 채널이 버전 3.58에서 버전 3.59로 업데이트됩니다. 업데이트가 완료되면 이 버전에서 새 기능이 추가되고 지원 중단된 기능이 삭제되거나 지난 3개월 동안의 버전과 비호환성 문제가 발생할 수 있습니다. 채널이 업데이트되면 이러한 변경사항을 테스트해야 할 수도 있습니다.

분기 동안 이 버전에는 새로운 기능, 버그 수정 또는 성능 개선사항이 포함되지 않습니다. 지원 중단된 기능은 삭제되지 않으며 이전 버전과의 호환성 문제가 발생하지 않습니다.

버전 업데이트

2월 중순에 버전 번호가 새 버전의 출시를 반영하여 이월됩니다.

버전 3.60

2월 중순에 새 버전 3.60이 출시됩니다. 출시가 완료되면 이 버전에 새 기능이 추가되고 지원 중단된 기능이 삭제되거나 버전 3.59와의 비호환성 문제가 발생할 수 있습니다. 버전 번호를 변경할 때는 애플리케이션을 테스트해야 합니다.

버전 3.59

이 버전에는 새 기능이 추가되고 지원 중단된 기능이 삭제되거나 버전 3.58과의 비호환성 문제가 발생할 수 있습니다. 버전 번호를 변경할 때는 애플리케이션을 테스트해야 합니다.

2월 중순 이후 이 버전은 더 이상 새로운 기능, 버그 수정 또는 성능 개선사항을 반영하여 업데이트되지 않습니다. 지원 중단된 기능은 삭제되지 않으며 이전 버전과의 호환성 문제가 발생하지 않습니다.

버전 3.58

이 버전에는 새 기능이 추가되고 지원 중단된 기능이 삭제되거나 버전 3.57과의 비호환성 문제가 발생할 수 있습니다. 버전 번호를 변경할 때는 애플리케이션을 테스트해야 합니다.

이 버전은 더 이상 새로운 기능, 버그 수정 또는 성능 개선사항을 반영하여 업데이트되지 않습니다. 이 버전 이후에 지원 중단된 기능은 삭제되지 않으며 이전 버전과의 새로운 비호환성 문제가 발생하지 않습니다.

버전 3.57

이 버전에는 새 기능이 추가되고 지원 중단된 기능이 삭제되거나 버전 3.56과의 비호환성 문제가 발생할 수 있습니다. 버전 번호를 변경할 때는 애플리케이션을 테스트해야 합니다.

버전 3.56

2월 중순 이후 이 버전은 삭제되며 더 이상 사용할 수 없습니다. 이 버전을 로드하려고 하면 무시되고 대신 기본 채널이 제공됩니다.

버전 지원

한 분기에 네 개의 버전을 사용할 수 있습니다. 이 네 버전이 모두 지원됩니다.

버전 확인

디버깅의 경우 google.maps.version 속성을 사용하여 애플리케이션에서 Maps JavaScript API의 현재 버전을 가져옵니다. 다음 코드 샘플은 브라우저 콘솔에 API 버전을 씁니다. 브라우저 콘솔에 관한 자세한 내용은 브라우저에서 오류 확인 가이드를 참고하세요.

<!DOCTYPE html>
<html>
  <head>
    <title>Display Google Maps API Version</title>
  </head>
  <body>
    <script>
      function initMap() {
        // Add your map here.
        console.log('Google Maps API version: ' + google.maps.version);
      }
    </script>
    <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap"
    defer></script>
  </body>
</html>

API 버전 관련 문서

개발자 가이드에서는 항상 주간 버전을 설명합니다.

또한 버전마다 별도로 관리되는 참조가 있습니다.

버전 3.59 API 참조 (주간 채널)
버전 3.58 API 참조 (분기별 채널)
버전 3.57 API 참조
버전 3.56 API 참조
버전 3.0~3.55는 삭제되었습니다.