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()를 호출합니다.

TypeScript

let map: google.maps.Map;
async function initMap(): Promise<void> {
  const { Map } = await google.maps.importLibrary("maps") as google.maps.MapsLibrary;
  map = new Map(document.getElementById("map") as HTMLElement, {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
}

initMap();
index.ts

JavaScript

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

필수 매개변수

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

선택적 매개변수

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

  • libraries: 로드할 추가 Maps JavaScript API 라이브러리의 쉼표로 구분된 목록. 고정된 라이브러리 집합을 지정하는 것은 일반적으로 권장되지 않지만 웹사이트의 캐싱 동작을 세부적으로 조정하려는 개발자는 해당 집합을 지정할 수 있습니다.

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

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

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

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

NPM js-api-loader 패키지 사용

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

npm install @googlemaps/js-api-loader

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

import { Loader } from "@googlemaps/js-api-loader"

로더는 프로미스 및 콜백 인터페이스를 표시합니다. 다음 예는 기본 프로미스 메서드 load()의 사용 방법을 보여줍니다.

TypeScript

const loader = new Loader({
  apiKey: "YOUR_API_KEY",
  version: "weekly",
  ...additionalOptions,
});

loader.load().then(async () => {
  const { Map } = await google.maps.importLibrary("maps") as google.maps.MapsLibrary;
  map = new Map(document.getElementById("map") as HTMLElement, {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
});
index.ts

JavaScript

const loader = new Loader({
  apiKey: "YOUR_API_KEY",
  version: "weekly",
  ...additionalOptions,
});

loader.load().then(async () => {
  const { Map } = await google.maps.importLibrary("maps");

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

index.js

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

기존 스크립트 로드 태그 사용

기존 스크립트 로드 태그는 계속 지원됩니다. 이 섹션은 기존 스크립트 로드 태그를 사용한 통합을 지원하기 위해 제공되었습니다. Dynamic Library Loading API로 이전하는 것이 좋습니다.

스크립트 태그 추가

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

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

기존 스크립트를 로드하는 URL 매개변수

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

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

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

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

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

필수 매개변수(기존)

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

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

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

선택사항인 매개변수(기존)

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

  • v: 사용할 Maps JavaScript API의 버전

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

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

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

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

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

Dynamic Library Import API로 이전

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

이전을 위한 단계

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

변경 전

<script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&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();