모든 준비를 마쳤습니다!

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

Google Maps Android API 활성화

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

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

지도 객체

지도는 API에서 GoogleMapMapFragment 클래스로 나타납니다.

코드 샘플

Github의 ApiDemos 리포지토리에는 GoogleMap 객체 및 SupportMapFragment 사용법을 보여주는 샘플이 포함되어 있습니다.

Android 앱에 지도 추가

지도 추가를 위한 기본 단계:

  1. (이 단계는 한 번만 수행하면 됩니다.) 프로젝트 구성 가이드의 단계에 따라 API를 가져오고, 키를 획득한 다음, Android 매니페스트에 필수 특성을 추가합니다.
  2. Fragment 객체를 지도를 처리할 Activity에 추가합니다. 가장 쉬운 방법은 <fragment> 요소를 Activity의 레이아웃 파일에 추가하는 것입니다.
  3. OnMapReadyCallback 인터페이스를 구현하고 onMapReady(GoogleMap) 콜백 메서드를 사용하여 GoogleMap 객체의 핸들을 가져옵니다. GoogleMap 객체는 지도 자체의 내부적 표현입니다. 지도의 뷰 옵션을 설정하려면 GoogleMap 객체를 수정합니다.
  4. 프래그먼트에서 getMapAsync()를 호출하여 콜백을 등록합니다.

다음은 각 단계에 대한 자세한 설명입니다.

프래그먼트 추가

액티비티 레이아웃 파일에 <fragment> 요소를 추가하고 Fragment 객체를 정의합니다. 이 요소는 android:name 특성을 "com.google.android.gms.maps.MapFragment"로 설정합니다. 그러면 MapFragment가 액티비티에 자동으로 첨부됩니다.

다음 레이아웃 파일은 <fragment> 요소가 포함되어 있습니다.

<?xml version="1.0" encoding="utf-8"?>
<fragment xmlns:android="http://schemas.android.com/apk/res/android"
    android:name="com.google.android.gms.maps.MapFragment"
    android:id="@+id/map"
    android:layout_width="match_parent"
    android:layout_height="match_parent"/>

또한, 코드에서 MapFragmentActivity에 추가할 수 있습니다. 이렇게 하려면 새 MapFragment 인스턴스를 생성하고 FragmentTransaction.add()를 호출하여 Fragment를 현재 Activity에 추가합니다.

 mMapFragment = MapFragment.newInstance();
 FragmentTransaction fragmentTransaction =
         getFragmentManager().beginTransaction();
 fragmentTransaction.add(R.id.my_container, mMapFragment);
 fragmentTransaction.commit();

지도 코드 추가

앱에서 지도를 사용하려면 OnMapReadyCallback 인터페이스를 구현하고 MapFragment 또는 MapView 객체에서 콜백의 인스턴스를 설정해야 합니다. 이 튜토리얼은 앱에 지도를 추가할 때 가장 흔히 사용하는 방법인 MapFragment를 사용합니다. 첫 단계는 콜백 인터페이스를 구현하는 것입니다.

public class MainActivity extends FragmentActivity
    implements OnMapReadyCallback {
...
}

ActivityonCreate() 메서드에서 레이아웃 파일을 콘텐츠 뷰로 설정합니다. 예를 들어, 레이아웃 파일에 main.xml이란 이름이 있으면 다음 코드를 사용합니다.

@Override
public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.main);
    ...
}

FragmentManager.findFragmentById()를 호출하고, <fragment> 요소의 리소스 ID에 전달하여 프래그먼트의 핸들을 가져옵니다. 리소스 ID R.id.map는 레이아웃 파일을 빌드할 때 Android 프로젝트에 자동으로 추가됩니다.

그런 다음 getMapAsync()를 사용하여 프래그먼트에서 콜백을 설정합니다.

MapFragment mapFragment = (MapFragment) getFragmentManager()
    .findFragmentById(R.id.map);
mapFragment.getMapAsync(this);

참고: Google Maps Android API가 MapFragment 객체를 지원하려면 API 레벨 12 이상이 필요합니다. API 레벨 12 이전의 애플리케이션을 대상으로 하는 경우, SupportMapFragment 클래스를 통해 동일 기능에 액세스할 수 있습니다. Android 지원 라이브러리도 포함해야 합니다.

참고: getMapAsync()가 메인 스레드에서 호출되어야 콜백이 메인 스레드에서 실행됩니다. Google Play 서비스가 사용자의 기기에 설치되지 않은 경우, 사용자가 Play 서비스를 설치할 때까지 콜백이 실행되지 않습니다.

onMapReady(GoogleMap) 콜백 메서드를 사용하여 GoogleMap 객체에 핸들을 가져옵니다. 지도를 사용할 준비가 되면 콜백이 실행됩니다. 이 콜백은 GoogleMap의 null이 아닌 인스턴스를 제공합니다. GoogleMap 객체를 사용하여 가령 지도의 뷰 옵션을 설정하거나 마커를 추가할 수 있습니다.

@Override
public void onMapReady(GoogleMap map) {
    map.addMarker(new MarkerOptions()
        .position(new LatLng(0, 0))
        .title("Marker"));
}

지도 객체

Google Maps Android API는 Android 애플리케이션에 Google 지도를 표시할 수 있게 해줍니다. 이 지도는 모바일용 Google 지도(GMM) 앱에서 보는 것과 같은 형태를 취하고 API는 여러 가지 동일한 기능을 보여줍니다. GMM 애플리케이션과 Google Maps Android API가 표시하는 지도 사이의 두드러진 차이점 두 가지는 다음과 같습니다.

  • API가 표시하는 지도 타일에는 개인화된 스마트 아이콘과 같은 개인화된 콘텐츠가 없습니다.
  • 지도의 모든 아이콘이 클릭 가능한 것은 아닙니다. 예를 들어, 대중교통 정류장 아이콘은 클릭할 수 없습니다. 그러나 지도에 추가하는 마커는 클릭할 수 있습니다. API에는 다양한 마커 상호작용에 대한 리스너 콜백 인터페이스가 있습니다.

또한, API는 지도 작성 기능 이외에도 Android UI 모델과 일치하는 상호작용을 모두 지원합니다. 예를 들어, 사용자 제스처에 반응하는 리스너를 정의하여 지도와의 상호작용을 설정할 수 있습니다.

지도 객체 사용 시 주요 클래스는 GoogleMap 클래스입니다. GoogleMap은 애플리케이션 내에서 지도 객체를 모델링합니다. UI 내에서 지도는 MapFragment 또는 MapView 객체로 표현됩니다.

GoogleMap은 다음 작업을 자동으로 처리합니다.

  • Google Maps 서비스에 연결.
  • 지도 타일 다운로드.
  • 기기 화면에 타일 표시.
  • 팬이나 확대/축소 같은 다양한 컨트롤 표시.
  • 지도를 이동하거나 확대/축소를 통해 팬과 확대/축소 제스처에 응답.

이 자동 작업과 더불어 API의 객체와 메서드로 지도의 동작을 제어할 수 있습니다. 예를 들어, GoogleMap은 지도상의 키 입력과 터치 제스처에 응답하는 콜백 메서드가 있습니다. 또한 GoogleMap에 제공한 객체를 사용하여 지도에 마커 아이콘을 설정하고 오버레이를 추가할 수 있습니다.

MapFragment

MapFragment는 Android Fragment 클래스의 서브클래스로, Android 프래그먼트에 지도를 배치할 수 있게 해줍니다. MapFragment 객체는 지도의 컨테이너 역할을 하며, GoogleMap 객체에 액세스를 제공합니다.

View와 달리 Fragment는 액티비티에서 동작이나 사용자 인터페이스의 일부를 나타냅니다. 여러 개의 프래그먼트를 하나의 액티비티에 조합하여 창이 여러 개인 UI를 구축할 수 있으며, 하나의 프래그먼트를 여러 액티비티에서 재사용할 수 있습니다. 자세한 내용은 프래그먼트에 관한 Android 문서를 참조하세요.

MapView

MapView는 AndroidView 클래스의 서브클래스로, Android View에 지도를 배치할 수 있게 해줍니다. View는 화면의 사각형 영역을 나타내며, Android 애플리케이션과 위젯의 기본적인 구성 블록입니다. MapFragment와 마찬가지로 MapView는 지도의 컨테이너로 작동하고, GoogleMap 객체를 통해 핵심 지도 기능을 노출합니다.

완전 대화형 모드에서 API를 사용하는 경우, MapView 클래스 사용자는 액티비티 수명 주기 메서드를 MapView 클래스의 해당 메서드(onCreate(), onStart(), onResume(), onPause(), onStop(), onDestroy(), onSaveInstanceState()onLowMemory())로 전달해야 합니다. GitHub의 ApiDemos 리포지토리에는 액티비티 수명 주기 메서드를 전달하는 방법을 보여주는 샘플이 포함되어 있습니다. 라이트 모드에서 API를 사용하는 경우, 수명 주기 이벤트 전달은 선택 사항입니다. 자세한 내용은 라이트 모드 문서를 참조하세요.

지도 유형

Google Maps Android API에서 사용할 수 있는 지도 유형에는 여러 가지가 있습니다. 지도 유형은 지도의 전체적 표현을 결정합니다. 예를 들어, 일반적으로 지도책에는 경계를 표시하는 데 중점을 둔 정치 지도와 도시나 지역의 모든 도로를 보여주는 도로 지도가 포함됩니다.

Google Maps Android API는 네 가지 유형의 지도와 아예 지도를 표시하지 않는 옵션을 제공합니다.

일반
일반적 도로 지도. 도로, 인공적 지형지물 및 중요한 자연적 지형지물(예: 강)이 표시됩니다. 도로와 지형지물 레이블도 보입니다.
하이브리드
도로 지도가 추가된 위성 사진 데이터. 도로와 지형지물 레이블도 보입니다.
위성
위성 사진 데이터. 도로와 지형지물 레이블은 보이지 않습니다.
지형
지형 데이터. 지도에 색상, 등고선, 레이블, 원근 음영이 포함됩니다. 일부 도로와 레이블도 보입니다.
없음
타일이 없습니다. 타일이 로드되지 않은 빈 그리드로 지도가 렌더링됩니다.

지도 유형 변경

지도의 유형을 설정하려면 GoogleMap 객체의 setMapType() 메서드를 호출하고 GoogleMap에서 정의된 유형 상수 중 하나를 전달합니다. 예를 들어, 위성 지도를 표시하려면:

GoogleMap map;
...
// Sets the map type to be "hybrid"
map.setMapType(GoogleMap.MAP_TYPE_HYBRID);

아래 이미지는 동일한 위치의 일반, 하이브리드, 지형 지도를 비교한 모습입니다.

MapType Comparison

실내 지도

높은 수준의 확대/축소에서 지도는 공항, 쇼핑몰, 대형 소매점, 대중교통 정류장 등과 같은 실내 공간 평면도를 표시합니다. 이런 평면도를 실내 지도라고 부르며, '일반' 및 '위성' 지도 유형(GoogleMap.MAP_TYPE_NORMALGoogleMap.MAP_TYPE_SATELLITE)에서 표시됩니다. 사용자가 지도를 확대하면 자동으로 활성화되고 축소하면 서서히 사라집니다.

지원 중단 고지: 향후 릴리스에서 실내 지도는 normal 지도 유형에서만 사용할 수 있습니다. 향후 릴리스부터 실내 지도는 satellite, terrain 또는 hybrid 지도에서 지원되지 않습니다. 실내 지도가 지원되지 않는 경우라도, isIndoorEnabled()가 지금과 같이 계속해서 setIndoorEnabled()를 통해 설정된 값을 반환합니다. 기본적으로 setIndoorEnabledtrue입니다. 릴리스 노트는 실내 지도 지원이 해당 지도 유형에서 사용할 수 없게 되었을 때 알려줍니다.

Indoor map example

API에서 실내 지도 사용

다음은 API의 실내 지도 기능 요약입니다.

GoogleMap.setIndoorEnabled(false)를 호출하여 실내 지도를 비활성화할 수 있습니다. 기본적으로 실내 지도는 활성화되어 있습니다. 실내 지도는 한 번에 하나의 지도에 표시됩니다. 기본적으로 이는 앱에 추가되는 첫 번째 지도입니다. 다른 지도에 실내 지도를 표시하려면, 첫 번째 지도에서 비활성화하고 두 번째 지도에서 setIndoorEnabled(true)를 호출합니다. 기본 레벨 선택기(층 선택기)를 비활성화하려면 GoogleMap.getUiSettings().setIndoorLevelPickerEnabled(false)를 호출합니다. 자세한 내용은 지도와 상호작용을 참조하세요. GoogleMap의 인터페이스인 OnIndoorStateChangeListener를 통해, 새 건물이 포커스 안에 들어오거나 건물에서 새로운 레벨이 활성화되면 호출할 리스너를 설정할 수 있습니다. 자세한 내용은
지도와 상호작용을 참조하세요.
GoogleMap.getFocusedBuilding()은 현재 포커스 안에 있는 건물을 제공합니다. 그러면 IndoorBuilding.getActiveLevelIndex()를 호출하여 현재 활성화된 레벨을 찾을 수 있습니다. IndoorBuildingIndoorLevel 객체에서 이용 가능한 모든 정보를 보려면 참조 문서를 참조하세요.

평면도 추가

실내 지도(평면도)는 위치 선택에서 사용할 수 있습니다. 애플리케이션에서 강조 표시하고 싶은 건물에 평면도 데이터를 사용할 수 없는 경우:

초기 상태 구성

Maps API는 애플리케이션의 필요에 맞게 지도의 초기 상태를 구성할 수 있게 해줍니다. 다음을 지정할 수 있습니다.

  • 위치, 확대/축소, 베어링 및 틸트를 포함한 카메라 위치. 카메라 위치 지정에 대한 자세한 내용은 지도 뷰 변경을 참조하세요.
  • 지도 유형.
  • 확대/축소 버튼 및/또는 나침반의 화면 표시 여부.
  • 사용자가 카메라 조작에 사용할 수 있는 제스처.
  • 라이트 모드 활성화 여부. 라이트 모드 지도는 전체 API가 제공하는 기능의 일부를 지원하는 지도의 비트맵 이미지입니다.

지도를 액티비티의 레이아웃 파일에 추가했다면 XML을 통해, 또는 지도를 프로그래밍 방식으로 추가했다면 해당 방식으로 지도의 초기 상태를 구성할 수 있습니다.

XML 특성 사용

이 섹션에서는 XML 레이아웃 파일을 사용하여 애플리케이션에 지도를 추가한 경우, 지도의 초기 상태를 설정하는 방법을 설명합니다.

Maps API는 레이아웃 파일에서 지도의 초기 상태를 직접 구성하는 데 사용할 수 있는 MapFragment 또는 MapView사용자 지정 XML 특성 집합을 정의합니다. 현재 다음 특성이 정의되어 있습니다.

  • mapType. 표시할 지도 유형을 지정할 수 있습니다. 유효한 값: none, normal, hybrid, satelliteterrain.
  • cameraTargetLat, cameraTargetLng, cameraZoom, cameraBearing, cameraTilt. 초기 카메라 위치를 지정할 수 있습니다. 카메라 위치 및 속성에 대한 자세한 내용은 여기를 참조하세요.
  • uiZoomControls, uiCompass. 지도에서 확대/축소 컨트롤과 나침반 표시 여부를 지정할 수 있습니다. 자세한 내용은 UiSettings를 참조하세요.
  • uiZoomGestures, uiScrollGestures, uiRotateGestures, uiTiltGestures. 지도와의 상호작용을 활성화/비활성화할 제스처를 지정할 수 있습니다. 자세한 내용은 UiSettings를 참조하세요.
  • zOrderOnTop. 지도 뷰의 화면을 창 상단에 배치할지 여부를 제어합니다. 자세한 내용은 SurfaceView.setZOrderOnTop(boolean)를 참조하세요. 여기에는 지도에 나타날 수 있는 모든 다른 뷰도 포함됩니다(예: 확대/축소 컨트롤, My Location 버튼).
  • useViewLifecycle. MapFragment에만 유효합니다. 이 특성은 지도의 수명 주기가 프래그먼트의 뷰 또는 프래그먼트 자체와 연동되어야 하는지 여부를 지정합니다. 자세한 내용은 여기를 참조하세요.
  • liteMode. true 값은 지도를 라이트 모드로 설정합니다. 라이트 모드 지도는 전체 API가 제공하는 기능의 일부를 지원하는 지도의 비트맵 이미지입니다. 이 특성의 기본값은 false입니다.

XML 레이아웃 파일 내에서 이러한 사용자 지정 특성을 사용하려면, 먼저 다음 네임스페이스 선언을 추가해야 합니다. 아무 네임스페이스나 선택할 수 있고 꼭 map을 사용하지 않아도 됩니다.

xmlns:map="http://schemas.android.com/apk/res-auto"

그런 다음 일반 Android 특성과 마찬가지로 레이아웃 구성 요소에 map: 접두사가 붙은 특성을 추가할 수 있습니다.

다음 XML 코드 스니펫은 몇 가지 사용자 지정 옵션으로 MapFragment를 구성하는 방법을 보여줍니다. 동일한 특성을 MapView에도 적용할 수 있습니다.

<fragment xmlns:android="http://schemas.android.com/apk/res/android"
  xmlns:map="http://schemas.android.com/apk/res-auto"
  android:name="com.google.android.gms.maps.SupportMapFragment"
  android:id="@+id/map"
  android:layout_width="match_parent"
  android:layout_height="match_parent"
  map:cameraBearing="112.5"
  map:cameraTargetLat="-33.796923"
  map:cameraTargetLng="150.922433"
  map:cameraTilt="30"
  map:cameraZoom="13"
  map:mapType="normal"
  map:uiCompass="false"
  map:uiRotateGestures="true"
  map:uiScrollGestures="false"
  map:uiTiltGestures="true"
  map:uiZoomControls="false"
  map:uiZoomGestures="true"/>

참고: Google Maps API 프리미엄 플랜 라이선스를 보유하고 Google Maps Android API를 사용하는 경우 각 속성에 m4b_라는 접두사를 붙여야 합니다. 예를 들어, 지도 유형 특성을 지정하는 경우, mapType이 아니라 m4b_mapType을 사용합니다. 또는 확대/축소 컨트롤을 지정하는 경우, uiZoomControls가 아니라 m4b_uiZoomControls를 사용합니다.

프로그래밍 방식으로

이 섹션은 프로그래밍 방식으로 애플리케이션에 지도를 추가한 경우, 지도의 초기 상태를 설정하는 방법을 설명합니다.

MapFragment(또는 MapView)를 프로그래밍 방식으로 추가한 경우, 지정된 옵션으로 GoogleMapOptions 객체에 전달하여 초기 상태를 구성할 수 있습니다. 사용 가능한 옵션은 위의 XML을 통한 방법과 정확히 동일합니다. 다음과 같이 GoogleMapOptions 객체를 생성할 수 있습니다.

GoogleMapOptions options = new GoogleMapOptions();

이어서 다음과 같이 구성합니다.

options.mapType(GoogleMap.MAP_TYPE_SATELLITE)
    .compassEnabled(false)
    .rotateGesturesEnabled(false)
    .tiltGesturesEnabled(false);

지도를 생성할 때 이 옵션을 적용하려면 다음 중 하나를 수행합니다.

지도 여백

이 동영상은 지도 여백의 예시를 보여줍니다.

Google 지도는 컨테이너 요소에 의해 정의된 전체 영역을 채우도록 구성되어 있습니다(일반적으로 MapView 또는 MapFragment). 지도가 나타나고 작동하는 방식 중 몇 가지는 컨테이너의 크기로 정의됩니다.

  • 카메라의 표적은 여백이 적용된 영역의 중심을 반영합니다.
  • 지도 컨트롤은 지도의 가장자리에 상대적으로 위치가 지정됩니다.
  • 저작권 선언 등의 법적 정보나 Google 로고는 지도 하단에 나타납니다.

GoogleMap.setPadding() 메서드를 사용하여 지도 가장자리 주변에 여백을 추가할 수 있습니다. 지도는 계속 전체 컨테이너를 채우지만, 텍스트와 컨트롤 배치, 지도 제스처, 카메라 이동은 마치 더 작은 공간에 배치된 것처럼 작동합니다. 그 결과 다음과 같은 변화가 나타납니다.

  • API 호출 또는 버튼 누름을 통한 카메라 이동(예: 나침반, My Location, 확대/축소 버튼)은 여백이 적용된 영역에 대해 상대적이 됩니다.
  • getCameraPosition()은 여백이 적용된 영역의 중심을 반환합니다.
  • Projection.getVisibleRegion()은 여백이 적용된 영역을 반환합니다.
  • UI 컨트롤은 지정된 픽셀 수를 기준으로 컨테이너 가장자리에서 오프셋됩니다.

여백은 지도의 일부분과 중첩되는 UI를 디자인할 때 유용합니다. 예를 들어, 아래 이미지에서는 지도의 위쪽과 오른쪽 가장자리를 따라 여백이 적용됩니다. 보이는 지도 컨트롤과 법적 고지 텍스트는 여백이 적용된 영역의 가장자리를 따라 표시되고(녹색), 지도는 계속 전체 컨테이너를 채웁니다(파란색). 이 예시에서 지도 컨트롤을 가리지 않고 지도의 오른쪽에 메뉴를 띄울 수 있습니다.

지도 여백

참고: Google Maps API 서비스 약관에 따라, 애플리케이션이 Google 로고나 저작권 고지를 제거하거나 가리지 말아야 합니다. 지도 여백을 사용하면 필요에 따라 이러한 요소의 위치를 조정할 수 있습니다. 지도 하단에 사용자 지정 UI를 표시하려면, 지도 하단에 여백을 추가하여 로고와 법적 고지가 항상 보이도록 해야 합니다.

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

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