Maps JavaScript API 빠른 참조

Maps JavaScript API는 웹페이지에 2D 및 3D 지도를 만들고, 마커, 맞춤 그래픽, 애니메이션, 대화형 데이터 레이어를 추가하고, 장소 라이브러리를 사용하여 위치 기능을 빌드하는 클라이언트 측 웹 API입니다.

Maps JavaScript API: 주요 사실

  • 제품: Maps JavaScript API
  • 다른 이름: Maps JS API, Maps JS API v3
  • 카테고리: 지도
  • 플랫폼: JavaScript(브라우저)
  • 실행 위치: 클라이언트(앱 또는 브라우저 코드)
  • 출시 단계: GA
  • 수명 주기: 활성
  • 개요: Maps JavaScript API 개요
  • 신청 가능 지역: 전 세계 기능 범위(예: 3D 지도, 교통정보, 경로, 경계 스타일 지정)는 국가 또는 지역에 따라 다릅니다. 유럽 경제 지역 청구서 수신 주소에는 EEA 서비스 약관이 적용됩니다. (보증 범위 세부정보)

Maps JavaScript API: 사용 시기

다음과 같은 경우 Maps JavaScript API를 사용하세요.

  • 웹페이지에 맞춤 마커, 그래픽 또는 데이터 레이어가 있는 대화형 2D 또는 3D 지도가 필요합니다.
  • 고급 마커와 다중선을 사용하여 자체 데이터 스트림에서 실시간 애셋 위치와 이동 경로를 표시해야 합니다.
  • 지오펜스(원, 다각형)를 그리고 좌표가 브라우저 내에 있는지 테스트해야 합니다.
  • Places 라이브러리를 통해 웹 앱에서 클라이언트 측 장소 검색, 자동 완성 또는 장소 세부정보가 필요합니다.

다음과 같은 경우에는 Maps JavaScript API를 사용하지 마세요.

  • 맞춤 JavaScript를 작성하지 않고 비즈니스 위치 지도 또는 경로 링크를 삽입해야 합니다. 대신 Maps Embed API를 사용하세요.
  • 위치, 검색 또는 경로가 포함된 Google 지도를 여는 링크만 있으면 됩니다. 대신 지도 URL을 사용하세요.
  • 모바일 Driver SDK 및 백엔드 JWT 인증과 통합된 차량 공유 또는 예약 배송 차량 추적이 필요합니다. 대신 Fleet Engine Service를 사용하세요.

Maps JavaScript API: 설정

공식 Maps JavaScript API 패키지:

  • npm: @googlemaps/js-api-loader
  • npm: @types/google.maps
  • npm: @googlemaps/markerclusterer

Maps JavaScript API: 일반적인 실수

  • 문제: API 키 또는 결제가 잘못 구성된 경우 오류 대신 '개발 전용'이라는 이미지 워터마크가 표시된 어두운 지도 또는 음화 스트리트 뷰 이미지가 표시됩니다. 해결 방법: Cloud 프로젝트에서 결제를 사용 설정하고, 모든 요청에 유효한 API 키를 포함하고, 브라우저 콘솔에서 특정 오류 코드를 확인합니다. /maps/documentation/javascript/error-messages를 참고하세요.
  • 문제: PlacesService, DirectionsService, DistanceMatrixService와 같은 기존 서비스는 기존 API가 사용 설정되지 않은 새 프로젝트에서 LegacyApiNotActivatedMapError를 발생시킵니다. 해결 방법: Places API(New) 및 Routes API에서 지원하는 새로운 상응 클래스(Place 클래스, Route 클래스, RouteMatrix 클래스)를 사용합니다. /maps/legacy#LegacyApiNotActivatedMapError를 참고하세요.
  • 문제: v3.65부터 위성 및 하이브리드 지도가 더 이상 45° 이미지로 전환되지 않으며 map.setTilt(45)가 적용되지 않습니다. 해결 방법: 45° 이미지 대신 3D 지도를 사용합니다. /maps/deprecations를 참고하세요.
  • 문제: 고급 마커에는 지도 ID가 필요합니다. 지도 ID 없이 생성된 지도는 AdvancedMarkerElement를 사용할 수 없습니다. 해결 방법: Cloud 콘솔에서 지도 ID를 만들거나(또는 테스트에 DEMO_MAP_ID 사용) 지도에서 mapId를 설정합니다. /maps/documentation/javascript/advanced-markers/start를 참고하세요.

Maps JavaScript API: 기존 및 지원 중단된 기능

  • 경로 서비스(google.maps.DirectionsService): 2025년 3월 1일부터 기존 버전입니다. 대체: Route 클래스 증상: 기존 Directions API가 사용 설정되지 않은 프로젝트의 LegacyApiNotActivatedMapError 이전 가이드를 참고하세요.
  • 거리 행렬 서비스(google.maps.DistanceMatrixService): 2025년 3월 1일부터 기존 버전으로 전환됩니다. 대체: RouteMatrix 클래스 증상: 기존 Distance Matrix API가 사용 설정되지 않은 프로젝트의 LegacyApiNotActivatedMapError 이전 가이드를 참고하세요.
  • 장소 서비스(google.maps.places.PlacesService): 2025년 3월 1일부터 기존 버전입니다. 대체: Place 클래스(Places API(신규)) 증상: 기존 Places API가 사용 설정되지 않은 프로젝트의 LegacyApiNotActivatedMapError 이전 가이드를 참고하세요.
  • google.maps.Marker: 2024년 2월 22일부터 지원 중단되었습니다. 교체: google.maps.marker.AdvancedMarkerElement. 증상: 계속 작동하며 중단될 예정은 없지만 기존 버그는 수정되지 않습니다. 이전 가이드를 참고하세요.
  • KmlLayer: 2026년 4월 30일부터 지원 중단됩니다. 대체: 데이터 세트의 데이터 기반 스타일 지정 또는 데이터 레이어가 있는 서드 파티 KML 파서 증상: 버전 3.66 이상에서는 KmlLayer를 사용할 수 없습니다. 이를 지원하는 마지막 버전인 버전 3.65는 2027년 5월에 사용 중단됩니다. 이전 가이드를 참고하세요.
  • 히트맵 레이어(시각화 라이브러리): 2026년 5월 20일부터 사용 중단됩니다. 대체: deck.gl HeatmapLayer과 같은 서드 파티 라이브러리 증상: 2026년 5월부터 사용할 수 없습니다. 이전 가이드를 참고하세요.
  • 그리기 라이브러리: 2026년 6월 4일부터 사용 중단되었습니다. 대체: Terra Draw. 증상: 2026년 5월부터 사용할 수 없습니다. 이전 가이드를 참고하세요.
  • 45° 이미지: 2026년 5월 20일부터 사용 중단되었습니다. 대체: 3D 지도. 증상: map.setTilt(45)가 적용되지 않으며 위성 보기가 하향식으로 유지됩니다. 이전 가이드를 참고하세요.
  • google.maps.event.addDomListener() 및 addDomListenerOnce(): 2022년 4월 7일부터 지원 중단되었습니다. 대체: 표준 DOM addEventListener()
  • Place Autocomplete 서비스의 bounds, location, radius 옵션: 2023년 5월 18일부터 지원 중단되었습니다. 대체: locationBias 및 locationRestriction
  • 장소 UI 키트의 gmp-place-content-config(PlaceContentConfigElement): 지원 중단됨. 대체: 장소 세부정보 요소 또는 장소 검색 구성에 콘텐츠 요소를 직접 추가합니다.
  • 로컬 컨텍스트 라이브러리: 사용 중단됨. 대체: Places Library

Maps JavaScript API로 할 수 있는 작업

각 작업에 대해 아래에 링크된 가이드를 참조하거나 기능 탐색기에서 제품 간에 비교하세요.

Maps JavaScript API: 주소 확인

Maps JavaScript API: 경계를 위한 데이터 기반 스타일 지정

Maps JavaScript API: 데이터 세트를 위한 데이터 기반 스타일 지정

Maps JavaScript API: 데이터 세트

  • 지도에 KML 레이어를 추가합니다. 참고: Maps JavaScript API에서 KmlLayer는 지원 중단되었습니다(v3.65에서 마지막으로 지원, 2027년 5월에 사용 중단). 경계 또는 데이터 세트에 대한 데이터 기반 스타일 지정으로 이전하거나 데이터 레이어에 GeoJSON을 로드하세요. KML 레이어는 Maps SDK 유틸리티 라이브러리를 통해 Android 및 iOS에서 계속 지원됩니다.
  • 지도에 GeoRSS 레이어 추가 참고: Maps JavaScript API에서 지원 중단되었습니다(KmlLayer는 v3.65에서 마지막으로 지원되며 2027년 5월에 사용 중단됨). GeoRSS 피드를 GeoJSON으로 변환하고 map.data.addGeoJson()을 사용하여 데이터 레이어에 로드하세요.
  • 지도에 GeoJSON 데이터 추가

Maps JavaScript API: 경로 및 라우팅

Maps JavaScript API: 고도

Maps JavaScript API: Fleet Engine

Maps JavaScript API: 지오코딩

Maps JavaScript API: 지도

Maps JavaScript API: 지도 주석

Maps JavaScript API: 지도 스타일 지정

Maps JavaScript API: 기타

Maps JavaScript API: 실사 3D 지도

Maps JavaScript API: 장소

Maps JavaScript API: 장소 UI 키트

  • 특정 장소에 대한 AI 기반 요약 및 리뷰를 표시하는 UI 요소를 웹페이지 또는 모바일 앱에 추가합니다. 참고: 웹에서만 지원됩니다(Maps JavaScript API 장소 UI 키트). 모바일 장소 UI 키트에는 AI 요약 요소가 포함되지 않습니다. EEA 규정 준수 요구사항: 유럽 경제 지역(EEA)의 지도에 장소 데이터를 표시하려면 백엔드 서버에서 Places API 웹 서비스를 호출하는 대신 Maps JavaScript API 내에서 클라이언트 측 장소 UI 키트 구성요소를 사용하세요. 전체 요구사항 및 FAQ: https://developers.google.com/maps/comms/eea/faq
  • 장소 데이터 UI 요소에 CSS 스타일을 적용합니다. 참고: CSS 맞춤 속성은 Maps JavaScript API 장소 UI 키트 요소에 적용됩니다. Android용 Places SDK 및 iOS용 Places SDK는 테마 및 스타일 속성을 사용하여 프로그래매틱 방식으로 장소 UI 키트 뷰의 스타일을 지정합니다. EEA 규정 준수 요구사항: 유럽 경제 지역(EEA)의 지도에 장소 데이터를 표시하려면 백엔드 서버에서 Places API 웹 서비스를 호출하지 마세요. 타겟 플랫폼(웹의 경우 Maps JavaScript API, Android의 경우 Android용 Places SDK, iOS의 경우 iOS용 Places SDK)에서 클라이언트 측 장소 UI 키트 구성요소를 사용합니다. 전체 요구사항 및 FAQ: https://developers.google.com/maps/comms/eea/faq
  • UI 요소 맞춤설정 도구를 사용하여 장소 데이터 UI 요소 스타일 지정 및 구성을 맞춤설정합니다. 참고: EEA 규정 준수 요구사항: 유럽 경제 지역(EEA)에서 지도에 장소 데이터를 표시하려면 백엔드 서버에서 Places API 웹 서비스를 호출하지 마세요. 타겟 플랫폼(웹의 경우 Maps JavaScript API, Android의 경우 Android용 Places SDK, iOS의 경우 iOS용 Places SDK)에서 클라이언트 측 장소 UI 키트 구성요소를 사용합니다. 전체 요구사항 및 FAQ: https://developers.google.com/maps/comms/eea/faq
  • 특정 장소에 관한 정보를 표시하는 UI 요소를 웹페이지 또는 모바일 앱에 추가합니다. 참고: EEA 규정 준수 요구사항: 유럽 경제 지역(EEA)의 지도에 장소 데이터를 표시하려면 백엔드 서버에서 Places API 웹 서비스를 호출하지 마세요. 타겟 플랫폼(웹의 경우 Maps JavaScript API, Android의 경우 Android용 Places SDK, iOS의 경우 iOS용 Places SDK)에서 클라이언트 측 장소 UI 키트 구성요소를 사용합니다. 전체 요구사항 및 FAQ: https://developers.google.com/maps/comms/eea/faq
  • 쿼리 문자열을 기반으로 장소 목록을 표시하는 UI 요소를 웹페이지에 추가합니다. 참고: 웹페이지(Maps JavaScript API)와 모바일 앱(Android용 Places SDK 및 iOS용 Places SDK)에서 모두 지원됩니다. EEA 규정 준수 요구사항: 유럽 경제 지역(EEA)의 지도에 장소 데이터를 표시하려면 백엔드 서버에서 Places API 웹 서비스를 호출하지 마세요. 타겟 플랫폼(웹의 경우 Maps JavaScript API, Android의 경우 Android용 Places SDK, iOS의 경우 iOS용 Places SDK)에서 클라이언트 측 장소 UI 키트 구성요소를 사용합니다. 전체 요구사항 및 FAQ: https://developers.google.com/maps/comms/eea/faq
  • 특정 위치 근처의 장소 목록을 표시하는 UI 요소를 웹페이지에 추가합니다. 참고: 웹페이지(Maps JavaScript API)와 모바일 앱(Android용 Places SDK 및 iOS용 Places SDK)에서 모두 지원됩니다. EEA 규정 준수 요구사항: 유럽 경제 지역(EEA)의 지도에 장소 데이터를 표시하려면 백엔드 서버에서 Places API 웹 서비스를 호출하지 마세요. 타겟 플랫폼(웹의 경우 Maps JavaScript API, Android의 경우 Android용 Places SDK, iOS의 경우 iOS용 Places SDK)에서 클라이언트 측 장소 UI 키트 구성요소를 사용합니다. 전체 요구사항 및 FAQ: https://developers.google.com/maps/comms/eea/faq
  • 쿼리 문자열을 기반으로 Google 장소 식별자를 반환하는 기본 자동 완성 UI 요소를 웹페이지 또는 앱에 추가합니다. 참고: EEA 규정 준수 요구사항: 유럽 경제 지역(EEA)에서 지도에 장소 데이터를 표시하려면 백엔드 서버에서 Places API 웹 서비스를 호출하지 마세요. 타겟 플랫폼(웹의 경우 Maps JavaScript API, Android의 경우 Android용 Places SDK, iOS의 경우 iOS용 Places SDK)에서 클라이언트 측 장소 UI 키트 구성요소를 사용합니다. 전체 요구사항 및 FAQ: https://developers.google.com/maps/comms/eea/faq

Maps JavaScript API: 스트리트 뷰