개요

플랫폼 선택: Android iOS 자바스크립트

Maps JavaScript API를 사용하면 웹페이지와 휴대기기에 표시할 자신만의 콘텐츠와 이미지를 사용하여 지도를 맞춤설정할 수 있습니다. Maps JavaScript API는 레이어와 스타일, 컨트롤과 이벤트, 다양한 서비스와 라이브러리를 사용하여 수정할 수 있는 네 가지 기본 지도 유형(도로 지도, 위성, 하이브리드, 지형)을 표시합니다.

대상

이 문서는 자바스크립트 프로그래밍 및 객체 지향 프로그래밍 개념에 익숙한 개발자를 위해 작성되었습니다. 개발자는 사용자의 입장에서 지도를 사용할 줄도 알아야 합니다. 웹에서 다양한 자바스크립트 튜토리얼을 찾을 수 있습니다.

이 문서는 Maps JavaScript API를 사용하여 신속하게 애플리케이션을 연구하고 개발할 수 있도록 작성되었습니다. Maps JavaScript API 참조도 게시됩니다.

Hello, World

Maps JavaScript API에 대해 가장 쉽게 배우는 방법은 간단한 예를 보는 것입니다. 다음 예는 오스트레일리아 뉴사우스웨일스의 시드니를 중심으로 하는 지도를 표시합니다.

TypeScript

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

initMap();

JavaScript

let map;

async function initMap() {
  //@ts-ignore
  const { Map } = await google.maps.importLibrary("maps");

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

initMap();

CSS

/*
 * Always set the map height explicitly to define the size of the div element
 * that contains the map.
 */
#map {
  height: 100%;
}

/*
 * Optional: Makes the sample page fill the window.
 */
html,
body {
  height: 100%;
  margin: 0;
  padding: 0;
}

HTML

<html>
  <head>
    <title>Simple Map</title>
    <script src="https://polyfill.io/v3/polyfill.min.js?features=default"></script>

    <link rel="stylesheet" type="text/css" href="./style.css" />
    <script type="module" src="./index.js"></script>
  </head>
  <body>
    <div id="map"></div>

    <!-- prettier-ignore -->
    <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: "AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg", v: "weekly"});</script>
  </body>
</html>
예 보기

샘플 사용해 보기

간단한 예시이지만 다음의 작업이 필요합니다.

  1. <!DOCTYPE html> 선언을 사용하여 애플리케이션을 HTML5로 선언합니다.
  2. 지도를 보관할 'map'이라는 div 요소를 만듭니다.
  3. div에서 지도를 만드는 자바스크립트 함수를 정의합니다.
  4. 부트스트랩 로더를 사용하여 Maps JavaScript API를 로드합니다.

이 단계는 아래에 설명되어 있습니다.

Maps JavaScript API 로드하기

부트스트랩 로더는 Maps JavaScript API를 로드하는 데 권장되는 방법입니다. JS 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_HERE",
    // Add other bootstrap parameters as needed, using camel case.
    // Use the 'v' parameter to indicate the version to load (alpha, beta, weekly, etc.)
  });
</script>

런타임 시 라이브러리를 로드하려면 다음과 같이 await 연산자를 사용하여 비동기 함수 내에서 importLibrary()를 호출합니다.

TypeScript

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

initMap();

JavaScript

let map;

async function initMap() {
  //@ts-ignore
  const { Map } = await google.maps.importLibrary("maps");

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

initMap();

NPM js-api-loader 패키지

NPM을 사용하여 Maps JavaScript API를 로드하려면 @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,
  });
});

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,
  });
});

애플리케이션을 HTML5로 선언

웹 애플리케이션 내에서 실제 DOCTYPE을 선언하는 것이 좋습니다. 이 예에서는 아래에 표시된 것처럼 간단한 HTML5 DOCTYPE을 사용하여 애플리케이션을 HTML5로 선언했습니다.

<!DOCTYPE html>

대부분의 최신 브라우저에서는 '표준 모드'에서 이 DOCTYPE을 사용하여 선언된 콘텐츠를 렌더링합니다. 즉 애플리케이션의 브라우저 간 호환성이 더 높아집니다. 또한 DOCTYPE은 성능 저하를 매끄럽게 처리하도록 설계되어, DOCTYPE을 인식하지 못하는 브라우저는 이를 무시하고 '쿼크 모드'를 사용하여 콘텐츠를 표시합니다.

쿼크 모드에서 작동하는 일부 CSS는 표준 모드에서 유효하지 않습니다. 특히 모든 백분율 기반 크기는 상위 블록 요소에서 상속해야 하며 상위 요소에서 크기를 지정하지 못하면 0x0픽셀로 간주됩니다. 이러한 이유로 다음과 같은 <style> 선언이 포함됩니다.

<style>
  #map {
    height: 100%;
  }
  html, body {
    height: 100%;
    margin: 0;
    padding: 0;
  }
</style>

이 CSS 선언은 지도 컨테이너 <div>(ID: map)가 HTML 본문 높이의 100%를 차지해야 한다는 것을 나타냅니다. <body><html>에 대한 백분율도 명시적으로 선언해야 합니다.

Maps JavaScript API 로드

Maps JavaScript API는 script 태그를 사용하여 로드되며 이 태그는 HTML 파일에 인라인으로 추가하거나 별도의 자바스크립트 파일을 사용하여 동적으로 추가할 수 있습니다. 두 접근 방식을 모두 검토하여 프로젝트에서 코드가 구조화되는 방식에 가장 적합한 접근 방식을 선택하는 것이 좋습니다.

인라인 로드

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

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

동적 로드

별도의 자바스크립트 파일을 사용하여 Maps JavaScript API를 인라인으로 동적으로 로드하려면 아래 예를 참고하세요. 이 접근 방식을 사용하면 별도의 .js 파일에서 API를 사용하기 위한 모든 코드를 처리할 수 있으며, 이는 스크립트 태그를 인라인으로 추가하는 것과 같습니다.

// Create the script tag, set the appropriate attributes
var script = document.createElement('script');
script.src = 'https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap';
script.async = true;

// Attach your callback function to the `window` object
window.initMap = function() {
  // JS API is loaded and available
};

// Append the 'script' element to 'head'
document.head.appendChild(script);
      

동적 로드

@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,
  });
});

자바스크립트

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,
  });
});

스크립트 태그 속성

위 예에서 script 태그에 설정되어 있는 여러 속성을 사용하시기 바랍니다. 다음은 각 속성에 관한 설명입니다.

  • src: Maps JavaScript API를 사용하는 데 필요한 모든 기호와 정의를 포함하여 Maps JavaScript API가 로드되는 URL입니다. 이 예의 URL에는 API 키를 제공하는 key와 Maps JavaScript API가 완전히 로드되면 호출할 전역 함수의 이름을 지정하는 callback, 두 개의 매개변수가 있습니다. URL 매개변수에 대해 자세히 알아보세요.
  • async: 브라우저에 스크립트를 비동기식으로 다운로드하고 실행하도록 요청합니다. 스크립트가 실행되면 callback 매개변수를 사용하여 지정된 함수를 호출합니다.

라이브러리

URL을 통해 Maps JavaScript API를 로드할 때 await 연산자를 사용하여 비동기 함수 내에서 importLibrary()를 호출하여 라이브러리를 추가로 로드할 수도 있습니다. 라이브러리는 기본 Maps JavaScript API에 추가 기능을 제공하는 코드의 모듈이지만 명시적으로 요청하지 않는 한 로드되지 않습니다. 자세한 내용은 Maps JavaScript API의 라이브러리를 참고하세요.

지도 DOM 요소

<div id="map"></div>

웹페이지에 지도를 표시하려면 표시할 자리를 예약해야 합니다. 일반적으로 이름이 지정된 div 요소를 만들고 브라우저의 DOM(문서 객체 모델)에서 이 요소에 대한 참조를 얻는 방식으로 자리를 예약합니다.

위의 예에서는 CSS를 사용하여 지도 div의 높이를 '100%'로 설정했습니다. 이렇게 하면 휴대기기의 크기에 맞게 확장됩니다. 브라우저의 화면 크기와 패딩에 따라 너비와 높이를 조정해야 할 수도 있습니다. 일반적으로 div는 포함된 요소에서 너비를 가져오고 비어 있는 div는 대개 높이가 0입니다. 이러한 이유로 항상 <div>에 높이를 명시적으로 설정해야 합니다.

지도 옵션

모든 지도에는 centerzoom, 두 가지 필수 옵션이 있습니다.

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

확대/축소 수준

지도를 표시하는 초기 해상도는 zoom 속성으로 설정되며, 여기서 0은 완전히 축소된 지구의 지도에 해당하며 확대/축소 수준이 높을수록 높은 해상도로 확대됩니다.

zoom: 8

지구 전체의 지도를 단일 이미지로 제공하려면 거대한 지도 또는 해상도가 매우 낮은 작은 지도가 필요합니다. 따라서 Google 지도 및 Maps JavaScript API 내 지도 이미지는 지도 '타일'과 '확대/축소 수준'으로 나누어져 있습니다. 확대/축소 수준이 낮을 때는 적은 수의 지도 타일로 넓은 영역을 커버하고, 확대/축소 수준이 높을수록 고해상도 타일로 더 좁은 영역을 커버합니다. 아래의 목록에는 각 확대/축소 단계의 대략적인 세밀한 정도가 나와 있습니다.

  • 1: 세계
  • 5: 대륙
  • 10: 도시
  • 15: 거리
  • 20: 건물

다음 세 이미지는 도쿄의 동일한 장소를 확대/축소 수준 0, 7, 18로 나타낸 것입니다.

Maps JavaScript API에서 현재 확대/축소 수준을 기반으로 지도를 로드하는 방법에 대한 자세한 내용은 지도 및 타일 좌표 가이드를 참고하세요.

지도 객체

map = new Map(document.getElementById("map"), {...});

지도를 나타내는 자바스크립트 클래스는 Map 클래스입니다. 이 클래스의 객체는 한 페이지에서 하나의 지도를 정의합니다. (이 클래스의 인스턴스를 두 개 이상 만들 수 있습니다. 각 객체는 페이지에서 별도의 지도를 정의합니다.) 자바스크립트 new 연산자를 사용하여 이 클래스의 새 인스턴스를 만듭니다.

새 지도 인스턴스를 만들 때 페이지의 <div> HTML 요소를 지도의 컨테이너로 지정합니다. HTML 노드는 자바스크립트 document 객체의 하위 노드이며 document.getElementById() 메서드를 통해 이 요소에 대한 참조를 가져올 수 있습니다.

이 코드는 map이라는 변수를 정의하고 이 변수를 새 Map 객체에 할당합니다. Map() 함수는 생성자라고 하며 다음과 같이 정의됩니다.

생성자 설명
Map(mapDiv:Node, opts?:MapOptions ) 전달되는 매개변수(선택사항)를 사용하여 지정된 HTML 컨테이너(일반적으로 DIV 요소) 내부에 새로운 지도를 만듭니다.

문제 해결

API 키 및 결제 오류

특정 상황에서는 '개발 전용'이라는 워터마크가 표시된 어두운 지도 또는 '음화' 스트리트 뷰 이미지가 표시될 수도 있습니다. 이 동작은 일반적으로 API 키 또는 청구 관련 문제를 나타냅니다. Google Maps Platform 제품을 사용하려면 계정에서 결제를 사용 설정해야 하고 모든 요청에 유효한 API 키를 포함해야 합니다. 다음 단계에 따라 이 문제를 해결할 수 있습니다.

코드가 작동하지 않는 경우:

지도 코드를 작성하고 실행하는 데 도움이 되도록 브렌던 케니와 마노 마크스가 다음 동영상에서 일반적인 실수 및 해결 방법을 알려줍니다.

  • 오타를 찾습니다. 자바스크립트는 대소문자를 구분하는 언어입니다.
  • 기본 사항을 확인합니다. 처음 지도를 만들 때 가장 일반적인 문제가 발생하는 경우가 있습니다. 예를 들면 다음과 같습니다.
    • 지도 옵션에서 zoomcenter 속성을 지정했는지 확인합니다.
    • 화면에 지도를 표시할 div 요소를 선언했는지 확인합니다.
    • 지도의 div 요소에 높이가 있는지 확인합니다. 기본적으로 div 요소는 높이가 0으로 생성되므로 표시되지 않습니다.
    참조 구현의 예를 참고하세요.
  • Chrome 개발자 도구에서 제공하는 디버거와 같은 자바스크립트 디버거를 사용하여 문제를 식별합니다. 먼저 자바스크립트 콘솔에서 오류를 찾아보세요.
  • Stack Overflow에 질문을 게시합니다. 적절한 질문을 게시하는 방법에 관한 가이드라인은 지원 페이지를 확인하세요.