모든 준비를 마쳤습니다!

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

Google Maps Android API 활성화

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

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

셰이프

Google Maps API for Android는 애플리케이션에 맞게 사용자 지정할 수 있도록 지도에 셰이프를 추가하는 몇 가지 간단한 방법을 제공합니다.

  • Polyline은 일련의 연결된 선 세그먼트로, 원하는 어떤 형태도 취할 수 있고 지도에서 경로와 노선을 표시하는 데 사용할 수 있습니다.
  • Polygon는 지도에서 영역을 표시하는 데 사용할 수 있는 폐쇄된 셰이프입니다.
  • Circle은 지도에서 지표면에 그려지는 지리적으로 정확한 원의 투사입니다.

이 모든 셰이프는 여러 가지 속성을 변경함으로써 모습을 사용자 지정할 수 있습니다.

코드 샘플

GitHub의 ApiDemos 리포지토리에는 셰이프와 기능 사용법이 포함되어 있습니다.

폴리라인

Polyline 클래스는 지도에서 연결된 선 세그먼트 집합을 정의합니다. Polyline 객체는 LatLng 위치 집합으로 구성되고, 순차적 시퀀스에 따라 이 위치를 연결하는 일련의 선 세그먼트를 생성합니다.

이 동영상은 폴리라인을 사용하여 지도에 경로를 그려서 사용자가 목적지에 도착하도록 돕는 방법을 제시합니다.

폴리라인을 생성하려면 먼저 PolylineOptions 객체를 생성하고 여기에 점을 추가합니다. 점은 지표면의 한 지점을 나타내고 LatLng 객체로 표현됩니다. 선 세그먼트는 PolylineOptions 객체에 추가한 순서에 따라 점 사이에 그려집니다.

PolylineOptions 객체에 점을 추가하려면 PolylineOptions.add()를 호출합니다. 이 메서드는 다양한 매개변수를 취하므로 한 번에 여러 점을 추가할 수 있습니다. (점이 이미 목록에 있다면 PolylineOptions.addAll(Iterable<LatLng>) 을 호출해도 됩니다.)

그런 다음 GoogleMap.addPolyline(PolylineOptions)을 호출하여 지도에 폴리라인을 추가할 수 있습니다. 이 메서드는 Polyline 객체를 반환하며, 나중에 이 객체를 사용하여 폴리라인을 변경할 수 있습니다.

다음 코드 스니펫은 지도에 사각형을 추가하는 방법을 보여줍니다.

// Instantiates a new Polyline object and adds points to define a rectangle
PolylineOptions rectOptions = new PolylineOptions()
        .add(new LatLng(37.35, -122.0))
        .add(new LatLng(37.45, -122.0))  // North of the previous point, but at the same longitude
        .add(new LatLng(37.45, -122.2))  // Same latitude, and 30km to the west
        .add(new LatLng(37.35, -122.2))  // Same longitude, and 16km to the south
        .add(new LatLng(37.35, -122.0)); // Closes the polyline.

// Get back the mutable Polyline
Polyline polyline = myMap.addPolyline(rectOptions);

폴리라인이 추가된 후에 형태를 변경하려면, Polyline.setPoints()를 호출하고 폴리라인에 새로운 점 목록을 제공합니다.

지도에 폴리라인을 추가하기 전이나 추가한 후에 폴리라인의 모양을 사용자 지정할 수 있습니다. 자세한 내용은 아래 모양 사용자 지정 섹션을 참조하세요.

폴리라인 이벤트

기본적으로 폴리라인은 클릭할 수 없습니다. Polyline.setClickable(boolean)을 호출하여 클릭을 활성화/비활성화할 수 있습니다.

OnPolylineClickListener를 사용하여 클릭 가능한 폴리라인에서 클릭 이벤트를 수신합니다. 지도에서 이 리스너를 설정하려면, GoogleMap.setOnPolylineClickListener(OnPolylineClickListener)를 호출합니다. 사용자가 폴리라인을 클릭하면 onPolylineClick(Polyline) 콜백을 수신합니다.

폴리곤

Polygon 객체는 순차적 시퀀스에 따라 일련의 좌표로 구성된다는 점에서 Polyline 객체와 유사합니다. 그러나 폴리곤은 끝이 열려 있지 않고 내부가 채워진 닫힌 루프 안에 지역을 정의하도록 설계되었습니다.

Polyline을 추가하는 것과 동일한 방식으로 Polygon을 지도에 추가할 수 있습니다. 먼저 PolygonOptions 객체를 생성하고 여기에 몇 개의 점을 추가합니다. 이러한 점들은 폴리곤의 윤곽선을 구성합니다. 이어서 GoogleMap.addPolygon(PolygonOptions)을 호출하여 지도에 폴리곤을 추가하면 Polygon 객체가 반환됩니다.

다음 코드 스니펫은 지도에 사각형을 추가합니다(참고: 채우기 색상을 정의하지 않았으므로 기본 채우기 색상은 투명입니다. 이전 섹션의 스니펫에서 그린 폴리라인과 똑같이 나타납니다.)

// Instantiates a new Polygon object and adds points to define a rectangle
PolygonOptions rectOptions = new PolygonOptions()
              .add(new LatLng(37.35, -122.0),
                   new LatLng(37.45, -122.0),
                   new LatLng(37.45, -122.2),
                   new LatLng(37.35, -122.2),
                   new LatLng(37.35, -122.0));

// Get back the mutable Polygon
Polygon polygon = myMap.addPolygon(rectOptions);

폴리곤이 추가된 후에 형태를 변경하려면, Polygon.setPoints()를 호출하고 폴리곤의 윤곽선에 새로운 점 목록을 제공합니다.

지도에 폴리곤을 추가하기 전과 추가한 후에 모습을 사용자 지정할 수 있습니다. 자세한 내용은 아래 모양 사용자 지정 섹션을 참조하세요.

폴리곤 자동 완성

위 예시의 폴리곤은 5개 좌표로 구성되지만, 첫 번째와 마지막 좌표는 같은 위치로, 루프를 정의합니다. 그러나 실제로 폴리곤은 폐쇄된 영역으로 정의되므로 이 마지막 좌표를 정의할 필요가 없습니다. 마지막 좌표가 첫 번째 좌표와 다르면 API가 좌표 시퀀스 끝에 첫 번째 좌표를 첨부하여 폴리곤을 자동으로 "닫습니다."

다음 두 폴리곤은 동일합니다. 각각에 대해 polygon.getPoints()를 호출하면 모든 4개 점을 반환합니다.

Polygon polygon = map.addPolygon(new PolygonOptions()
        .add(new LatLng(0, 0), new LatLng(0, 5), new LatLng(3, 5), new LatLng(0, 0))
        .strokeColor(Color.RED)
        .fillColor(Color.BLUE));

Polygon polygon = map.addPolygon(new PolygonOptions()
         .add(new LatLng(0, 0), new LatLng(0, 5), new LatLng(3, 5))
         .strokeColor(Color.RED)
         .fillColor(Color.BLUE));

빈 폴리곤 생성

여러 경로를 단일. Polygon 객체에 결합하여 채워진 고리나 "도넛"과 같은 복잡한 셰이프를 생성할 수 있습니다. (도넛 모양은 폴리곤 영역이 폴리곤 내부에 "섬"처럼 나타납니다.) 복잡한 셰이프는 언제나 여러 개의 더욱 간단한 경로로 구성됩니다.

두 경로는 동일한 영역에 정의되어야 합니다. 두 영역 중 더 큰 영역은 채우기 영역을 정의하고 추가 옵션이 없는 단순한 폴리곤입니다. 이어서 두 번째 경로를 addHole() 메서드로 전달합니다. 두 번째의 더 작은 경로는 더 큰 경로로 완전히 감싸여서 폴리곤의 조각이 제거된 것처럼 나타납니다. 구멍이 폴리곤의 윤곽선과 겹치는 경우, 폴리곤이 채우기 없이 렌더링됩니다.

아래 스니펫은 작은 사각형 구멍이 있는 하나의 사각형을 생성합니다.

mMap.addPolygon(new PolygonOptions()
        .add(new LatLng(0, 0), new LatLng(0, 5), new LatLng(3, 5), new LatLng(3, 0), new LatLng(0, 0))
        .addHole(new LatLng(1, 1), new LatLng(1, 2), new LatLng(2, 2), new LatLng(2, 1), new LatLng(1, 1))
        .fillColor(Color.BLUE));

폴리곤 이벤트

기본적으로 폴리곤은 클릭할 수 없습니다. Polygon.setClickable(boolean)을 호출하여 클릭을 활성화/비활성화할 수 있습니다.

OnPolygonClickListener를 사용하여 클릭 가능한 폴리곤에서 클릭 이벤트를 수신합니다. 지도에서 이 리스너를 설정하려면, GoogleMap.setOnPolygonClickListener(OnPolygonClickListener)를 호출합니다. 사용자가 폴리곤을 클릭하면 onPolygonClick(Polygon) 콜백을 수신합니다.

일반 Polygon 클래스와 더불어 Maps API는 Circle 객체의 특정 클래스도 포함하여 구조를 단순화합니다.

원을 구성하려면 다음 두 가지 속성을 지정해야 합니다.

  • LatLng으로 center 지정.
  • 미터 단위 radius.

그러면 원이 주어진 center에서 radiusm 떨어진 지표면의 모든 점 집합으로 정의됩니다. Maps API가 사용하는 메르카토르 도법이 평평한 표면에 구체를 렌더링하는 방식 때문에 원이 적도 근처에 위치할 때는 거의 완벽한 원형을 나타나고 원이 적도에서 멀어질수록 (화면 상에) 점점 더 비원형으로 나타납니다.

다음 코드 스니펫은 CircleOptions 객체를 생성하고 GoogleMap.addCircle(CircleOptions)을 호출하여 지도에 원을 추가합니다.

// Instantiates a new CircleOptions object and defines the center and radius
CircleOptions circleOptions = new CircleOptions()
    .center(new LatLng(37.4, -122.1))
    .radius(1000)); // In meters

// Get back the mutable Circle
Circle circle = myMap.addCircle(circleOptions);

원이 추가된 후에 형태를 변경하려면, Circle.setRadius() 또는 Circle.setCenter()를 호출하고 새 값을 제공합니다.

지도에 원을 추가하기 전과 추가한 후에 모습을 사용자 지정할 수 있습니다. 자세한 내용은 아래 모양 사용자 지정 섹션을 참조하세요.

원 이벤트

기본적으로 원은 클릭할 수 없습니다. CircleOptions.clickable(boolean)이 포함된 GoogleMap.addCircle()을 호출하거나 Circle.setClickable(boolean)을 호출하면 클릭을 활성화/비활성화할 수 있습니다.

OnCircleClickListener를 사용하여 클릭 가능한 원에서 클릭 이벤트를 수신합니다. 지도에서 이 리스너를 설정하려면, GoogleMap.setOnCircleClickListener(OnCircleClickListener)를 호출합니다.

사용자가 원을 클릭하면 다음 코드 샘플과 같이 onCircleClick(Circle) 콜백을 수신합니다.

public class MyActivity extends FragmentActivity
        implements OnMapReadyCallback {

        private GoogleMap mMap;
        private Circle circle;

        @Override
        public void onMapReady(GoogleMap map) {
            mMap = map;

            circle = mMap.addCircle(new CircleOptions()
                .center(new LatLng(37.4, -122.1))
                .radius(1000)
                .strokeWidth(10)
                .strokeColor(Color.GREEN)
                .fillColor(Color.argb(128, 255, 0, 0))
                .clickable(true);

            map.setOnCircleClickListener(new OnCircleClickListener() {

                @Override
                public void onCircleClick(Circle circle) {
                    // Flip the r, g and b components of the circle's
                    // stroke color.
                    int strokeColor = circle.getStrokeColor() ^ 0x00ffffff;
                    circle.setStrokeColor(strokeColor);
                }
            });
        }
}

모양 사용자 지정

지도에 셰이프를 추가하기 전에 (옵션 객체에서 원하는 속성을 지정하거나) 지도에 추가한 후에 셰이프의 모양을 변경할 수 있습니다. 게터도 모든 속성에 존재하므로 셰이프의 현재 상태에 쉽게 액세스할 수 있습니다.

다음 스니펫은 멜버른에서 퍼스까지 측지 세그먼트로 굵은 파란색 폴리라인을 추가합니다. 아래 섹션에서는 이러한 속성을 더욱 자세히 설명합니다.

Polyline line = map.addPolyline(new PolylineOptions()
    .add(new LatLng(-37.81319, 144.96298), new LatLng(-31.95285, 115.85734))
    .width(25)
    .color(Color.BLUE)
    .geodesic(true));

참고: 이 속성은 위에서 설명한 모든 셰이프에 적용할 수 있지만, 일부 속성은 특정 셰이프에서만 사용할 수 있습니다(예: 폴리라인은 내부가 없으므로 채우기 색상을 가질 수 없습니다).

스트로크 색상

스트로크 색상은 32비트 ARGB(alpha-red-green-blue) 정수로, 셰이프의 스트로크의 불투명도와 색상을 지정합니다. *Options.strokeColor()(또는 폴리라인의 경우 PolylineOptions.color())를 호출하여 셰이프의 옵션 객체에서 이 속성을 설정합니다. 속성이 지정되지 않은 경우, 기본 스트로크 색상은 검은색(Color.BLACK)입니다.

셰이프를 지도에 추가한 후에 getStrokeColor()(폴리라인의 경우, getColor())를 호출하여 스트로크 색상에 액세스하고 setStrokeColor()(setColor() for a polyline)를 호출하여 변경할 수 있습니다.

채우기 색상

채우기 색상은 폴리곤과 원에만 적용됩니다. 폴리라인에는 정의된 내부가 없으므로 채우기 색상이 적용되지 않습니다. 폴리곤의 경우, 구멍 안에 있는 내부 영역은 폴리곤의 내부가 아니므로, 채우기 색상이 설정된 경우 그 부분은 색이 채워지지 않습니다.

채우기 색상은 32비트 ARGB(alpha-red-green-blue) 정수로, 셰이프 내부의 불투명도와 색상을 지정합니다. *Options.fillColor()를 호출하여 셰이프의 옵션 객체에서 이 속성을 설정합니다. 속성이 지정되지 않은 경우, 기본 스트로크 색상은 투명(Color.TRANSPARENT)입니다.

셰이프를 지도에 추가한 후에 getFillColor()를 호출하여 채우기 색상에 액세스하고 setFillColor()를 호출하여 변경할 수 있습니다.

스트로크 너비

라인 스트로크의 너비는 pixels (px) 단위의 부동 소수점입니다. 지도가 확대/축소될 때 너비는 배율이 조정되지 않습니다. (즉, 셰이프는 모든 확대/축소 수준에서 동일한 스트로크 너비를 갖게 됩니다.) *Options.strokeWidth()(또는 폴리라인의 경우 PolylineOptions.width())를 호출하여 셰이프의 옵션 객체에서 이 속성을 설정합니다. 속성이 지정되지 않은 경우, 기본 스트로크는 10픽셀입니다.

셰이프를 지도에 추가한 후에 getStrokeWidth()(폴리라인의 경우, getWidth())를 호출하여 스트로크 너비에 액세스하고 setStrokeWidth()(setWidth() for a polyline)를 호출하여 변경할 수 있습니다.

측지 세그먼트

측지 설정은 폴리라인과 폴리곤에만 적용됩니다. 원은 세그먼트 집합으로 정의되지 않으므로 측지 설정이 적용되지 않습니다.

측지 설정은 폴리라인/폴리곤의 연속적 교점 사이에 있는 선이 그려지는 방법을 결정합니다. 측지 세그먼트는 지표면(구체)의 최단 거리를 따라가고 메르카토르 도법을 사용하는 지도에서 곡선으로 나타날 수 있습니다. 비측지 세그먼트는 지도에 직선으로 그려집니다.

*Options.geodesic()를 호출하여 셰이프의 옵션 객체에서 이 속성을 설정합니다. 여기서 true는 세그먼트를 측지로 그려야 한다는 것을 나타내고, false는 세그먼트를 직선으로 그려야 한다는 것을 나타냅니다. 속성이 지정되지 않은 경우, 기본값은 비측지 세그먼트(false)입니다.

셰이프를 지도에 추가한 후에isGeodesic()를 호출하여 측지 설정에 액세스하고 setGeodesic()를 호출하여 변경할 수 있습니다.

Z-인덱스

Z-인덱스는 지도에서 다른 오버레이(다른 셰이프, 그라운드 오버레이, 타일 오버레이)에 대해 상대적으로 이 셰이프의 스택 순서를 지정합니다. Z-인덱스가 높은 오버레이는 Z-인덱스가 낮은 오버레이 위에 그려집니다. 동일한 Z-인덱스를 가진 2개의 오버레이는 임의의 순서로 그려집니다.

마커는 다른 오버레이의 z-인덱스와 관계없이 언제나 다른 오버레이 위에 그립니다.

*Options.zIndex()를 호출하여 셰이프의 옵션 객체에서 이 속성을 설정합니다. 속성이 지정되지 않은 경우, 기본 Z-인덱스는 0입니다. 셰이프를 지도에 추가한 후에 getZIndex()를 호출하여 Z-인덱스에 액세스하고 setZIndex()를 호출하여 변경할 수 있습니다.

가시성

가시성은 셰이프를 지도에 그려야 할지 여부를 지정합니다. 여기서 true는 셰이프를 그려야 함을 나타내고 false는 셰이프를 그리지 말아야 함을 나타냅니다. 이를 통해 지도에서 일시적으로 셰이프를 감출 수 있습니다. 지도에서 셰이프를 영구적으로 제거하려면 해당 셰이프에서 remove()를 호출합니다.

*Options.visible()을 호출하여 셰이프의 옵션 객체에서 이 속성을 설정합니다. 속성이 지정되지 않은 경우, 기본 가시성은 true입니다. 셰이프를 지도에 추가한 후에 isVisible()를 호출하여 가시성에 액세스하고 setVisible()를 호출하여 변경할 수 있습니다.

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

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