지도 삽입

컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

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

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 속성 값으로 생성한 URL을 설정합니다. iframe의 heightwidth 속성으로 지도의 크기를 제어합니다. 예를 들면 다음과 같습니다.

<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 속성을 사용하여 특정 지도 부분이 전체 화면으로 전환되도록 할 수 있습니다.
  • 지도 주위에서 표준 iframe 테두리를 삭제하는 frameborder="0"style="border:0" 속성
  • referrerpolicy="no-referrer-when-downgrade" 속성을 사용하여 브라우저가 전체 URL을 요청과 함께 Referer 헤더로 전송하도록 허용하면 API 키 제한사항이 올바르게 작동할 수 있습니다.

iframe의 크기를 웹사이트의 구조와 디자인에 맞게 조절할 수 있지만, 일반적으로 방문자가 더 큰 지도와 더 쉽게 상호작용할 수 있습니다. 삽입된 지도는 어느 쪽으로든 크기가 200px 이하인 경우 지원되지 않습니다.

API 키 제한사항

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

지도에 표시되는 광고

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로, 또는 '849VCWC8+R9'는 849VCWC8%2BR9로 변환합니다.
center 선택사항 지도뷰의 중심을 정의합니다. 쉼표로 구분된 위도 및 경도 값을 허용합니다(예: 37.4218,-122.0840).
zoom 선택사항 지도의 초기 확대/축소 수준을 설정합니다. 0 (전 세계)부터 21(개별 건물)까지의 값입니다. 상한은 선택한 위치에서 사용할 수 있는 지도 데이터에 따라 다를 수 있습니다.
maptype 선택사항 로드할 지도 타일 유형을 정의합니다. roadmap(기본값) 또는 satellite
language 선택사항 UI 요소와 지도 타일에 라벨을 표시하는 데 사용할 언어를 정의합니다. 기본적으로 방문자는 모국어로 지도를 볼 수 있습니다. 이 매개변수는 일부 국가 타일에만 지원됩니다. 요청한 특정 타일이 타일 집합에 지원되지 않으면 해당 타일 세트의 기본 언어가 사용됩니다.
region 선택사항 지정학적 민감도에 따라 표시할 경계선과 라벨을 정의합니다. 익숙한 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 선택사항 지정학적 민감도에 따라 표시할 경계선과 라벨을 정의합니다. 익숙한 ccTLD (최상위 도메인) 두 문자 값에 매핑되는 2자리(숫자 이외의) 유니코드 지역 하위 태그로 지정된 지역 코드를 허용합니다. 지원되는 지역은 Google Maps Platform 범위 세부정보를 참고하세요.

directions 모드

다음 예에서는 directions 모드를 사용하여 노르웨이 오슬로와 텔레마크 간의 경로, 유료도로 및 고속도로를 제외한 거리 및 이동 시간을 표시합니다.

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로, 또는 '849VCWC8+R9'는 849VCWC8%2BR9로 변환합니다.
destination 필수 경로의 도착지를 정의합니다. URL 이스케이프 처리된 장소 이름, 주소, 코드, 위도/경도 좌표, 장소 ID Maps Embed API는 공백을 이스케이프 처리할 때 +%20을 모두 지원합니다. 예를 들어 '시청, 뉴욕, 뉴욕'은 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 선택사항 지정학적 민감도에 따라 표시할 경계선과 라벨을 정의합니다. 익숙한 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가 파노라마 ID를 찾을 수 없는 경우에만 사용됩니다.

선택적 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 선택사항 지정학적 민감도에 따라 표시할 경계선과 라벨을 정의합니다. 익숙한 ccTLD (최상위 도메인) 두 문자 값에 매핑되는 2자리(숫자 이외의) 유니코드 지역 하위 태그로 지정된 지역 코드를 허용합니다. 지원되는 지역은 Google Maps Platform 범위 세부정보를 참고하세요.

search 모드

Search 모드는 표시된 지도 영역 전체에서 검색 결과를 표시합니다. 검색어에 위치를 포함하거나(record+stores+in+Seattle) centerzoom 매개변수를 포함하여 검색을 결합함으로써 검색 위치를 정의하는 것이 좋습니다.

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 선택사항 지정학적 민감도에 따라 표시할 경계선과 라벨을 정의합니다. 익숙한 ccTLD (최상위 도메인) 두 문자 값에 매핑되는 2자리(숫자 이외의) 유니코드 지역 하위 태그로 지정된 지역 코드를 허용합니다. 지원되는 지역은 Google Maps Platform 범위 세부정보를 참고하세요.

장소 ID 매개변수

Maps Embed API는 장소 이름 또는 주소를 제공하는 대신 장소 ID 사용을 지원합니다. 장소 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은(는) 야외 컬렉션으로 검색을 제한합니다. 실내 컬렉션은 검색결과에 포함되지 않습니다. 지정된 위치에 야외 파노라마가 없을 수도 있습니다. 또한 검색은 실내 또는 실외인지 확인할 수 있는 파노라마만 반환합니다. 예를 들어 PhotoSphere는 실내 또는 실외에서 알 수 없으므로 반환되지 않습니다.