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 } = await google.maps.importLibrary("maps");

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

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: 채널별 사용량 추적을 참고하세요.

  • solutionChannel: Google Maps Platform에서는 빠른 구현을 위해 다양한 종류의 샘플 코드를 제공합니다. 더 복잡한 코드 샘플의 채택을 추적하고 솔루션 품질을 개선하기 위해 Google은 샘플 코드의 API 호출에 solutionChannel 쿼리 매개변수를 포함합니다.

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

이 섹션에서는 직접 스크립트 로드 태그를 사용하는 방법을 보여줍니다. 직접 스크립트는 지도가 로드될 때 라이브러리를 로드하므로 런타임에 라이브러리를 명시적으로 요청할 필요가 없어 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를 로드할 수 있습니다.

  • mapIds: 쉼표로 구분된 지도 ID 목록입니다. 지정된 지도 ID의 구성이 미리 로드되도록 합니다. 여기에서 지도 ID를 지정하는 것은 지도 ID 사용에 필요하지 않지만 네트워크 성능을 미세 조정하려는 개발자에게는 유용합니다.

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

  • solution_channel: Google Maps Platform에서는 빠른 구현을 위해 다양한 종류의 샘플 코드를 제공합니다. 더 복잡한 코드 샘플의 채택을 추적하고 솔루션 품질을 개선하기 위해 Google은 샘플 코드의 API 호출에 solution_channel 쿼리 매개변수를 포함합니다.

NPM js-api-loader 패키지 사용

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

npm install @googlemaps/js-api-loader

이 패키지는 다음 코드를 사용하여 애플리케이션으로 가져올 수 있습니다.

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

로더는 Promise를 사용하여 라이브러리를 사용할 수 있도록 합니다. 라이브러리는 importLibrary() 메서드로 로드됩니다. 다음 예에서는 Map 클래스를 로드합니다.

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

setOptions({
  apiKey: "YOUR_API_KEY",
  version: "weekly",
});

importLibrary("maps").then(({ Map }) => {
  new Map(document.getElementById("map"), {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
}).catch(e => {
  // do something
});

비동기 함수에서 async/await를 사용할 수도 있습니다. 이 예시에서는 추가 라이브러리를 로드합니다.

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

setOptions({
  apiKey: "YOUR_API_KEY",
  version: "weekly",
});

const { Map } = await importLibrary("maps");
const { AdvancedMarkerElement } = await importLibrary("marker");
const map = new Map(document.getElementById("map"), {
  center: { lat: -34.397, lng: 150.644 },
  zoom: 8,
});
const marker = new AdvancedMarkerElement({
  map,
  position: { lat: -34.397, lng: 150.644 },
});
const { PlaceAutocompleteElement } = await importLibrary("places");
await google.maps.importLibrary("places");
const placeAutocomplete = new google.maps.places.PlaceAutocompleteElement();
document.body.append(placeAutocomplete);

js-api-loader가 포함된 샘플을 참고하세요.

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();