이 가이드에서는 웹페이지에 대화형 지도를 삽입하는 방법을 설명합니다.
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를 사용하려면 빌드한 URL을 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 키 제한으로 요청이 거부될 수 있습니다. 제한사항이 제대로 작동하려면 위의 예와 같이 iframe에 referrerpolicy
속성을 추가하여 Referer
헤더가 Google로 전송되도록 명시적으로 허용합니다.
지도상의 광고
Maps Embed API에는 지도 위 광고가 포함될 수 있습니다. 지도 위에 표시되는 광고 형식과 광고 세트는 예고 없이 변경될 수 있습니다.
지도 모드 선택
요청 URL에서 사용할 다음 지도 모드 중 하나를 지정할 수 있습니다.
place
: 랜드마크, 사업체, 지형지물 또는 도시 등과 같은 특정 장소나 주소에 지도 핀을 표시합니다.view
: 마커나 경로가 없는 지도를 반환합니다.directions
: 지도에 지정된 2개 이상의 지점 간 경로와 거리 및 이동 시간을 표시합니다.streetview
: 지정된 위치의 양방향 파노라마 뷰를 표시합니다.search
: 표시된 지도 영역에서 검색한 결과를 표시합니다.
place
모드
다음 URL은 place
지도 모드를 사용하여
에펠탑:
https://www.google.com/maps/embed/v1/place
?key=YOUR_API_KEY
&q=Eiffel+Tower,Paris+France
다음 매개변수를 사용할 수 있습니다.
매개변수 | 유형 | 설명 | 허용 값 |
---|---|---|---|
q |
필수 | 지도 마커 위치를 정의합니다. | URL 이스케이프 처리된 장소 이름, 주소, Plus Code 또는 장소 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
¢er=-33.8569,151.2152
&zoom=18
&maptype=satellite
다음 매개변수를 사용할 수 있습니다.
매개변수 | 유형 | 설명 | 허용 값 |
---|---|---|---|
center |
필수 | 지도 뷰의 중앙을 정의합니다. | 쉼표로 구분된 위도와 경도 값을 허용합니다. 예를 들면 다음과 같습니다.
37.4218,-122.0840 |
zoom |
선택사항 | 지도의 초기 확대/축소 수준을 설정합니다. | 값 범위는 0 (전 세계)에서 21 (개별 건물)까지입니다. 상한값은 지도 데이터에 따라 다를 수 있습니다.
선택한 위치에서 사용할 수 있습니다. |
maptype |
선택사항 | 로드할 지도 타일의 유형을 정의합니다. | roadmap (기본값) 또는 satellite |
language |
선택사항 | UI 요소와 지도 타일에 레이블을 표시할 때 사용할 언어를 정의합니다. 기본적으로 방문자는 자신의 지도를 설정할 수 있습니다. 있습니다. 이 매개변수는 일부 국가 타일에만 지원됩니다. 요청된 특정 언어가 타일 집합에 대해 지원되지 않으면, 이 타일 집합의 기본 언어가 사용됩니다. | |
region |
선택사항 | 다음에 따라 표시할 적절한 테두리와 라벨을 정의합니다. 지정학적으로 민감하게 만들 수 있습니다. | 익숙한 ccTLD('최상위 도메인') 두 문자 값에 매핑되는 두 문자(숫자가 아닌) 유니코드 지역 하위 태그로 지정된 지역 코드를 허용합니다. 지원되는 지역은 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 |
선택사항 | 다음에 따라 표시할 적절한 테두리와 라벨을 정의합니다. 지정학적으로 민감하게 만들 수 있습니다. | 익숙한 ccTLD('최상위 도메인') 두 문자 값에 매핑되는 두 문자(숫자가 아닌) 유니코드 지역 하위 태그로 지정된 지역 코드를 허용합니다. 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 |
선택사항 | 다음에 따라 표시할 적절한 테두리와 라벨을 정의합니다. 지정학적으로 민감하게 만들 수 있습니다. | 익숙한 ccTLD('최상위 도메인') 두 문자 값에 매핑되는 두 문자(숫자가 아닌) 유니코드 지역 하위 태그로 지정된 지역 코드를 허용합니다. 지원되는 지역은 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 |
선택사항 | 다음에 따라 표시할 적절한 테두리와 라벨을 정의합니다. 지정학적으로 민감하게 만들 수 있습니다. | 익숙한 ccTLD('최상위 도메인') 두 문자 값에 매핑되는 두 문자(숫자가 아닌) 유니코드 지역 하위 태그로 지정된 지역 코드를 허용합니다. 지원되는 지역은 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
는 야외 모음으로 검색을 제한합니다. 실내용 컬렉션은 검색결과에 포함되지 않습니다. 야외 파노라마는 지정된 위치에 이(가) 존재하지 않을 수 있습니다. 또한 검색 시 실내 또는 실외인지 확인할 수 있는 파노라마만 반환됩니다. 예를 들어 PhotoSpheres는 알 수 없는 상태이므로 반환되지 않습니다. 실외 또는 실외에 위치합니다.