Maps Embed API는 JavaScript를 사용하지 않고 iframe src URL로 설정된 HTTP 요청을 통해 웹페이지에 대화형 지도 또는 스트리트 뷰 파노라마를 배치합니다. place, view, directions, streetview, search 지도 모드를 지원합니다.
Maps Embed API: 주요 사실
- 제품: Maps Embed API
- 다른 이름: Google Maps Embed API, Maps Embed
- 카테고리: 지도
- 플랫폼: JavaScript(브라우저)
- 실행 위치: 클라이언트(앱 또는 브라우저 코드)
- 출시 단계: GA
- 수명 주기: 활성
- 개요: Maps Embed API 개요
- 신청 가능 지역: 전 세계 스트리트 뷰 보기 모드는 스트리트 뷰 서비스 범위에 따라 달라집니다.
region매개변수는 Google Maps Platform 노출 범위 세부정보 페이지에 나열된 지역을 허용합니다. (보증 범위 세부정보)
Maps Embed API: 사용해야 하는 경우
다음과 같은 경우 Maps Embed API를 사용하세요.
- JavaScript 없이 HTML iframe만 사용하여 웹페이지에 대화형 지도 또는 스트리트 뷰 파노라마를 표시해야 합니다.
- 삽입된 지도에 장소 핀, 지도 뷰, 지점 간 경로 또는 지역 검색 결과를 표시해야 합니다.
- 요청당 요금이 부과되지 않고 QPS 또는 일일 요청 한도가 없는 삽입된 지도가 필요합니다(API 키는 여전히 필요함).
다음과 같은 경우에는 Maps Embed API를 사용하지 마세요.
- 자체 콘텐츠와 이미지를 사용하여 웹 지도를 맞춤설정해야 합니다. 대신 Maps JavaScript API를 사용하세요.
- iframe URL 매개변수 이외의 프로그래매틱 기능으로 삽입된 지도를 확장해야 합니다. 대신 Maps JavaScript API를 사용하세요.
Maps Embed API: 설정
- 사용 설정할 서비스:
maps-embed-backend.googleapis.com - 인증: API 키
- 시작하기: Maps Embed API 설정
- 참조: Maps Embed API 참조
- 가격 책정: Maps Embed API 사용량 및 결제
Maps Embed API: 일반적인 실수
- 문제: 호스트 페이지에서
referrer메타 태그를no-referrer또는same-origin로 설정하면 브라우저가Referer헤더를 전송하지 않으며 HTTP 리퍼러 제한 API 키가 삽입 요청을 거부할 수 있습니다. 해결 방법: 사이트의 도메인이 Google로 전송되도록 iframe에referrerpolicy="strict-origin-when-cross-origin"를 추가합니다. /maps/documentation/embed/embedding-map을 참고하세요. - 문제: 삽입된 지도는 가로 또는 세로가 200픽셀 미만인 경우 지원되지 않습니다. 해결 방법: iframe
width및height를 200픽셀 이상으로 설정합니다. /maps/documentation/embed/embedding-map을 참고하세요. - 문제: 사용량이 무료이더라도 결제가 사용 설정되지 않았거나, 결제 수단이 잘못되었거나, 자체적으로 설정한 일일 한도를 초과했거나, 리퍼러 제한 키를 사용하는 동안 요청에 HTTP 리퍼러가 누락된 경우 '개발 목적으로만 사용'이라는 워터마크가 표시된 어두운 지도가 표시됩니다. 해결 방법: 프로젝트에서 유효한 결제 수단으로 결제를 사용 설정하고, 자체적으로 설정한 일일 할당량 한도를 높이거나 삭제하고, 리퍼러 제한 키에 대해 리퍼러가 전송되는지 확인합니다(예: iframe의
referrerpolicy="strict-origin-when-cross-origin"). /maps/documentation/embed/error-messages를 참고하세요. - 문제: 잘못된 요청(잘못되거나 누락된 매개변수, 누락되거나 잘못된 키와 같은 API 키 및 할당량 오류, Maps Embed API가 사용 설정되지 않음, 키 제한 위반)의 경우 설명 메시지가 아닌 HTTP 4xx 상태 코드만 브라우저 콘솔에 보고됩니다. 오류 텍스트는 지도 대신 iframe 내에 표시됩니다. 해결 방법: iframe의 오류 텍스트와 콘솔 상태 코드(매개변수 오류의 경우 400, 키가 누락된 경우 401, 키가 잘못된 경우 403)를 읽은 다음 매개변수가 유효하고, 키가 유효하며, Maps Embed API가 사용 설정되어 있고, 키 제한사항이 요청을 허용하는지 확인합니다. /maps/documentation/embed/error-messages를 참고하세요.
Maps Embed API로 할 수 있는 작업
각 작업에 대해 아래에 링크된 가이드를 참조하거나 기능 탐색기에서 제품 간에 비교하세요.