새로운 지도 스타일이 곧 Google Maps Platform에 제공될 예정입니다. 이 지도 스타일 지정 업데이트에는 새로운 기본 색상 팔레트와 지도 환경 및 사용성 개선사항이 포함됩니다. 모든 지도 스타일이 2025년 3월에 자동으로 업데이트됩니다. 사용 가능 여부 및 더 일찍 선택하는 방법에 대한 자세한 내용은 Google Maps Platform용 새로운 지도 스타일을 참고하세요.

이 페이지는 Cloud Translation API를 통해 번역되었습니다.

지도 삽입

이 가이드에서는 웹페이지에 대화형 지도를 삽입하는 방법을 설명합니다.

Maps Embed API URL 만들기

다음은 Maps Embed API를 로드하는 URL의 예입니다.

https://www.google.com/maps/embed/v1/MAP_MODE?key=YOUR_API_KEY&PARAMETERS

다음과 같이 바꿉니다.

MAP_MODE를 지도 모드로 바꿉니다.
YOUR_API_KEY를 API 키로 바꿉니다. 자세한 내용은 API 키 가져오기를 참고하세요.
지도의 필수 및 선택적 매개변수로 PARAMETERS 바꾸기 있습니다.

iframe에 URL 추가

웹페이지에서 Maps Embed API를 사용하려면 iframe의 src 속성 값으로 빌드됩니다. 다음을 사용하여 지도 크기 제어: iframe의 height 및 width 속성. 예를 들면 다음과 같습니다.

<iframe
  width="450"
  height="250"
  frameborder="0" style="border:0"
  referrerpolicy="no-referrer-when-downgrade"
  src="https://www.google.com/maps/embed/v1/MAP_MODE?key=YOUR_API_KEY&PARAMETERS"
  allowfullscreen>
</iframe>

위의 iframe 샘플은 추가 속성을 사용합니다.

특정 지도 부분을 전체 화면으로 표시할 수 있는 allowfullscreen 속성
표준을 삭제하는 frameborder="0" 및 style="border:0" 속성 지도 주변의 iframe 테두리
referrerpolicy="no-referrer-when-downgrade" 속성을 사용하면 브라우저에서 전체 URL을 요청과 함께 Referer 헤더로 보내서 API 키 제한이 제대로 작동할 수 있습니다.

자체 웹사이트의 구조와 디자인에 맞게 iframe 크기를 조절할 수 있습니다. 그러나 방문자는 일반적으로 큰 지도와 상호작용하는 것이 더 쉽다고 생각합니다. 삽입된 지도는 어느 쪽이든 200픽셀 미만인 경우 지원되지 않습니다. 측정기준을 선택할 수 있습니다.

API 키 제한사항

호스팅 웹사이트에 no-referrer로 설정된 referrer 메타 태그가 있는 경우 또는 same-origin이면 브라우저가 Referer 헤더를 Google로 전송하지 않습니다. 이 API 키 제한이 발생할 수 있음 요청을 거부합니다. 제한이 제대로 작동하도록 하려면 referrerpolicy 속성을 iframe에 추가하여 명시적으로 Referer 헤더를 Google에 전송하도록 허용

지도상의 광고

Maps Embed API에는 지도 위 광고가 포함될 수 있습니다. 광고 형식 및 특정 지도에 표시되는 광고 집합은 예고 없이 변경될 수 있습니다.

지도 모드 선택

요청 URL에 사용할 다음 지도 모드 중 하나를 지정할 수 있습니다.

place: 특정 장소 또는 주소에 지도 핀을 표시합니다. 명소, 업체, 지형지물, 마을 등을 검색할 수 있습니다.
view: 마커나 경로가 없는 지도를 반환합니다.
directions: 둘 이상 간의 경로를 표시합니다. 거리 및 이동 시간뿐만 아니라 지도의 지정된 지점도 사용할 수 있습니다.
streetview: 다음 위치의 대화형 파노라마 뷰를 표시합니다. 지정할 수 있습니다.
search: 표시된 지도에서 검색한 결과를 표시합니다. 리전으로 나뉩니다

`place` 모드

다음 URL은 place 지도 모드를 사용하여 에펠탑:

https://www.google.com/maps/embed/v1/place
  ?key=YOUR_API_KEY
  &q=Eiffel+Tower,Paris+France

다음 매개변수를 사용할 수 있습니다.

매개변수	유형	설명	허용 값
`q`	필수	지도 마커 위치를 정의합니다.	URL 이스케이프된 장소 이름, 주소, 플러스 코드 또는 장소 ID. Maps Embed API는 `+` 및 `%20`를 모두 지원합니다. 가 사용됩니다. 예를 들어 'City Hall, New York, NY'를 변환합니다. ~ `City+Hall,New+York,NY` 또는 플러스 코드: '849VCWC8+R9' ~ `849VCWC8%2BR9`
`center`	선택사항	지도뷰의 중심을 정의합니다.	쉼표로 구분된 위도와 경도 값을 허용합니다. 예를 들면 다음과 같습니다. `37.4218,-122.0840`
`zoom`	선택사항	지도의 초기 확대/축소 수준을 설정합니다.	`0` (전 세계)에서 `21`까지의 범위 값 (개별 건물)을 표시합니다. 상한은 지도 데이터에 따라 다를 수 있습니다. 선택한 위치에서 사용할 수 있습니다.
`maptype`	선택사항	로드할 지도 타일의 유형을 정의합니다.	`roadmap`(기본값) 또는 `satellite`
`language`	선택사항	UI 요소 및 표시에 사용할 언어를 정의합니다. 라벨을 지정할 수도 있습니다. 기본적으로 방문자는 자신의 지도를 설정합니다. 있습니다. 이 매개변수는 일부 국가 타일에만 지원됩니다. 만약 요청된 특정 언어가 타일 집합에서 지원되지 않는 경우 기본 언어가 사용됩니다.
`region`	선택사항	다음에 따라 표시할 적절한 테두리와 라벨을 정의합니다. 지정학적으로 민감하게 만들 수 있습니다.	숫자가 아닌 2자리로 지정된 지역 코드를 사용할 수 있습니다. 익숙한 ccTLD('최상위 도메인')로의 유니코드 지역 하위 태그 매핑 2자(영문 기준) 값이어야 합니다. Google Maps Platform을 참고하세요. 지원되는 지역의 적용 범위 세부정보를 참조하세요.

`view` 모드

다음 예시에서는 view 모드와 선택적 maptype 매개변수를 사용하여 다음을 수행합니다. 지도의 위성 보기를 표시합니다.

https://www.google.com/maps/embed/v1/view
  ?key=YOUR_API_KEY
  &center=-33.8569,151.2152
  &zoom=18
  &maptype=satellite

다음 매개변수를 사용할 수 있습니다.

매개변수	유형	설명	허용 값
`center`	필수	지도뷰의 중심을 정의합니다.	쉼표로 구분된 위도와 경도 값을 허용합니다. 예를 들면 다음과 같습니다. `37.4218,-122.0840`
`zoom`	선택사항	지도의 초기 확대/축소 수준을 설정합니다.	`0` (전 세계)에서 `21`까지의 범위 값 (개별 건물)을 표시합니다. 상한은 지도 데이터에 따라 다를 수 있습니다. 선택한 위치에서 사용할 수 있습니다.
`maptype`	선택사항	로드할 지도 타일의 유형을 정의합니다.	`roadmap`(기본값) 또는 `satellite`
`language`	선택사항	UI 요소 및 표시에 사용할 언어를 정의합니다. 라벨을 지정할 수도 있습니다. 기본적으로 방문자는 자신의 지도를 설정합니다. 있습니다. 이 매개변수는 일부 국가 타일에만 지원됩니다. 만약 요청된 특정 언어가 타일 집합에서 지원되지 않는 경우 기본 언어가 사용됩니다.
`region`	선택사항	다음에 따라 표시할 적절한 테두리와 라벨을 정의합니다. 지정학적으로 민감하게 만들 수 있습니다.	숫자가 아닌 2자리로 지정된 지역 코드를 사용할 수 있습니다. 익숙한 ccTLD('최상위 도메인')로의 유니코드 지역 하위 태그 매핑 2자(영문 기준) 값이어야 합니다. Google Maps Platform을 참고하세요. 지원되는 지역의 적용 범위 세부정보를 참조하세요.

`directions` 모드

다음 예에서는 directions 모드를 사용하여 Oslow와 노르웨이의 텔레마크(Telemark), 유료 도로와 고속도로를 제외한 거리 및 이동 시간.

https://www.google.com/maps/embed/v1/directions
  ?key=YOUR_API_KEY
  &origin=Oslo+Norway
  &destination=Telemark+Norway
  &avoid=tolls|highways

다음 매개변수를 사용할 수 있습니다.

매개변수	유형	설명	허용 값
`origin`	필수	경로를 표시할 시작 지점을 정의합니다.	URL로 이스케이프 처리된 장소 이름, 주소, 플러스 코드, 위도/경도 좌표 또는 장소 ID입니다. Maps Embed API는 `+` 및 `%20`를 모두 지원합니다. 가 사용됩니다. 예를 들어 'City Hall, New York, NY'를 변환합니다. ~ `City+Hall,New+York,NY` 또는 플러스 코드: '849VCWC8+R9' ~ `849VCWC8%2BR9`
`destination`	필수	경로의 도착 지점을 정의합니다.	URL로 이스케이프 처리된 장소 이름, 주소, 플러스 코드, 위도/경도 좌표 또는 장소 ID입니다. Maps Embed API는 `+` 및 `%20`를 모두 지원합니다. 가 사용됩니다. 예를 들어 'City Hall, New York, NY'를 변환합니다. ~ `City+Hall,New+York,NY` 또는 플러스 코드: '849VCWC8+R9' ~ `849VCWC8%2BR9`
`waypoints`	선택사항	경로 사이를 이동할 중간 장소를 하나 이상 지정합니다. 확인할 수 있습니다	장소 이름, 주소 또는 장소 ID. 파이프 문자 (\|)를 사용하여 여러 경유지를 지정할 수 있습니다. 별도의 장소 (예: `Berlin,Germany\|Paris,France`) 다음을 수행할 수 있습니다. 최대 20개의 경유지를 지정합니다.
`mode`	선택사항	이동 방법을 정의합니다. 모드를 지정하지 않으면 Maps Embed API는 지정할 수 있습니다	`driving`, `walking` (보행자 선호) 가능한 경우 경로 및 인도), `bicycling` (이는 자전거 전용 도로 및 가능한 경우 선호하는 도로를 경유하는 경로) `transit` 또는 `flying`입니다.
`avoid`	선택사항	경로에서 피해야 할 지형지물을 지정합니다. 이것은 제한된 지형지물이 포함된 경로를 제외합니다. 인코더-디코더 아키텍처를 더 유리한 경로를 제공합니다.	`tolls`, `ferries` 또는 `highways`. 파이프 문자로 여러 값을 구분합니다 (예: `avoid=tolls\|highways`)을 입력합니다.
`units`	선택사항	표시 시 측정 방법, 미터법 또는 야드파운드법 지정 거리에 있습니다. `units`를 지정하지 않으면 쿼리의 `origin` 국가에 따라 사용할 단위가 결정됩니다.	`metric` 또는 `imperial`
`center`	선택사항	지도뷰의 중심을 정의합니다.	쉼표로 구분된 위도와 경도 값을 허용합니다. 예를 들면 다음과 같습니다. `37.4218,-122.0840`
`zoom`	선택사항	지도의 초기 확대/축소 수준을 설정합니다.	`0` (전 세계)에서 `21`까지의 범위 값 (개별 건물)을 표시합니다. 상한은 지도 데이터에 따라 다를 수 있습니다. 선택한 위치에서 사용할 수 있습니다.
`maptype`	선택사항	로드할 지도 타일의 유형을 정의합니다.	`roadmap`(기본값) 또는 `satellite`
`language`	선택사항	UI 요소 및 표시에 사용할 언어를 정의합니다. 라벨을 지정할 수도 있습니다. 기본적으로 방문자는 자신의 지도를 설정합니다. 있습니다. 이 매개변수는 일부 국가 타일에만 지원됩니다. 만약 요청된 특정 언어가 타일 집합에서 지원되지 않는 경우 기본 언어가 사용됩니다.
`region`	선택사항	다음에 따라 표시할 적절한 테두리와 라벨을 정의합니다. 지정학적으로 민감하게 만들 수 있습니다.	숫자가 아닌 2자리로 지정된 지역 코드를 사용할 수 있습니다. 익숙한 ccTLD('최상위 도메인')로의 유니코드 지역 하위 태그 매핑 2자(영문 기준) 값이어야 합니다. Google Maps Platform을 참고하세요. 지원되는 지역의 적용 범위 세부정보를 참조하세요.

`streetview` 모드

Maps Embed API를 사용하면 스트리트 뷰 이미지를 지정된 위치로부터 대화형 파노라마를 적용 범위. 사용자 제공된 Photo Sphere 및 스트리트 뷰 특별 컬렉션 도 사용할 수 있습니다.

각 스트리트 뷰 파노라마는 단일 위치에서 완전한 360도 뷰를 볼 수 있습니다 이미지에는 360도 가로 보기 (완전한 래핑)가 포함됩니다. 180도 세로 뷰 (위에서 아래로 수직)를 볼 수 있습니다. 이 streetview 모드는 결과를 렌더링하는 뷰어를 제공합니다. 카메라가 중심에 있는 구로 파노라마를 촬영합니다. 카메라를 조작할 수 있습니다. 카메라의 확대/축소와 방향을 제어합니다.

다음 streetview 모드 파노라마를 참고하세요.

https://www.google.com/maps/embed/v1/streetview
  ?key=YOUR_API_KEY
  &location=46.414382,10.013988
  &heading=210
  &pitch=10
  &fov=35

다음 URL 매개변수 중 하나가 필수입니다.

location는 위도와 경도를 쉼표로 구분하여 허용합니다. 값 (46.414382,10.013988)을 반환합니다. API는 파노라마를 가장 가까운 곳에서 촬영되었습니다. 스트리트 뷰 이미지는 주기적으로 새로고침되며 사진은 약간 다른 곳에서 촬영될 수 있습니다. 매번 위치가 다른 식으로 맞춰질 수도 이미지가 업데이트되면 파노라마가 표시됩니다.
pano는 특정 파노라마 ID입니다. 포드의 pano location를 지정할 수도 있습니다. 이 location는 API가 파노라마를 찾을 수 없는 경우에만 사용됩니다. 있습니다.

선택적 URL 매개변수:

매개변수	유형	설명	허용 값
`heading`	선택사항	카메라의 나침반 방향을 시계 방향 각도로 나타냅니다. 북쪽에 위치해 있습니다.	-180°~360°의 값
`pitch`	선택사항	는 카메라의 각도, 위/아래를 지정합니다. 양수 값은 음수 값은 카메라 각도를 아래로 내립니다. 이 피치가 피치가 0°일 때 카메라 위치를 기준으로 이미지를 캡처한 것입니다. 이로 인해 피치가 0°인 경우가 많지만 항상 그렇지는 않습니다. 예를 들어 언덕에서 촬영한 이미지는 기본 피치가 수평이 아닌 경우	-90°~90° 사이의 값
`fov`	선택사항	이미지의 수평 시야를 결정합니다. 그것은 기본값은 90°입니다. 고정 크기 표시 영역을 처리할 때 줌레벨로 간주할 수 있으며, 숫자가 작을수록 확대해 보겠습니다.	도 단위 값(범위: 10°~100°)
`center`	선택사항	지도뷰의 중심을 정의합니다.	쉼표로 구분된 위도와 경도 값을 허용합니다. 예를 들면 다음과 같습니다. `37.4218,-122.0840`
`zoom`	선택사항	지도의 초기 확대/축소 수준을 설정합니다.	`0` (전 세계)에서 `21`까지의 범위 값 (개별 건물)을 표시합니다. 상한은 지도 데이터에 따라 다를 수 있습니다. 선택한 위치에서 사용할 수 있습니다.
`maptype`	선택사항	로드할 지도 타일의 유형을 정의합니다.	`roadmap`(기본값) 또는 `satellite`
`language`	선택사항	UI 요소 및 표시에 사용할 언어를 정의합니다. 라벨을 지정할 수도 있습니다. 기본적으로 방문자는 자신의 지도를 설정합니다. 있습니다. 이 매개변수는 일부 국가 타일에만 지원됩니다. 만약 요청된 특정 언어가 타일 집합에서 지원되지 않는 경우 기본 언어가 사용됩니다.
`region`	선택사항	다음에 따라 표시할 적절한 테두리와 라벨을 정의합니다. 지정학적으로 민감하게 만들 수 있습니다.	숫자가 아닌 2자리로 지정된 지역 코드를 사용할 수 있습니다. 익숙한 ccTLD('최상위 도메인')로의 유니코드 지역 하위 태그 매핑 2자(영문 기준) 값이어야 합니다. Google Maps Platform을 참고하세요. 지원되는 지역의 적용 범위 세부정보를 참조하세요.

`search` 모드

Search 모드는 표시된 지도 영역에 대한 검색 결과를 표시합니다. 검색 위치는 검색어 (record+stores+in+Seattle)에 위치 포함 또는 검색을 결합하기 위해 center 및 zoom 매개변수를 포함합니다.

https://www.google.com/maps/embed/v1/search
  ?key=YOUR_API_KEY
  &q=record+stores+in+Seattle

다음 매개변수를 사용할 수 있습니다.

매개변수	유형	설명	허용 값
`q`	필수	검색어를 정의합니다.	지역적 제한, `in+Seattle` 또는 `near+98033` 등).
`center`	선택사항	지도뷰의 중심을 정의합니다.	쉼표로 구분된 위도와 경도 값을 허용합니다. 예를 들면 다음과 같습니다. `37.4218,-122.0840`
`zoom`	선택사항	지도의 초기 확대/축소 수준을 설정합니다.	`0` (전 세계)에서 `21`까지의 범위 값 (개별 건물)을 표시합니다. 상한은 지도 데이터에 따라 다를 수 있습니다. 선택한 위치에서 사용할 수 있습니다.
`maptype`	선택사항	로드할 지도 타일의 유형을 정의합니다.	`roadmap`(기본값) 또는 `satellite`
`language`	선택사항	UI 요소 및 표시에 사용할 언어를 정의합니다. 라벨을 지정할 수도 있습니다. 기본적으로 방문자는 자신의 지도를 설정합니다. 있습니다. 이 매개변수는 일부 국가 타일에만 지원됩니다. 만약 요청된 특정 언어가 타일 집합에서 지원되지 않는 경우 기본 언어가 사용됩니다.
`region`	선택사항	다음에 따라 표시할 적절한 테두리와 라벨을 정의합니다. 지정학적으로 민감하게 만들 수 있습니다.	숫자가 아닌 2자리로 지정된 지역 코드를 사용할 수 있습니다. 익숙한 ccTLD('최상위 도메인')로의 유니코드 지역 하위 태그 매핑 2자(영문 기준) 값이어야 합니다. Google Maps Platform을 참고하세요. 지원되는 지역의 적용 범위 세부정보를 참조하세요.

장소 ID 매개변수

Maps Embed API는 선택할 수 있습니다 장소 ID는 고유한 방식으로 장소를 찾아냅니다. 자세한 내용은 Google Places API 문서를 참조하세요.

Maps Embed API는 다음 URL에 대한 장소 ID를 허용합니다. 매개변수:

q
origin
destination
waypoints

장소 ID를 사용하려면 먼저 place_id: 접두사를 추가해야 합니다. 이 다음 코드는 뉴욕 시청을 길찾기의 출발지로 지정합니다. 요청: origin=place_id:ChIJs--MqP1YwokRBwAhjXWIHn8

radius는 미터로 지정된 반경을 설정하며 주어진 위도와 경도를 중심으로 하여 파노라마를 표시합니다. 유효한 값 음이 아닌 정수입니다. 기본값은 50입니다.
source에서는 선택한 출처로 스트리트 뷰 검색을 제한합니다. 유효한 값은 다음과 같습니다.
- default는 스트리트 뷰에 기본 소스를 사용합니다. 검색량은 특정 소스에 국한되지 않습니다
- outdoor는 야외 모음으로 검색을 제한합니다. 실내용 컬렉션은 검색결과에 포함되지 않습니다. 야외 파노라마는 지정된 위치에 이(가) 존재하지 않을 수 있습니다. 또한 검색만 실내에 있는지 확인할 수 있는 파노라마를 반환합니다. 야외에서 촬영할 수 있습니다. 예를 들어 PhotoSpheres는 알 수 없는 상태이므로 반환되지 않습니다. 실외 또는 실외에 위치합니다.

지도 삽입

Maps Embed API URL 만들기

iframe에 URL 추가

API 키 제한사항

지도상의 광고

지도 모드 선택

place 모드

view 모드

directions 모드

streetview 모드

search 모드

장소 ID 매개변수

`place` 모드

`view` 모드

`directions` 모드

`streetview` 모드

`search` 모드