Maps JavaScript API 로드하기

이 가이드에서는 Maps JavaScript API를 로드하는 방법을 설명합니다. 다음 세 가지 방법을 사용할 수 있습니다.

동적 라이브러리 가져오기 사용

동적 라이브러리 가져오기는 런타임에 라이브러리를 로드하는 기능을 제공합니다. 이를 통해 로드 시 한 번에 모든 라이브러리를 요청하는 대신 필요할 때 필요한 라이브러리를 요청할 수 있습니다. 또한 페이지에서 Maps JavaScript API를 여러 번 로드하지 않도록 보호합니다.

다음 스니펫에 표시된 대로 애플리케이션 코드에 인라인 부트스트랩 로더를 추가하여 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",
    // Use the 'v' parameter to indicate the version to use (weekly, beta, alpha, etc.).
    // Add other bootstrap parameters as needed, using camel case.
  });
</script>

부트스트랩 로더 코드를 JavaScript 코드에 직접 추가할 수도 있습니다.

런타임 시 라이브러리를 로드하려면 await 연산자를 사용하여 async 함수 내에서 importLibrary()를 호출합니다. 필요한 클래스의 변수를 선언하면 다음 코드 예와 같이 정규화된 경로 (google.maps.Map 등)를 사용하지 않아도 됩니다.

let map;
async function initMap() {
    const { Map, RenderingType } = (await google.maps.importLibrary('maps'));
    map = new Map(document.getElementById('map'), {
        center: { lat: -34.397, lng: 150.644 },
        zoom: 8,
        renderingType: RenderingType.VECTOR,
    });
}
initMap();
index.js

함수는 필요한 클래스의 변수를 선언하지 않고도 라이브러리를 로드할 수 있습니다. 이는 gmp-map 요소를 사용하여 지도를 추가한 경우 특히 유용합니다. 변수가 없으면 정규화된 경로(예: google.maps.Map)를 사용해야 합니다.

let map;
let center =  { lat: -34.397, lng: 150.644 };

async function initMap() {
  await google.maps.importLibrary("maps");
  await google.maps.importLibrary("marker");

  map = new google.maps.Map(document.getElementById("map"), {
    center,
    zoom: 8,
    mapId: "DEMO_MAP_ID",
  });

  addMarker();
}

async function addMarker() {
  const marker = new google.maps.marker.AdvancedMarkerElement({
    map,
    position: center,
  });
}

initMap();

또는 다음과 같이 HTML에서 직접 라이브러리를 로드할 수 있습니다.

<script>
google.maps.importLibrary("maps");
google.maps.importLibrary("marker");
</script>

Dynamic Library Loading API로 이전하는 방법을 알아보세요.

필수 매개변수

  • key: API 키. 유효한 API 키가 지정되지 않는 한 Maps JavaScript API가 로드되지 않습니다.

선택적 매개변수

  • v: 로드할 Maps JavaScript API의 버전

  • libraries: 사전 로드를 시작할 추가 Maps JavaScript API 라이브러리의 배열입니다. 고정된 라이브러리 집합을 지정하는 것은 일반적으로 권장되지 않지만 웹사이트의 캐싱 동작을 세부적으로 조정하려는 개발자는 해당 집합을 지정할 수 있습니다. 사용하기 전에 선택한 각 라이브러리에 대해 google.maps.importLibrary()를 호출하는 것이 여전히 중요합니다.

  • language: 사용할 언어. 이 매개변수는 컨트롤의 이름, 저작권 고지, 운전 경로, 컨트롤 라벨, 서비스 요청에 대한 응답에 영향을 미칩니다. 지원 언어 목록을 참고하세요.

  • region: 사용할 지역 코드. 이 매개변수는 지정된 국가 또는 지역을 기반으로 API의 동작을 변경합니다.

  • authReferrerPolicy: 지도 JS 고객은 Cloud 콘솔에서 HTTP 리퍼러 제한사항을 구성하여 특정 API 키를 사용할 수 있는 URL을 제한할 수 있습니다. 기본적으로 이러한 제한사항은 특정 경로만 API 키를 사용하도록 구성할 수 있습니다. 동일한 도메인 또는 출처의 URL에서 API 키를 사용할 수 있는 경우 Maps JavaScript API의 요청을 승인할 때 전송되는 데이터의 양을 제한하도록 authReferrerPolicy: "origin"을 설정할 수 있습니다. 이 매개변수가 지정되고 Cloud 콘솔에서 HTTP 리퍼러 제한사항이 사용 설정된 경우 지정된 경로가 없이 현재 웹사이트의 도메인과 일치하는 HTTP 리퍼러 제한사항이 있을 때만 Maps JavaScript API를 로드할 수 있습니다.

  • mapIds: 지도 ID의 배열입니다. 지정된 지도 ID의 구성이 사전 로드되도록 합니다. 여기에서 지도 ID를 지정하는 것은 지도 ID 사용에 필요하지 않지만 네트워크 성능을 세부적으로 조정하려는 개발자는 지정할 수 있습니다.

  • channel: 채널별 사용량 추적을 참고하세요.

  • internalUsageAttributionIds: 마커 클러스터링 라이브러리 사용과 같이 개발자에게 유용한 라이브러리와 샘플을 Google에서 파악하는 데 도움이 되는 사용량 기여 ID의 배열입니다. 사용량 기여 ID 전송을 거부하려면 이 속성을 삭제하거나 값을 빈 배열 ([])로 설정해도 됩니다. 고유한 값만 전송됩니다. 자세한 내용은 Google Maps Platform 솔루션 매개변수 를 참고하세요.

직접 스크립트 로드 태그 사용

이 섹션에서는 직접 스크립트 로드 태그를 사용하는 방법을 보여줍니다. 직접 스크립트는 지도가 로드될 때 라이브러리를 로드하므로 런타임에 라이브러리를 명시적으로 요청할 필요가 없어 gmp-map 요소를 사용하여 만든 지도를 간소화할 수 있습니다. 직접 스크립트 로드 태그는 스크립트가 로드될 때 요청된 모든 라이브러리를 한 번에 로드하므로 일부 애플리케이션의 성능에 영향을 미칠 수 있습니다. 페이지 로드당 직접 스크립트 로드 태그를 한 번만 포함하세요.

스크립트 태그 추가

HTML 파일에 Maps JavaScript API 인라인을 로드하려면 아래와 같이 script 태그를 추가하세요.

<script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&loading=async&callback=initMap">
</script>

직접 스크립트 로드 URL 매개변수

이 섹션에서는 Maps JavaScript API를 로드할 때 스크립트 로드 URL의 쿼리 문자열에서 지정할 수 있는 모든 매개변수를 설명합니다. 일부 매개변수는 필수이고 일부는 선택사항입니다. URL에서와 마찬가지로 모든 매개변수는 앰퍼샌드 (&) 문자를 사용하여 구분합니다.

다음 URL 예에는 가능한 모든 매개변수에 대한 자리표시자가 있습니다.

https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY
&loading=async
&callback=FUNCTION_NAME
&v=VERSION
&libraries="LIBRARIES"
&language="LANGUAGE"
&region="REGION"
&auth_referrer_policy="AUTH_REFERRER_POLICY"
&map_ids="MAP_IDS"
&channel="CHANNEL"
&solution_channel="SOLUTION_IDENTIFIER"

다음 script 태그 예의 URL은 Maps JavaScript API를 로드합니다.

<script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&loading=async&callback=initMap">
</script>

필수 매개변수 (직접) {:.hide-from-toc}

Maps JavaScript API를 로드할 때는 다음 매개변수가 필요합니다.

  • key: API 키. 유효한 API 키가 지정되지 않는 한 Maps JavaScript API가 로드되지 않습니다.

선택적 매개변수 (직접) {:.hide-from-toc}

특정 버전의 Maps JavaScript API를 요청하거나 추가 라이브러리를 로드하거나 지도를 현지화하거나 HTTP 리퍼러 확인 정책을 지정하려면 다음 매개변수를 사용하세요.

  • loading: Maps JavaScript API에서 사용할 수 있는 코드 로드 전략입니다. Maps JavaScript API가 동기식으로 로드되지 않았으며 스크립트의 load 이벤트에 의해 JavaScript 코드가 트리거되지 않음을 나타내려면 async로 설정합니다. 성능 향상을 위해 가능한 경우 이 값을 async로 설정하는 것이 좋습니다. (Maps JavaScript API를 사용할 수 있을 때 작업을 실행하려면 callback 매개변수를 대신 사용하세요.) 버전 3.55부터 사용할 수 있습니다.

  • callback: Maps JavaScript API가 완전히 로드되면 호출할 전역 함수의 이름입니다.

  • v: 사용할 Maps JavaScript API의 버전입니다.

  • libraries: 로드할 추가 Maps JavaScript API 라이브러리의 쉼표로 구분된 목록입니다.

  • language: 사용할 언어입니다. 이 매개변수는 컨트롤의 이름, 저작권 고지, 운전 경로, 컨트롤 라벨 및 서비스 요청에 대한 응답에 영향을 미칩니다. 지원 언어 목록을 참고하세요.

  • region: 사용할 지역 코드입니다. 이 매개변수는 지정된 국가 또는 지역을 기반으로 API의 동작을 변경합니다.

  • auth_referrer_policy: 고객은 Cloud 콘솔에서 HTTP 리퍼러 제한사항을 구성하여 특정 API 키를 사용할 수 있는 URL을 제한할 수 있습니다. 기본적으로 이러한 제한사항은 특정 경로만 API 키를 사용하도록 구성할 수 있습니다. 동일한 도메인 또는 출처의 URL에서 API 키를 사용할 수 있는 경우 Maps JavaScript API의 요청을 승인할 때 전송되는 데이터의 양을 제한하도록 auth_referrer_policy=origin을 설정할 수 있습니다. 이 기능은 버전 3.46부터 사용할 수 있습니다. 이 매개변수가 지정되고 Cloud 콘솔에서 HTTP 리퍼러 제한사항이 사용 설정된 경우 지정된 경로가 없이 현재 웹사이트의 도메인과 일치하는 HTTP 리퍼러 제한사항 이 있을 때만 Maps JavaScript API를 로드할 수 있습니다.

  • map_ids: 지도 ID의 쉼표로 구분된 목록입니다. 지정된 지도 ID의 구성이 사전 로드되도록 합니다. 여기에서 지도 ID를 지정하는 것은 지도 ID 사용에 필요하지 않지만 네트워크 성능을 세부적으로 조정하려는 개발자는 지정할 수 있습니다.

  • channel: 채널별 사용량 추적을 참고하세요.

  • internal_usage_attribution_ids: 마커 클러스터링 라이브러리 사용과 같이 개발자에게 유용한 라이브러리와 샘플을 Google에서 파악하는 데 도움이 되는 사용량 기여 ID의 쉼표로 구분된 목록입니다. 사용량 기여 ID 전송을 거부하려면 이 속성을 삭제하거나 값을 빈 문자열로 바꿔도 됩니다. 고유한 값만 전송됩니다. 자세한 내용은 Google Maps Platform 솔루션 매개변수 를 참고하세요.

NPM js-api-loader 패키지 사용

@googlemaps/js-api-loader 패키지는 NPM 패키지 관리자를 사용하여 로드할 수 있습니다. 다음 명령어를 사용하여 설치합니다.

npm install @googlemaps/js-api-loader

여기에 표시된 대로 패키지를 가져옵니다.

import { setOptions, importLibrary } from "@googlemaps/js-api-loader"

로더는 프로미스를 사용하여 라이브러리를 사용할 수 있도록 합니다. importLibrary() 메서드를 사용하여 라이브러리를 로드합니다. 다음 예에서는 로더를 사용하여 지도를 로드하는 방법을 보여줍니다.

TypeScript

// Import the needed libraries.
import { setOptions, importLibrary } from '@googlemaps/js-api-loader';

const API_KEY = 'AIzaSyA6myHzS10YXdcazAFalmXvDkrYCp5cLc8';

async function initMap(): Promise<void> {
    // Set loader options.
    setOptions({
        key: API_KEY,
        v: 'weekly',
    });

    // Load the Maps library.
    const { Map } = (await importLibrary('maps'));

    // Set map options.
    const mapOptions = {
        center: { lat: 48.8566, lng: 2.3522 },
        zoom: 3,
    };

    // Declare the map.
    const map = new Map(
        document.getElementById('map') as HTMLElement,
        mapOptions
    );
}

initMap();
index.ts

JavaScript

// Import the needed libraries.
import { setOptions, importLibrary } from '@googlemaps/js-api-loader';
const API_KEY = 'AIzaSyA6myHzS10YXdcazAFalmXvDkrYCp5cLc8';
async function initMap() {
    // Set loader options.
    setOptions({
        key: API_KEY,
        v: 'weekly',
    });
    // Load the Maps library.
    const { Map } = (await importLibrary('maps'));
    // Set map options.
    const mapOptions = {
        center: { lat: 48.8566, lng: 2.3522 },
        zoom: 3,
    };
    // Declare the map.
    const map = new Map(document.getElementById('map'), mapOptions);
}
initMap();
index.js

전체 예시 코드를 참고하세요.

Dynamic Library Import API로 이전

이 섹션에서는 Dynamic Library Import API를 사용하기 위해 통합을 이전하는 데 필요한 단계를 설명합니다.

이전 단계

첫째, 직접 스크립트 로드 태그를 인라인 부트스트랩 로더 태그로 바꿉니다.

변경 전

<script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&loading=async&libraries=maps&callback=initMap">
</script>

변경 후

<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",
    // Use the 'v' parameter to indicate the version to use (weekly, beta, alpha, etc.).
    // Add other bootstrap parameters as needed, using camel case.
  });
</script>

그런 다음 애플리케이션 코드를 업데이트합니다.

  • initMap() 함수를 비동기식으로 변경합니다.
  • importLibrary()를 호출하여 필요한 라이브러리를 로드하고 액세스합니다.

변경 전

let map;

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

window.initMap = initMap;

변경 후

let map;
// initMap is now async
async function initMap() {
    // Request libraries when needed, not in the script tag.
    const { Map } = await google.maps.importLibrary("maps");
    // Short namespaces can be used.
    map = new Map(document.getElementById("map"), {
        center: { lat: -34.397, lng: 150.644 },
        zoom: 8,
    });
}

initMap();