모든 준비를 마쳤습니다!

개발을 시작하려면 개발자 문서로 이동하세요.

Google Maps Embed API 활성화

개발을 시작하기 위해 Google Developers Console에서 우선적으로 해야 할 일을 몇 가지 소개하겠습니다.

  1. 프로젝트 생성 또는 선택
  2. Google Maps Embed API 활성화
  3. 적합한 키 생성
계속

Google Maps Embed API

개요

Google Maps Embed API는 간단한 HTTP 요청으로 사이트에 대화형 지도나 스트리트 뷰 파노라마를 배치할 수 있게 해줍니다. Google Maps Embed API URL을 iframe의 src 특성으로 설정하면 웹 페이지나 블로그에 쉽게 포함할 수 있습니다.

<iframe
  width="600"
  height="450"
  frameborder="0" style="border:0"
  src="https://www.google.com/maps/embed/v1/place?key=YOUR_API_KEY
    &q=Space+Needle,Seattle+WA" allowfullscreen>
</iframe>

나를 위해 제작된 지도

사이트를 방문하는 모든 사람은 각자 자신에게 맞는 Google 지도를 보게 됩니다. Google 계정으로 로그인하면 사용자가 보는 지도에 저장된 장소, 집, 직장 위치 등이 바로 표시됩니다. 또한 위치에 별 표시하기 등과 같은 지도와의 상호작용이 데스크톱이나 모바일용 Google 지도에서 쉽게 볼 수 있도록 저장됨을 의미합니다.

이러한 사용자별 상세정보는 다른 사용자에게 보이지 않습니다. 각 방문자는 자신만을 위해 제작된 지도를 봅니다.

쉬운 임베딩

Google Maps Embed API 지도는 웹페이지에 쉽게 추가됩니다. 빌드하는 URL을 iframe의 src 특성 값으로 설정하기만 하면 됩니다. iframe의 heightwidth 특성으로 지도 크기를 제어합니다. JavaScript가 필요 없습니다.

사용 제한 없음

Google Maps Embed API에 대한 사용 제한이 없습니다. 사용 제한이나 초당 쿼리 조절에 대한 걱정 없이 트래픽이 높은 웹사이트에 지도나 스트리트 뷰 파노라마를 포함할 수 있습니다.

지도에 표시되는 광고

Google Maps Embed API는 지도에 표시되는 광고를 포함할 수 있습니다. 지도 위에 표시되는 광고 형식과 광고 세트는 예고없이 변경될 수 있습니다.

URL 구성

Google Maps Embed API 요청에 대한 URL은 다음과 같습니다.

https://www.google.com/maps/embed/v1/MODE?key=YOUR_API_KEY&parameters

여기에서:

  • {MODE}place, directions, search, view, streetview 중 하나입니다.
  • {YOUR_API_KEY} 는 무료 API 키입니다.
  • parameters에는 선택적 매개변수와 모드별 매개변수가 포함됩니다.

API 키

모든 Google Maps Embed API 요청에는 무료 API 키가 key 매개변수의 값으로 포함되어야 합니다. API 키를 사용하면 애플리케이션의 Maps API 사용량을 모니터링하고, Google이 필요에 따라 여러분의 웹사이트/애플리케이션에 대해 문의할 수 있습니다.

Google Maps Embed API 사용을 시작하려면 아래 버튼을 클릭합니다. 그러면 Google Maps Embed API가 자동으로 활성화되고 API 키를 가져옵니다.

키 가져오기

또는 다음 단계를 수행하여 API 키를 가져옵니다.

  1. Google API Console로 이동합니다.
  2. 프로젝트를 생성하거나 선택합니다.
  3. Continue를 클릭하여 API를 활성화합니다.
  4. Credentials 페이지에서 API key를 가져옵니다(그리고 API 키 제한을 설정합니다).
    참고: 기존의 무제한 API 키가 있거나 브라우저 제한이 있는 키가 있다면, 이 키를 사용할 수도 있습니다.
  5. 다음 모범 사례에 따라 API 키의 보안을 설정하는 것이 좋습니다.


Google API Console에서는 또한 기존 키를 조회하거나 활성화된 API 목록을 조회할 수 있습니다.

Google API Console 사용에 대한 자세한 내용은 API Console 도움말을 참조하세요.

API 키 제한의 유형

Google Maps API는 Android나 iOS 앱, 웹 브라우저 및 HTTP 웹 서비스를 통해 이용할 수 있습니다. 모든 플랫폼의 API가 일반적인(무제한) API 키를 사용할 수 있습니다. 선택적으로 하나의 제한(예: HTTP 참조 페이지)을 API 키에 추가할 수 있습니다. 제한된 경우, 해당 유형의 제한을 지원하는 플랫폼에서만 키가 작동합니다. 키 및 자격 증명에 대해 자세히 알아보세요.

지도 모드

여러분이 사용할 수 있는 4가지 지도 임베드 모드가 있습니다. 모드는 요청 URL에서 지정됩니다.

장소 모드

Place 모드는 랜드마크, 사업체, 지형지물 또는 도시 등과 같은 특정 장소에 지도 핀을 표시합니다.

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

다음 URL 매개변수는 필수입니다.

  • q는 지도에서 강조 표시할 장소를 정의합니다. 이 매개변수는 위치를 장소 이름이나 주소, 장소 ID로 받아들입니다. 문자열은 URL-이스케이프되어야 하므로 "City Hall, New York, NY"과 같은 주소는 City+Hall,New+York,NY로 변환되어야 합니다. (스페이스를 이스케이프할 때 Google Maps Embed API는 +%20를 모두 지원합니다.) 장소 ID는 place_id:라는 접두사를 붙여야 합니다.

특성화된 저장

Google 계정으로 로그인한 사용자는 q 매개변수가 나타내는 장소를 저장할 수 있습니다. 저장된 장소는 웹이나 모바일 기기에서 다른 Google 지도에 나타납니다. 기본적으로, 포함된 지도에서 저장되는 장소에는 해당 장소가 있던 위치와 저장된 시간을 사용자에게 알려주는 특성 정보가 포함됩니다. 다음 매개변수로 특성을 개인화할 수 있습니다.

  • attribution_source는 사이트나 앱에 저장을 특성화합니다. attribution_web_url 또는 attribution_ios_deep_link_id를 설정하기 전에 사용자 지정 attribution_source를 포함해야 합니다. 지도가 나타나는 페이지의 URL 경로를 기본값으로 지정합니다. 예: https://example.com/path/
  • attribution_web_url은 웹사이트로 돌아가는 링크를 지정합니다. attribution_source가 지정되지 않은 경우, attribution_web_url은 포함된 지도가 나타나는 URL을 기본값으로 지정합니다. 예: https://example.com/path/page.html
  • attribution_ios_deep_link_id는 iOS 애플리케이션으로 연결되는 딥 링크를 제공하는 URL 구성표를 지정합니다. iOS용 Google 지도에서 보면, attribution_web_url 대신 attribution_ios_deep_link_id가 표시됩니다.

다음 예시는 브리티시 컬럼비아의 빅토리아에 있는 Empress 호텔에 핀을 표시합니다. 이 위치를 저장하면 저장이 "Google Maps Embed API"에 특성화됩니다. 특성은 URL로 나타납니다. 다음 예시는 Google Maps URL 구성표를 사용하여 iOS 사용자에게 자동차 길찾기를 제공합니다.

https://www.google.com/maps/embed/v1/place?key=YOUR_API_KEY
  &q=Fairmont+Empress,Victoria+BC
  &attribution_source=Google+Maps+Embed+API
  &attribution_web_url=http://www.fairmont.com/empress-victoria/
  &attribution_ios_deep_link_id=comgooglemaps://?daddr=Fairmont+Empress,+Victoria,+BC

길찾기 모드

Directions 모드는 지도에 지정된 2개 이상 지점 간 경로와 거리 및 이동 시간을 표시합니다.

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

다음 URL 매개변수는 필수입니다.

  • origin은 길찾기를 표시할 시작 지점을 정의합니다. 값은 장소 이름, 주소 또는 장소 ID가 될 수 있습니다. 문자열은 URL-이스케이프되어야 하므로 "City Hall, New York, NY"과 같은 주소는 City+Hall,New+York,NY로 변환되어야 합니다. (스페이스를 이스케이프할 때 Google Maps Embed API는 +%20를 모두 지원합니다.) 장소 ID는 place_id:라는 접두사를 붙여야 합니다.
  • destination은 길찾기의 종료 지점을 정의합니다.

선택적 URL 매개변수:

  • waypoints는 출발지에서 목적지로 가는 경로에 하나 이상의 중간 장소를 지정합니다. 파이프 문자(|)를 사용하여 장소를 구분하는 방식으로 여러 경유지를 지정할 수 있습니다(예: Berlin,Germany|Paris,France). 경유지는 최대 20개까지 지정할 수 있습니다. 각 경유지는 장소 이름, 주소 또는 장소 ID가 될 수 있습니다.
  • mode는 교통수단을 정의합니다. 선택 항목은 driving, walking (가능하면 보행자 전용 도로 및 인도 선호), bicycling(가능하면 자전거 전용 도로 및 선호 거리 경유), transit 또는 flying이 있습니다. 모드가 지정되지 않은 경우, Google Maps Embed API는 지정된 경로에 대해 가장 관련성이 높은 모드 중에서 하나 이상을 표시합니다.
  • avoid는 Google 지도에게 tolls, ferries 및/또는 highways를 피하라고 지시합니다. 파이프 문자로 여러 개의 값을 구분합니다(예: avoid=tolls|highways). 참고로 이렇게 하더라도 제한된 기능이 포함된 경로가 제외되는 것은 아니며, 더 나은 경로를 찾기 위해 결과를 편중할 뿐입니다.
  • units는 결과값에서 거리를 표시할 때 metric 또는 imperial 단위를 지정합니다. units가 지정되지 않은 경우, 쿼리의 origin 국가가 사용할 단위를 결정합니다.

검색 모드

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

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

다음 URL 매개변수는 필수입니다.

  • q는 검색어를 지정합니다. 검색어에는 in+Seattle 또는 near+98033 등과 같은 지리적 제한을 포함할 수 있습니다.

뷰 모드

View 모드는 마커나 찾아가는 길이 없는 지도를 반환합니다.

다음 예시는 선택적 maptype 매개변수를 사용하여 지도의 위성 뷰를 표시합니다.

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

다음 URL 매개변수는 필수입니다.

  • center는 지도 창의 중앙을 정의하고 위도와 경도를 쉼표로 구분된 값(-33.8569,151.2152)으로 받아들입니다.

선택적 매개변수

다음 선택적 매개변수는 위에 나열된 모든 지도 모드에서 사용할 수 있습니다.

  • center는 지도 뷰의 중앙을 정의합니다. 쉼표로 구분된 위도와 경도 값(예: 37.4218,-122.0840)을 받아들입니다.

  • zoom은 지도의 처음 확대/축소 수준을 설정합니다. 허용되는 값 범위는 0(세계 전체)에서 21(개별 건물)까지입니다. 상한은 선택된 위치에서 이용할 수 있는 지도 데이터에 따라 달라집니다.

  • maptyperoadmap(기본값) 또는 satellite가 될 수 있고, 로드할 지도 타일 유형을 정의합니다.

  • language는 UI 요소와 지도 타일에 레이블을 표시할 때 사용하는 언어를 정의합니다. 참고로, 이 매개변수는 일부 국가 타일에만 지원됩니다. 요청된 특정 언어가 타일 집합에 대해 지원되지 않으면, 이 타일 집합의 기본 언어가 사용됩니다. 기본적으로, 방문자에게 자국 언어로 된 지도가 표시됩니다.

  • region은 지정학적 민감도에 따라 표시할 적절한 경계선과 레이블을 정의합니다. 두 문자 ccTLD('최상위 도메인') 값으로 지정된 지역 코드를 받아들입니다.

장소 ID 매개변수

Google Maps Embed API는 장소 이름이나 주소를 제공하는 대신 장소 ID를 사용하도록 지원합니다. 장소 ID는 장소를 고유하게 식별하는 안정적인 방법입니다. 장소 ID를 찾고 사용하는 방법에 대한 자세한 내용은 Google Places API 문서 를 참조하세요.

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

  • q

  • origin

  • destination

  • waypoints

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

스트리트 뷰 모드

Google Maps Embed API를사용하면 스트리트 뷰 이미지를 대화형 파노라마로 자신의 사이트나 블로그에 표시할 수 있습니다. Google 스트리트 뷰는 지정된 위치부터 커버리지 영역 전반에 걸쳐 파노라마 뷰를 제공합니다. 사용자 제공 Photo Sphere, 및 스트리트 뷰 스페셜 컬렉션도 이용할 수 있습니다.

각 스트리트 뷰 파노라마는 단일 위치에서 완전한 360도 뷰를 제공합니다. 이미지에는 360도 가로 뷰(완전한 래핑)와 180도 세로 뷰(위에서 아래로 수직)가 포함됩니다.

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는 카메라의 각도, 위/아래 방향을 지정합니다. pitch는 -90°~90° 범위에서 도 단위로 지정됩니다. 양수 값은 카메라 각도를 올리고 음수 값은 카메라 각도를 내립니다. 기본 피치 값은 이미지를 캡처했을 때 카메라 위치에 따라 0°로 설정됩니다. 그러므로 피치가 0°이더라도 수평이 아닌 경우가 많습니다. 예를 들어, 언덕에서 촬영한 이미지는 기본 피치가 수평이 아닐 것입니다.

  • fov는 이미지의 수평 시야각을 판별합니다. 시야각은 10°~100° 범위의 도 단위로 표현됩니다. 기본값은 90°입니다. 고정된 크기의 뷰포트를 다루는 경우 시야각은 확대/축소 수준으로 간주될 수 있으며, 숫자가 작을수록 확대/축소 수준이 더 높음을 나타냅니다.

  • language는 UI 요소와 레이블에 사용하는 언어를 정의합니다. 기본적으로, 방문자에게 자국 언어로 된 UI 요소가 표시됩니다.

  • region은 지정학적 민감도에 따라 표시할 적절한 경계선과 레이블을 정의합니다. 두 문자 ccTLD('최상위 도메인') 값으로 지정된 지역 코드를 받아들입니다.

지도 임베딩

웹 페이지에서 Google Maps Embed API를 사용하려면 iframe의 src 특성 값으로 빌드한 URL을 설정합니다. iframe의 heightwidth 특성으로 지도의 크기를 제어합니다.

<iframe
  width="450"
  height="250"
  frameborder="0" style="border:0"
  src="https://www.google.com/maps/embed/v1/search?key=YOUR_API_KEY&q=record+stores+in+Seattle" allowfullscreen>
</iframe>

: iframe 속성에 allowfullscreen을 추가하여 특정 지도 부분이 전체 화면이 되도록 허용합니다. : frameborder="0"style="border:0" 속성은 지도 주변에서 표준 iframe 테두리를 제거합니다.

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

다음에 대한 의견 보내기...

Google Maps Embed API
Google Maps Embed API
도움이 필요하시나요? 지원 페이지를 방문하세요.