모든 준비를 마쳤습니다!

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

Google Maps Android API 활성화

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

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

마커

마커는 지도에서 단일 위치를 나타냅니다. 기본 색상을 변경하거나 마커 아이콘을 사용자 지정 이미지로 교체하는 방식으로 마커를 사용자 지정할 수 있습니다. 정보 창은 마커에 추가 컨텍스트를 제공할 수 있습니다.

코드 샘플

Github의 ApiDemos 리포지토리에는 다양한 마커 기능을 보여주는 샘플이 포함되어 있습니다.

소개

마커는 지도에서 위치를 식별합니다. 기본 마커는 Google 지도 디자인에 공통되는 표준 아이콘을 사용합니다. API로 아이콘 색상, 이미지 또는 앵커 지점을 변경할 수 있습니다. 마커는 Marker 유형의 객체이고, GoogleMap.addMarker(markerOptions) 메서드로 지도에 추가됩니다.

마커는 대화형으로 설계되었습니다. 기본적으로 click 이벤트를 수신하고 종종 이벤트 리스너와 함께 사용되어 정보 창을 나타냅니다. 마커의 draggable 속성을 true로 설정하면 사용자가 마커의 위치를 변경할 수 있게 됩니다. 길게 누르면 마커를 이동하는 기능이 활성화됩니다.

기본적으로 사용자가 마커를 누르면 지도 툴바가 지도 오른쪽 하단에 나타나고, 사용자가 Google 지도 모바일 앱에 신속히 액세스할 수 있습니다. 툴바를 비활성화할 수도 있습니다. 자세한 내용은 컨트롤 가이드를 참조하세요.

마커 시작하기

이 Maps Live 에피소드는 Google Maps Android API를 사용하여 마커를 지도에 추가하는 기본적인 내용을 다룹니다.

마커 추가

다음 예시는 지도에 마커를 추가하는 방법을 보여줍니다. 마커는 10,10 좌표에 생성되고 클릭하면 정보 창에 'Hello world' 문자열을 표시합니다.

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

마커에 대한 추가 정보 표시

일반적인 요구사항은 사용자가 지도에서 마커를 누르면 장소 또는 위치에 대한 추가 정보를 표시하는 것입니다. 정보 창 가이드를 참조하세요.

데이터와 마커 연결

다음 코드 샘플에서 보듯이 Marker.setTag()를 사용하여 임의의 데이터 객체를 마커와 함께 저장할 수 있고 Marker.getTag()를 사용하여 데이터 객체를 검색할 수 있습니다.

/**
 * A demo class that stores and retrieves data objects with each marker.
 */
public class MarkerDemoActivity extends FragmentActivity implements
        OnMarkerClickListener,
        OnMapReadyCallback {

    private static final LatLng PERTH = new LatLng(-31.952854, 115.857342);
    private static final LatLng SYDNEY = new LatLng(-33.87365, 151.20689);
    private static final LatLng BRISBANE = new LatLng(-27.47093, 153.0235);

    private Marker mPerth;
    private Marker mSydney;
    private Marker mBrisbane;

    private GoogleMap mMap;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.marker_demo);

        SupportMapFragment mapFragment =
                (SupportMapFragment) getSupportFragmentManager().findFragmentById(R.id.map);
        mapFragment.getMapAsync(this);
    }

    /** Called when the map is ready. */
    @Override
    public void onMapReady(GoogleMap map) {
        mMap = map;

        // Add some markers to the map, and add a data object to each marker.
        mPerth = mMap.addMarker(new MarkerOptions()
                .position(PERTH)
                .title("Perth");
        mPerth.setTag(0);

        mSydney = mMap.addMarker(new MarkerOptions()
                .position(SYDNEY)
                .title("Sydney");
        mSydney.setTag(0);

        mBrisbane = mMap.addMarker(new MarkerOptions()
                .position(BRISBANE)
                .title("Brisbane");
        mBrisbane.setTag(0);

        // Set a listener for marker click.
        mMap.setOnMarkerClickListener(this);
    }

    /** Called when the user clicks a marker. */
    @Override
    public boolean onMarkerClick(final Marker marker) {

        // Retrieve the data from the marker.
        Integer clickCount = (Integer) marker.getTag();

        // Check if a click count was set, then display the click count.
        if (clickCount != null) {
            clickCount = clickCount + 1;
            marker.setTag(clickCount);
            Toast.makeText(this,
                           marker.getTitle() +
                           " has been clicked " + clickCount + " times.",
                           Toast.LENGTH_SHORT).show();
        }

        // Return false to indicate that we have not consumed the event and that we wish
        // for the default behavior to occur (which is for the camera to move such that the
        // marker is centered and for the marker's info window to open, if it has one).
        return false;
    }
}

다음은 마커 데이터를 저장하고 검색하는 데 유용한 시나리오의 몇 가지 예입니다.

  • 앱은 다양한 유형의 마커를 제공할 수 있으며 사용자가 클릭할 때 다르게 처리하려고 합니다. 이를 위해 유형을 나타내는 마커와 함께 String을 저장할 수 있습니다.
  • 고유한 레코드 식별자가 있는 시스템과 상호작용할 수 있으며, 여기서 마커는 해당 시스템의 특정 레코드를 나타냅니다.
  • 마커 데이터는 마커의 z-인덱스를 결정할 때 사용되는 우선 순위를 나타낼 수 있습니다.

드래그 가능한 마커

지도에 마커가 추가된 후 draggable 속성이 true로 설정되어 있으면 마커 위치를 변경할 수 있습니다. 마커를 길게 누르면 드래그가 활성화됩니다. 화면에서 손가락을 떼면 마커가 그 자리에 그대로 남아 있습니다.

마커는 기본적으로 드래그할 수 없습니다. 마커를 지도에 추가하기 전에 MarkerOptions.draggable(boolean)을 사용하거나 지도에 추가한 후에 Marker.setDraggable(boolean)을 사용하여 마크를 명시적으로 드래그 가능하게 설정해야 합니다. 마커 드래그 이벤트에 설명된 것처럼 마커에서 드래그 이벤트를 수신할 수 있습니다.

아래 스니펫은 오스트레일리아 퍼스에 드래그 가능한 마커를 추가합니다.

static final LatLng PERTH = new LatLng(-31.90, 115.86);
Marker perth = mMap.addMarker(new MarkerOptions()
                          .position(PERTH)
                          .draggable(true));

마커 사용자 지정

이 동영상은 마커를 사용하여 지도에 위치를 시각화하는 방법을 보여줍니다.

마커는 기본 아이콘 대신 사용자 지정 이미지를 정의할 수 있습니다. 아이콘 정의에는 마커의 시각적 동작에 영향을 미치는 다양한 속성들을 설정하는 과정이 포함됩니다.

마커는 다음 속성을 통해 사용자 지정을 지원합니다.

위치(필수)
지도에서 마커의 위치에 대한 LatLng 값입니다. 이는 Marker 객체의 유일한 필수 속성입니다.
앵커
마커의 LatLng 위치에 배치될 이미지의 지점. 기본값은 이미지의 하단 중앙입니다.
알파
마커의 투명도를 설정합니다. 기본값은 1.0입니다.
제목
사용자가 마커를 눌렀을 때 정보 창에 표시되는 문자열.
스니펫
제목 아래에 표시되는 추가 텍스트.
아이콘
기본 마커 이미지 대신 표시되는 비트맵.
드래그 가능
사용자가 마커를 이동할 수 있게 하려면 true로 설정합니다. 기본값은 false입니다.
가시성
마커가 보이지 않게 하려면 false로 설정합니다. 기본값은 true입니다.
평면 또는 빌보드 방향
기본적으로 마커는 화면과 반대쪽 방향이므로, 카메라로 회전하거나 틸트할 수 없습니다. 평면 마커는 지표면과 반대쪽 방향이며, 카메라로 회전과 틸트가 가능합니다. 두 유형의 마커 모두 확대/축소에 따라 크기가 변경되지 않습니다. 이 효과를 원하면 GroundOverlays를 사용합니다.
회전
시계방향으로 도 단위로 지정되는 마커의 방향. 마커가 평면인 경우 기본 위치가 변경됩니다. 평면 마커의 기본 위치는 북쪽 정렬입니다. 마커가 평면이 아닌 경우, 기본 위치는 위를 가리키고 마커가 항상 카메라를 마주하도록 회전합니다.

아래 스니펫은 기본 아이콘으로 간단한 마커를 생성합니다.

static final LatLng MELBOURNE = new LatLng(-37.813, 144.962);
Marker melbourne = mMap.addMarker(new MarkerOptions()
                          .position(MELBOURNE));

마커 색상 사용자 지정

BitmapDescriptor 객체를 icon() 메서드에 전달하여 기본 마커 이미지 색상을 사용자 지정할 수 있습니다. BitmapDescriptorFactory 객체에서 사전 지정된 색상 집합을 사용하거나, BitmapDescriptorFactory.defaultMarker(float hue) 메서드로 사용자 지정 마커 색상을 설정할 수 있습니다. 색조는 0~360 사이의 값이며, 색상환의 지점을 나타냅니다.

static final LatLng MELBOURNE = new LatLng(-37.813, 144.962);
Marker melbourne = mMap.addMarker(new MarkerOptions()
                          .position(MELBOURNE)
                          .icon(BitmapDescriptorFactory.defaultMarker(BitmapDescriptorFactory.HUE_AZURE)));

마커 투명도 사용자 지정

MarkerOptions.alpha() 메서드로 마커의 투명도를 제어할 수 있습니다. 알파는 0.0~1.0 사이의 부동 소수점으로 지정되어야 하며, 여기서 0은 완전 투명을, 1은 완전 불투명을 나타냅니다.

static final LatLng MELBOURNE = new LatLng(-37.813, 144.962);
Marker melbourne = mMap.addMarker(new MarkerOptions()
                          .position(MELBOURNE)
                          .alpha(0.7f));

마커 이미지 사용자 지정

기본 마커 이미지를 보통 '아이콘'이라고 부르는 사용자 지정 마커 이미지로 교체할 수 있습니다. 사용자 지정 아이콘은 항상 BitmapDescriptor로 설정되고, BitmapDescriptorFactory 클래스에 있는 메서드 중 하나를 사용하여 정의됩니다.

fromAsset(String assetName)
assets 디렉토리에 있는 비트맵 이미지를 사용하여 사용자 지정 마커를 생성합니다.
fromBitmap(Bitmap image)
비트맵 이미지에서 사용자 지정 마커를 생성합니다.
fromFile(String fileName)
내부 저장소에 있는 비트맵 이미지 파일의 이름을 사용하여 사용자 지정 아이콘을 생성합니다.
fromPath(String absolutePath)
비트맵 이미지의 절대 파일 경로에서 사용자 지정 마커를 생성합니다.
fromResource(int resourceId)
비트맵 이미지의 리소스 ID를 사용하여 사용자 지정 마커를 생성합니다.

아래 스니펫은 사용자 지정 아이콘으로 마커를 생성합니다.

  private static final LatLng MELBOURNE = new LatLng(-37.813, 144.962);
  private Marker melbourne = mMap.addMarker(new MarkerOptions()
                            .position(MELBOURNE)
                            .title("Melbourne")
                            .snippet("Population: 4,137,400")
                            .icon(BitmapDescriptorFactory.fromResource(R.drawable.arrow)));

마커 평면화

마커 아이콘은 일반적으로 화면에 상대적으로 그려지므로, 지도를 회전, 틸트, 확대/축소하더라도 마커의 방향이 변경되지 않습니다. 마커의 방향을 지구에 대해 평평하게 설정할 수 있습니다. 이 방향을 향하는 마커는 지도가 회전할 때 회전하고 지도가 틸트될 때 시점을 바꿉니다. 평면 마커는 지도가 확대/축소될 때 크기를 유지합니다.

마커의 방향을 바꾸려면 마커의 flat 속성을 true로 설정합니다.

static final LatLng PERTH = new LatLng(-31.90, 115.86);
Marker perth = mMap.addMarker(new MarkerOptions()
                          .position(PERTH)
                          .flat(true));

마커 회전

Marker.setRotation() 메서드를 사용하여 앵커 지점을 중심으로 마커를 회전할 수 있습니다. 회전은 기본 위치에서부터 시계 방향으로 도 단위로 측정됩니다. 마커가 지도에서 평면인 경우 기본 위치는 북쪽입니다. 마커가 평면이 아닌 경우, 기본 위치는 위를 가리키고 마커가 항상 카메라를 마주하도록 회전합니다.

아래 예시는 마커를 90° 회전합니다. 앵커 지점을 0.5,0.5으로 설정하면 마커가 베이스가 아니라 중앙을 기준으로 회전합니다.

static final LatLng PERTH = new LatLng(-31.90, 115.86);
Marker perth = mMap.addMarker(new MarkerOptions()
                          .position(PERTH)
                          .anchor(0.5,0.5)
                          .rotation(90.0));

마커 Z-인덱스

Z-인덱스는 이 마커의 스택 순서를 지도의 다른 마커와 비교하여 지정합니다. z-인덱스가 높은 마커는 z-인덱스가 낮은 마커 위에 그려집니다. 기본 z-인덱스 값은 0입니다.

다음 코드 스니펫에서 보듯이 MarkerOptions.zIndex()를 호출하여 마커의 옵션 객체에서 z-인덱스를 설정합니다.

@Override
public void onMapReady(GoogleMap map) {
    map.addMarker(new MarkerOptions()
        .position(new LatLng(10, 10))
        .title("Marker z1")
        .zIndex(1.0f));
}

마커의 z-인덱스는 Marker.getZIndex()를 호출하여 액세스하고 Marker.setZIndex()를 호출하여 변경할 수 있습니다.

마커는 다른 오버레이의 z-인덱스에 관계없이 항상 타일 계층 및 기타 비 마커 오버레이(그라운드 오버레이, 폴리라인, 폴리곤 및 기타 셰이프) 위에 그려집니다. 마커는 다른 오버레이와 비교하여 별도의 z-인덱스 그룹에 있는 것으로 간주됩니다.

아래의 클릭 이벤트에서 z-인덱스의 효과를 참조하세요.

마커 이벤트 처리

Maps API를 사용하여 마커 이벤트를 수신하고 응답할 수 있습니다. 이 이벤트를 수신하려면 마커가 속한 GoogleMap 객체에서 해당 리스너를 설정해야 합니다. 이벤트가 지도 상의 마커 중 하나에서 발생하면 리스너의 콜백이 호출되고 해당 Marker 객체가 매개변수로 전달됩니다. 이 Marker 객체와 Marker 객체에 대한 자체 참조를 비교하려면 ==이 아니라 equals()를 사용해야 합니다.

다음 이벤트를 수신할 수 있습니다:

마커 클릭 이벤트

OnMarkerClickListener를 사용하여 마커에서 클릭 이벤트를 수신할 수 있습니다. 지도에 이 리스너를 설정하려면 GoogleMap.setOnMarkerClickListener(OnMarkerClickListener)를 호출합니다. 사용자가 마커를 클릭하면 onMarkerClick(Marker)가 호출되고 마커가 인수로 전달됩니다. 이 메서드는 이벤트를 소비했는지 여부를 나타내는 부울을 반환합니다(예: 기본 동작을 억제하고 싶은 경우). 이 메서드가 false를 반환하면 사용자 지정 동작과 함께 기본 동작이 발생합니다. 마커 클릭 이벤트의 기본 동작은 정보 창(사용 가능한 경우)을 표시하고 마커가 지도의 중앙에 오도록 카메라를 이동하는 것입니다.

클릭 이벤트에서 z-인덱스의 효과:

  • 사용자가 마커의 클러스터를 클릭하면 z-인덱스가 가장 높은 마커에 대해 클릭 이벤트가 트리거됩니다.
  • 클릭당 하나 이하의 이벤트가 트리거됩니다. 다시 말해, z-인덱스 값이 더 낮은 마커나 기타 오버레이로는 클릭이 전달되지 않습니다.
  • 마커의 클러스터를 클릭하면 후속 클릭이 클러스터를 차례로 순환하면서 각각을 차례로 선택합니다. 순환 순서는 먼저 z-인덱스가 우선하고 그런 다음 클릭 지점의 근접도에 따라 적용됩니다.
  • 사용자가 클러스터에 근접하지 않는 지점을 클릭하면 API가 처음부터 시작되도록 클러스터를 다시 계산하고 클릭 사이클의 상태를 다시 설정합니다.
  • 클릭 이벤트는 순환을 다시 시작하기 전에 마커 클러스터를 통해 다른 셰이프 및 오버레이에 적용됩니다.
  • 마커는 다른 오버레이의 z-인덱스에 관계없이 다른 오버레이 또는 셰이프(폴리라인, 폴리곤, 원 및/또는 그라운드 오버레이)과 비교하여 별도의 z-인덱스 그룹에 있는 것으로 간주됩니다. 여러 개의 마커, 오버레이나 셰이프가 서로 중첩된 경우, 먼저 클릭 이벤트가 마커의 클러스터에 대해 적용된 다음, z-인덱스 값 기반의 클릭 가능한 다른 오버레이나 셰이프에 대해 클릭 이벤트가 트리거됩니다.

마커 드래그 이벤트

OnMarkerDragListener를 사용하여 마커의 드래그 이벤트를 수신할 수 있습니다. 지도에 이 리스너를 설정하려면 GoogleMap.setOnMarkerDragListener를 호출합니다. 마커를 드래그하려면 사용자가 마커를 길게 눌러야 합니다. 사용자가 화면에서 손가락을 떼면 마커가 그 자리에 그대로 있습니다. 마커를 드래그하면 처음에 onMarkerDragStart(Marker)가 호출됩니다. 마커를 드래그하는 동안 onMarkerDrag(Marker)가 지속적으로 호출됩니다. 드래그가 끝날 때 onMarkerDragEnd(Marker)가 호출됩니다. Marker.getPosition()을 호출하여 언제든지 마커의 위치를 구할 수 있습니다.

참고: 기본적으로 마커는 드래그할 수 없습니다. 마커는 사용자가 드래그하기 전에 드래그 가능하도록 명시적으로 설정되어야 합니다. 이 작업은 지도에 추가하기 전에 MarkerOptions.draggable(boolean)을 사용하거나 지도에 추가한 후에 Marker.setDraggable(boolean)을 사용하여 수행할 수 있습니다.

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

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