15주년을 맞이한 Google Maps Platform - 최신 뉴스 및 공지사항 확인하기

지도 객체

지도는 API에서 GoogleMapMapFragment 클래스로 표현됩니다.

코드 샘플

GitHub의 ApiDemos 저장소에는 GoogleMap 객체 및 SupportMapFragment의 사용 방법을 보여주는 샘플이 포함되어 있습니다.

Android 앱에 지도 추가

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

  1. (이 단계는 한 번만 실행하면 됩니다.) 프로젝트 구성 가이드의 단계에 따라 API 및 키를 가져오고 Android 매니페스트에 필수 속성을 추가합니다.
  2. 지도를 처리할 ActivityFragment 객체를 추가합니다. 가장 쉬운 방법은 Activity의 레이아웃 파일에 <fragment> 요소를 추가하는 것입니다.
  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"/>

코드에서 ActivityMapFragment를 추가할 수도 있습니다. 새로운 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);

onMapReady(GoogleMap) 콜백 메서드를 사용하여 GoogleMap 객체의 핸들을 가져옵니다. 지도를 사용할 준비가 되면 콜백이 트리거되며 null이 아닌 GoogleMap 인스턴스를 제공합니다. 예를 들어 GoogleMap 객체를 사용하여 지도의 뷰 옵션을 설정하거나 아이콘을 추가할 수 있습니다.

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

지도 객체

Maps SDK for Android를 사용하면 Android 애플리케이션에 Google 지도를 표시할 수 있습니다. 이 지도는 Google 모바일 지도(GMM) 앱에 표시되는 지도와 모양이 동일하며 API에서 다수의 동일한 지형지물을 노출합니다. GMM 애플리케이션과 Maps SDK for Android가 표시하는 지도의 두드러진 차이점은 다음 두 가지입니다.

  • API에서 표시하는 지도 타일에는 맞춤 스마트 아이콘과 같은 맞춤 콘텐츠가 포함되지 않습니다.
  • 지도의 모든 아이콘이 클릭 가능한 것은 아닙니다. 예를 들어 대중교통 정류장 아이콘은 클릭할 수 없습니다. 하지만 지도에 추가하는 아이콘은 클릭할 수 있으며 API에는 다양한 아이콘 상호작용을 위한 리스너 콜백 인터페이스가 있습니다.

매핑 기능 외에도 API에서는 Android UI 모델과 일치하는 모든 상호작용을 지원합니다. 예를 들어 사용자 동작에 응답하는 리스너를 정의하여 지도와의 상호작용을 설정할 수 있습니다.

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

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

  • Google 지도 서비스에 연결
  • 지도 타일 다운로드
  • 기기 화면에 타일 표시
  • 이동(상하/좌우) 및 확대/축소와 같은 다양한 컨트롤 표시
  • 화면 이동 및 확대/축소 동작 시 지도를 이동하고 확대/축소하여 응답

이러한 자동 작업 외에 API의 객체 및 메서드를 사용하여 지도의 동작을 관리할 수 있습니다. 예를 들어 GoogleMap에는 지도상의 키 입력 및 터치 동작에 응답하는 콜백 메서드가 있습니다. GoogleMap에 제공하는 객체를 사용하여 지도에 아이콘을 설정하고 오버레이를 추가할 수도 있습니다.

MapFragment

Android Fragment 클래스의 하위 클래스인 MapFragment를 사용하면 Android 프래그먼트에 지도를 배치할 수 있습니다. MapFragment 객체는 지도의 컨테이너 역할을 하며 GoogleMap 객체에 액세스 권한을 제공합니다.

View와 달리 Fragment는 활동에서 동작 또는 사용자 인터페이스의 일부를 나타냅니다. 여러 프래그먼트를 하나의 활동에 결합하여 다중 창 UI를 만들고 프래그먼트를 여러 활동에 재사용할 수 있습니다. 자세한 내용은 프래그먼트에 관한 Android 문서를 참고하세요.

MapView

Android View 클래스의 하위 클래스인 MapView를 사용하면 Android View에 지도를 배치할 수 있습니다. View는 화면의 직사각형 영역을 나타내며 Android 애플리케이션 및 위젯 구축의 기본 구성요소입니다. MapFragment와 마찬가지로 MapView는 지도의 컨테이너 역할을 하며 GoogleMap 객체를 통해 핵심 지도 기능을 노출합니다.

완전 대화형 모드에서 API를 사용하는 경우 MapView 클래스의 사용자는 onCreate(), onStart(), onResume(), onPause(), onStop(), onDestroy(), onSaveInstanceState(), onLowMemory() 등의 활동 수명 주기 메서드를 MapView 클래스의 연관 메서드에 전달해야 합니다. GitHub의 ApiDemos 저장소에는 활동 수명 주기 메서드를 전달하는 방법을 보여주는 샘플이 포함되어 있습니다. 라이트 모드에서 API를 사용하는 경우 수명 주기 이벤트를 전달하지 않아도 됩니다. 자세한 내용은 라이트 모드 문서를 참고하세요.

지도 유형

Maps SDK for Android 내에서는 다양한 유형의 지도를 사용할 수 있습니다. 지도의 유형에 따라 지도의 전반적인 모양이 결정됩니다. 예를 들어 지도책에는 일반적으로 경계 표시에 초점을 두는 행정구역 지도와 도시 또는 지역의 모든 도로를 표시하는 도로 지도가 포함됩니다.

Maps SDK for Android에서는 네 가지 유형의 지도 및 지도를 전혀 표시하지 않는 옵션을 제공합니다.

일반
일반적인 도로 지도입니다. 도로, 인공 지형지물, 주요 자연 지형지물(예: 강)을 표시합니다. 도로 및 지형지물 라벨도 표시됩니다.
하이브리드
도로 지도가 추가된 위성 사진 데이터입니다. 도로 및 지형지물 라벨도 표시됩니다.
위성
위성 사진 데이터입니다. 도로 및 지형지물 라벨은 표시되지 않습니다.
지형
지형 데이터입니다. 지도에 색상, 등고선, 라벨, 원근감을 나타내는 명암이 포함됩니다. 도로 및 라벨도 일부 표시됩니다.
없음
타일이 없습니다. 지도가 타일이 로드되지 않은 빈 그리드로 렌더링됩니다.

지도 유형 변경

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

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

아래의 이미지는 동일한 위치의 일반, 하이브리드 및 지형 지도를 비교하여 보여줍니다.

MapType 비교

실내 지도

높은 확대/축소 수준에서는 공항, 쇼핑몰, 대형 소매점, 환승역/정류장과 같은 실내 공간의 평면도가 지도에 표시됩니다. 실내 지도라고 하는 이 평면도는 '일반' 및 '위성' 지도 유형(GoogleMap.MAP_TYPE_NORMALGoogleMap.MAP_TYPE_SATELLITE)의 경우 표시되며 사용자가 확대하면 자동으로 사용 설정되고 지도가 축소되면 사라집니다.

지원 중단 알림: 향후 출시 버전에서는 normal 지도 유형에서만 실내 지도를 사용할 수 있습니다. 향후 출시 버전부터 satellite, terrain 또는 hybrid 지도에서는 실내 지도가 지원되지 않습니다. 실내 지도가 지원되지 않는 경우에도 isIndoorEnabled()에서는 계속해서 지금처럼 setIndoorEnabled()를 통해 설정된 값을 반환합니다. setIndoorEnabled의 기본값은 true입니다. 이러한 지도 유형에서 실내 지도가 지원되지 않게 되면 출시 노트를 통해 알려드립니다.

실내 지도의 예

API에서 실내 지도 사용

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

  • GoogleMap.setIndoorEnabled(false)를 호출하여 실내 지도를 사용 중지할 수 있습니다. 기본적으로 실내 지도는 사용 설정되어 있습니다. 실내 지도는 한 번에 하나의 지도에 표시됩니다. 기본적으로 이 지도가 앱에 추가되는 첫 번째 지도입니다. 실내 지도를 다른 지도에 표시하려면 첫 번째 지도에서 사용 중지한 다음 두 번째 지도에서 setIndoorEnabled(true)를 호출합니다.
  • 기본 층 선택기를 사용 중지하려면 GoogleMap.getUiSettings().setIndoorLevelPickerEnabled(false)를 호출합니다. 자세한 내용은 지도와 상호작용을 참고하세요.
  • Google 지도의 인터페이스인 OnIndoorStateChangeListener를 사용하면 새 건물에 초점이 맞춰지거나 건물에서 새 층이 활성화될 때 호출되는 리스너를 설정할 수 있습니다. 자세한 내용은 지도와 상호작용을 참고하세요.
  • GoogleMap.getFocusedBuilding()은 현재 초점이 맞춰진 건물을 보여줍니다. 그런 다음 IndoorBuilding.getActiveLevelIndex()를 호출하여 현재 활성 층을 찾을 수 있습니다. IndoorBuildingIndoorLevel 객체에서 사용할 수 있는 모든 정보를 보려면 참조 문서를 참고하세요.

기본 지도의 스타일을 지정해도 실내 지도에는 영향을 미치지 않습니다.

평면도 추가

실내 지도(평면도)는 일부 위치에서 사용할 수 있습니다. 애플리케이션에서 강조하려는 건물의 평면도 데이터를 사용할 수 없는 경우 다음과 같이 할 수 있습니다.

  • Google 지도에 직접 평면도를 추가합니다. 이렇게 하면 모든 Google 지도 사용자가 평면도를 사용할 수 있게 됩니다.
  • 평면도를 지도에 지면 오버레이 또는 타일 오버레이로 표시합니다. 이렇게 하면 애플리케이션 사용자만 평면도를 볼 수 있습니다.

교통정보 레이어

사용자에게 상단에 교통량 정보가 표시된 지도를 제공할 수 있습니다. 이 레이어는 지역 교통상황을 시각적으로 요약하여 보여줍니다. setTrafficEnabled() 메서드를 호출하여 교통정보 레이어를 사용 설정하거나 중지할 수 있으며 isTrafficEnabled() 메서드를 호출하여 교통정보 레이어가 현재 사용 설정되어 있는지 확인할 수 있습니다. 다음 예는 교통정보 레이어가 지도에 표시되는 방법을 보여줍니다.

교통정보 레이어를 보여주는 Google 지도

초기 상태 구성

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

  • 위치, 확대/축소, 방위, 기울기 등 카메라 위치. 카메라 위치 지정에 관한 자세한 내용은 카메라 및 뷰를 참고하세요.
  • 지도 유형
  • 확대/축소 버튼 또는 나침반이 화면에 표시되는지 여부
  • 사용자가 카메라를 조작하기 위해 사용할 수 있는 동작
  • 라이트 모드의 사용 설정 여부. 라이트 모드 지도는 전체 API에서 제공하는 기능의 일부를 지원하는 지도의 비트맵 이미지입니다.

지도의 초기 상태는 활동의 레이아웃 파일에 지도를 추가한 경우 XML을 통해, 프로그래매틱 방식으로 지도를 추가한 경우 프로그래매틱 방식으로 구성할 수 있습니다.

XML 속성 사용

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

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

  • mapType: 표시할 지도 유형을 지정할 수 있습니다. 유효한 값은 none, normal, hybrid, satellite, terrain입니다.
  • cameraTargetLat, cameraTargetLng, cameraZoom, cameraBearing, cameraTilt: 초기 카메라 위치를 지정할 수 있습니다. 카메라 위치 및 속성에 관한 자세한 내용은 여기를 참고하세요.
  • uiZoomControls, uiCompass: 확대/축소 컨트롤 및 나침반을 지도에 표시할지 여부를 지정할 수 있습니다. 자세한 내용은 UiSettings를 참고하세요.
  • uiZoomGestures, uiScrollGestures, uiRotateGestures, uiTiltGestures: 지도와의 상호작용을 위해 사용 설정/사용 중지할 동작을 지정할 수 있습니다. 자세한 내용은 UiSettings를 참고하세요.
  • zOrderOnTop: 지도뷰의 표면을 창 상단에 배치할지 여부를 관리합니다. 자세한 내용은 SurfaceView.setZOrderOnTop(boolean)을 참고하세요. 이 속성은 지도에 표시할 수 있는 기타 모든 뷰(예: 확대/축소 컨트롤, 내 위치 버튼)에 적용됩니다.
  • 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"/>

프로그래매틱 방식

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

프로그래매틱 방식으로 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를 호출하거나 버튼(예: 나침반, 내 위치, 확대/축소 버튼)을 누르는 경우 패딩 처리된 영역을 기준으로 카메라가 움직입니다.
  • getCameraPosition()에서 패딩 처리된 영역의 중심을 반환합니다.
  • Projection.getVisibleRegion()에서 패딩 처리된 영역을 반환합니다.
  • UI 컨트롤은 컨테이너의 가장자리에서 지정된 픽셀 수만큼 떨어집니다.

패딩은 지도의 일부와 겹쳐지는 UI를 디자인할 때 도움이 될 수 있습니다. 예를 들어 아래 이미지의 지도는 상단 및 오른쪽 가장자리를 따라 패딩 처리됩니다. 화면에 보이는 지도 컨트롤과 법적 문구는 패딩 처리된 영역(녹색)의 가장자리를 따라 표시되며 지도는 전체 컨테이너(파란색)를 계속 채웁니다. 이 예에서는 지도 컨트롤을 가리지 않고 지도 오른쪽에 메뉴를 띄울 수 있습니다.

지도 패딩

지도 현지화

앱에 MapView 또는 MapFragment를 추가하는 경우 지도의 텍스트 요소가 사용자의 기기 설정과 위치에 따라 적절한 언어로 표시됩니다 . resConfigs 항목을 Gradle 파일에 추가하여 앱에서 사용하는 언어를 지원되는 모든 언어의 일부로 제한할 수 있습니다. 이 기능은 사용되지 않는 언어를 제거하는 데 유용하며 앱의 바이너리 크기도 감소합니다. 예:

defaultConfig {
    resConfigs "en", "fr", "es", "zh", "de", "ja", "ru", "ko", "pt", "in"
}

Android 앱 현지화에 대해 자세히 알아보세요.