🌏 지도 띄우기부터 마커까지, Google Maps 연동하기

Google Cloud Platform(GCP)
Google Maps Platform
Platform Pricing & API Costs
Styling Wizard: Google Maps
Google Maps Platform - Documentation

이번글에서는 Google Maps를 사용하여 Flutter에서 지도를 띄우고 활용할 수 있는 사용 방법에 대해서 알아보도록 하겠다.

Flutter에서 지도를 띄우는 방법은 여러가지 방법들이 있다.
국내 서비스만을 지원한다면 Naver, Kakao 등의 지도를 SDK로 사용할 수도 있고, 글로벌 서비스를 지원하는 경우에는 Google, OSM(Open Street Map) 지도를 사용할 수도 있다.

여러 방법 중 Google 지도를 사용하는 방법에 대해서 다뤄볼 예정이고, 다른 글에서 OSM, Naver, Kakao 지도를 사용하는 방법도 공유할 예정이다.

Google Maps는 Google이 제공하는 전세계 지도 및 네비게이션 서비스로, 일반/위성/지형/실시간 교통 등의 다양한 뷰를 제공하고 있고 길찾기, 스트리트 뷰, 위치 검색, 매장 및 업체 검색, 장소 리뷰/별점 등의 위치와 관련된 기능들을 API를 통해 무료 또는 유료로 제공해주고 있다.

위의 기능들을 모바일인지 웹인지에 따라 제공 범위가 달라지게 되고 기능별 API 비용도 일부 차이가 있을 수 있으니 반드시 서비스에 사용하고 싶은 기능의 비용을 확인하시어 개발을 진행하여야 한다.

Google Maps는 구글의 다양한 Platform을 지원하는 GCP(Google Cloud Platform)에서 제공하며, Maps Platform의 경우 모든 계정에 월 $200 무료 크레딧을 지원해주기 때문에 범위내에서는 무료 사용도 가능하다.

Flutter로 모바일 개발을 하는 경우에는 Maps SDK로 단순히 지도를 노출하고 디바이스의 GPS를 통해 실시간 위치를 가져오는 정도의 기능은 과금 없이 사용이 가능하지만, 주소를 좌표로 변환하는 Geocoding API나 좌표를 주소로 변환하는 Reverse Geocoding API, 경로를 검색하는 Directions API, 장소 및 매장 정보를 검색하는 Places API는 과금 대상이니 GCP 가격 정책에서 정확한 비용을 확인하시면 된다.

이 글에서는 Google Maps의 다양한 기능들을 최대한 다뤄볼 예정이며, 비용에 대한 부분은 고려하지 않을 것이니 참고하시길 바란다.

Google Maps Setup

Google Maps 사용을 위한 API 활성화 및 콘솔 세팅을 진행해 보자.

Google Cloud Platform(GCP)에 접속하여, 원하는 프로젝트를 선택해 주도록 하자.

GCP에 접속 후 콘솔을 클릭하여 이동해 주자.

좌측 상단에 프로젝트를 눌러서 원하는 프로젝트를 선택해 주시면 된다. 만일 프로젝트가 아직 생성하지 않았다면 "새 프로젝트"를 선택해서 프로젝트를 생성해주시면 된다.

여기서 GCP를 한 번도 사용하지 않았다면 무료로 시작하기를 통해 계정을 등록해 주고 진행해주시면 된다.

GCP의 API는 유료가 포함되어 있어 사용한 만큼 과금되는 방식이기 때문에, 계정 최초 등록시에는 카드 정보를 반드시 입력해야 한다. 테스트 용도라면 한도를 100원으로 낮게 설정해 주시면 된다.

프로젝트로 이동을 완료 하였다면, 상단의 검색바를 통해 Google Maps Platform으로 이동해 주자.

이제 Google Maps Platform으로 이동해보면, 아래와 같이 Google Maps Platform 시작하기가 노출 되면서 바로 API 키를 생성하도록 나오게 되는데, "Google Maps Platform으로 이동" 버튼을 클릭해 주고 우선 API 키 보호는 나중에를 선택해서 넘어가 주도록 하자.

위에 API 키 자동 생성 창이 노출되지 않아도 아무 문제 없다.

대시보드 좌측에 "키 및 사용자 인증 정보"로 이동해 보면, 방금 생성한 키를 확인할 수 있다.

생성된 키를 눌러서 들어가 보면 상세한 정보를 볼 수 있는데, 여기서 문제가 하나 생기게 된다.

키 제한사항 탭에서 접속 가능한 애플리케이션 제한사항이 있는데, 해당 API 키로는 애플리케이션 제한 역시 1개만 등록이 가능하다는 것을 알 수 있다.

Flutter는 Android, iOS를 모두 커버하는 크로스 플랫폼이기 때문에, 하나의 애플리케이션만 개발하지 않다보니 API 키를 안전하게 보호하지 못하게 된다.

본인의 서비스에서 별도로 API 키를 보호하지 않아도 된다고 판단하시면, 그냥 제한 없이 하나의 생성된 API로 Android, iOS를 모두 사용하여도 상관은 없다. 다만 API 키의 제한이 없기 때문에 API 키 유출로 인한 타 애플리케이션의 제한이 불가능하다.

Android, iOS 중 단일 플랫폼만 서비스를 제공할 경우라면 하나의 키만 제한사항을 설정하여 사용하시면 된다.

상단에 사용자 인증 정보 만들기를 클릭하여 API 키를 선택해 주면 즉시 생성이 완료된다.

생성된 API 키를 클릭하여 수정을 해보도록 하자.

우선 Android 전용 API를 생성하도록 하겠다. 키 구분을 위해 이름을 자유롭게 수정해 주시면 되고 애플리케이션 제한사항에 Android 앱을 선택하면 아래에 추가할 수 있는 버튼이 나온다.

현재 해당 API 키를 사용하려는 앱의 패키지 이름을 넣어주고, SHA-1 인증키를 넣어주면 된다.

우선 패키지 네임은 프로젝트의 Android > app > build.gradle 파일안에 android 태그의 namespace에서 확인하면 된다.

SHA-1 디버그 인증키 추출은 Mac 기준으로 프로젝트 수준에서 터미널을 열어 아래 명령어를 입력해주면 출력되는 인증서 지문의 SHA1을 복사해서 넣어주면 된다.

keytool -list -v -alias androiddebugkey -keystore ~/.android/debug.keystore -storepass android -keypass android

윈도우를 사용하는 경우에는 아래 글에서 추출 방법을 확인할 수 있다.

SHA 인증서 추출하기

참고로 SHA1 디버그 인증키는 각 PC마다 고유한 인증서이므로, 여러 팀원과 협업하는 경우에는 각 팀원의 PC의 인증키를 모두 추가해 주면 된다. 추가를 해주지 않으면 API 키 보호에 따라 API 요청이 거부되게 된다.

SHA-1 키와 패키지 네임을 추가하고 하단에 저장을 눌러 변경사항을 저장해주면 아래와 같이 정상적으로 추가가 된다.

추가가 더 필요하다면 Add를 눌러 여러 개의 인증서를 추가할 수 있다.

자 이제 배포를 염두한 상태이거나 이미 배포된 서비스의 경우 스토어 인증서의 SHA-1 키도 등록을 해주어야 정상적으로 사용자들이 서비스 이용이 가능하다.

Play Console로 이동하여 앱 무결성 > 앱 서명 탭으로 이동하면 배포된 서비스의 앱 서명 SHA1 키 값을 확인할 수 있다.

해당 키가 등록되지 않으면 스토어에서 다운로드 받은 앱은 API 접근이 거절되기 때문에, 배포된 서비스라면 반드시 추가해야 하고 아직 배포 전이라면 배포시 구글에서 서명하는 앱 서명 키를 놓치지 말고 해당 API키에 등록을 해주어야 한다.

이번에는 iOS API 전용 키를 발급해 보도록 하자.

위에서 수행한 절차대로 사용자 인증 정보 만들기 > API 키를 선택하여 새로운 키를 생성한 뒤에 적절한 네임을 만들어주고 애플리케이션 제한사항에 iOS 앱을 선택해 주도록 하자.

iOS는 앱의 Bundle ID를 추가만 해주면 된다. 이제 해당 서비스의 Bundle ID에 등록된 앱만 API 접근이 가능해 진다.

Bundle ID는 프로젝트의 iOS 폴더를 우클릭하여 XCode("Open In Xcode")를 열어준 뒤 Signing & Capablities 탭의 Bundle Identifier 값에서 확인할 수 있다.

이제 API 키 생성 및 보호하는 방법에 대해서 살펴봤지만, 아직 중요한 단계가 남아있다.

생성한 API 키로 어떤 GCP의 API들을 사용할지를 선택하여 활성화 해줘야 한다. 현재는 API 제한사항을 설정하지 않았기 때문에, 모든 제품의 API가 활성되어 있는 상태이다.

기본적으로 Google Maps Platform을 통해 자동으로 API가 생성되면 구글이 추천하는 Maps와 관련된 API 31개만 자동으로 활성화 되어 있는게 기본 상태인데, 사실 이 정도 API 기능도 대부분 거의 사용하지 않을거다.

필요한 API만 활성화 하면서 어떤 기능을 사용할 때에 어떤 API가 필요한지를 알아보면서 진행해 보도록 하겠다.

생성된 키를 눌러 이번에는 하단에 API 제한사항 섹션으로 내려가서 "키 제한"을 선택해 주도록 하자.

Select APIs로 메뉴를 열어준 뒤 필터창에 maps라고 치면 지도 사용을 위한 가장 기본적인 SDK가 나오게 된다.

여기서 해당하는 SDK를 선택해 주면 되는데, 각 키에 해당하는 Maps SDK를 선택해주면 된다.
하나의 키로 사용을 한다면, Android, iOS를 모두 선택해 주면 된다.

저장을 꼭 눌러주자. 이제 Flutter에서 Maps SDK를 사용할 수 있는 기본 세팅은 완료가 되었다.

참고로 API 키 관련해서 헷갈려 하시는 분들이 있는데, 해당 키의 보호조치와 Google Platform의 API 제한은 서로 다른 개념이다.
키를 보호 하는건 타 앱 또는 타 서비스에서의 접근을 제한 하고자 하는 보호 목적이고, Google Platform의 API를 제한 하는건 해당 키로 어떤 서비스가 까지 활성화 할지를 결정하는 것이다.
그렇기 때문에, Maps API만 전용으로 키를 사용 하여도 되고 다른 Google의 서비스를 하나의 키로만 프로젝트에 적용해서 사용해도 된다. 이건 관리의 영역이기 때문에 서비스, 팀 성향에 맞게 관리 기준을 적용해 효율적으로 사용하면 된다.

Flutter Map Integration

google_maps_flutter | Flutter Packages

GCP에서 Google Maps 활성화를 완료 했으니, 이제 Flutter에서 구글 지도를 띄우도록 해보자.

How to Set Up google_maps_flutter in Flutter

Google Maps SDK를 Flutter에서 쉽게 사용하도록 도와주는 패키지를 먼저 추가해주자.

dependencies

- 이 글에서는 2.10.1 버전을 기준으로 작성됨

dependencies:
	google_maps_flutter: <latest_version>

이제 Google Map을 호출하는 코드를 추가한 뒤 앱을 실행해보자.

GoogleMap(
	initialCameraPosition: CameraPosition(
		zoom: 6,
		target: LatLng(37.5642135, 127.0016985),
	),
),

Android, iOS 모두 에러가 나면서 지도가 노출되지 않았을 것이다. 이유는 GCP에서 생성한 API 키를 등록해 주지 않아서이다.

iOS

Xcode를 열고 AppDelegate.swift 파일로 이동하여 GoogleMaps를 임포트한 뒤 네이티브의 GMSService에 API 키를 제공해 주면 된다.

GMSServices.provideAPIKey("your_api_key")

AppDelegate 안에 추가해주도록 하자.

import Flutter
import UIKit
import GoogleMaps

@main
@objc class AppDelegate: FlutterAppDelegate {
  override func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
  ) -> Bool {
  
    GMSServices.provideAPIKey("AIzaSyDFYC6Nfif0GgcvPqalITn_twppssvSu3I")

    GeneratedPluginRegistrant.register(with: self)
    return super.application(application, didFinishLaunchingWithOptions: launchOptions)
  }
}

Android

Android 폴더의 app > src > main의 AndroidManifest.xml 파일을 열어준 뒤 application 태그 아래에 geo.API_KEY 관련 meta-data를 추가해 주면 된다.

<meta-data android:name="com.google.android.geo.API_KEY"
           android:value="your_api_key"/>

해당 태그들 사이에 정확히 추가해야 한다.

<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <application
        android:label="map_playground"
        android:name="${applicationName}"
        android:icon="@mipmap/ic_launcher">
      
        <activity
            android:name=".MainActivity"
            android:exported="true"
            android:launchMode="singleTop"
            android:taskAffinity=""
            android:theme="@style/LaunchTheme"
			...
        </activity>
      
        <meta-data android:name="com.google.android.geo.API_KEY"
        android:value="AIzaSyDRQ763aWsmva0QMQ-___VNeQvjwcm__b8"/>
		...
    </application>
    <queries>
        <intent>
            <action android:name="android.intent.action.PROCESS_TEXT"/>
            <data android:mimeType="text/plain"/>
        </intent>
    </queries>
</manifest>

이제 다시 실행해보면, Android, iOS 모두 정상적으로 구글 지도가 노출되는 것을 확인할 수 있다.

생성한 API 키는 API키에 접속해 보면 "키 표시" 버튼을 클릭하여 확인할 수 있다.

다시 앱을 실행해보면 정확히 서울을 기준으로 Google 지도가 정상적으로 오픈되는 것을 확인할 수 있다 !

iOS	Android

Overview of Core Features

기본적인 사용을 위한 설정은 완료 되었으니, google_maps_flutter 패키지의 여러 기능들에 대해서 본격적으로 다뤄보도록 하자.

🔥 google_maps_flutter 버전에 따라 사용 방법의 차이가 있을 수 있음 !

가장 기본인 지도를 띄어주는 것 부터 시작해보자.

GoogleMap 객체를 통해 UI에 지도를 노출하게 되며, 필수 값으로 초기 카메라 포지션을 지정해 주어야 한다.

CameraPosition 객체에 위도/경도를 생성해 target을 지정하면 된다.

GoogleMap(
	initialCameraPosition: CameraPosition(
	target: LatLng(37.5642135, 127.0016985),
	),
),

CameraPosition 객체는 target 외에도 zoom, tilt(기울기), bearing(방위각) 필드를 사용하여 원하는 카메라의 위치 및 뷰를 조정할 수 있다.

zoom: 6 tilt: 0 bearing: 0	zoom: 6 tilt: 0 bearing: 140	zoom: 6 tilt: 0 bearing: 90	zoom: 20 tilt: 0 bearing: 0	zoom: 20 tilt: 45 bearing: 0	zoom: 20 tilt: 90 bearing: 30

mapType 필드를 사용하여 지도 종류를 지정할 수 있다

GoogleMap(
	mapType: MapType.none,
    ...
),

none 타입을 제외하고는 구글에서 제공하는 지도 타입으로 맵을 사용할 수 있고, none 타입으로 지정시 지도를 노출 시키지 않으면서, tileOverlays 필드에 커스텀 또는 사용자 정의 타일을 제공하여 원하는 뷰나 UI 등을 사용하고 싶을 때 활용할 수 있다.

normal - 기본 지도 (도로, 건물, 지형 등)
satellite - 위성 이미지 지도 (건물 윤곽 없는 실사 이미지)
terrain - 지형 지도 (산, 언덕 등 고도 정보 표시)
hybrid - 위성 지도 + 도로 및 지명 정보
none - 아무것도 표시하지 않음

normal	hybrid	satellite	terrain

위에서 살펴본 tileOverlays는 공간위에 여러 레이어를 겹쳐서 UI에 적용하는 기능인데, 게임 지도나 고대 지도와 같은 나만의 지도를 보여줄 수도 있고 기본 지도위에 날씨나 행정 구역등의 정보를 표현할 때에도 레이어를 겹치게 해서 보여줄 수도 있는 기능이다. 즉 밑에서 다뤄볼 style 필드처럼 UI 적인 요소 외에도 추가적인 정보를 제공하고자 할 때에도 널리 사용되는 기능이다.

지도의 스타일을 만드는 다른 방법은 style 필드를 사용하여 원하는 UI 스타일을 JSON 타입으로 제공하는 방법이다.

아래 예시는 간단하게 POI(Point of Interest)를 제거하는 스타일이다.

GoogleMap(
	...
	style: '''
  [
    {
      "featureType": "poi",
      "elementType": "labels",
      "stylers": [
        { "visibility": "off" }
      ]
    }
  ]
  ''',
      ),

JSON에는 featureType, elementType, stylers를 사용하여 UI에 커스텀 명령을 실행하게 하는데, 구글에서 제공하는 스타일 가이드를 통해 확인할 수 있고 공식 툴을 통해 커스텀 및 코드를 확인할 수 있다.

Styling Wizard: Google Maps

간편하게 도로 색상, poi, 물 색상, 공원 숨기기, 지형 강조 등의 UI를 쉽게 구현할 수 있다.

style 관련된 부분은 다른 글에서 더 자세히 다뤄보도록 하겠다.

구글 지도에 기본적으로 제공하는 UI 요소들에 대해서도 살펴보도록 하자.

• myLocationButtonEnabled: 현재 위치로 이동하는 버튼 UI 표시 여부
• zoomControlsEnabled: +/- 줌 버튼 UI 표시
• compassEnabled: 나침반 UI 표시 여부 (지도 회전시 북쪽 정렬 아이콘)
• mapToolbarEnabled(only Android): 마커 탭 시 Google 지도 상호 작용 툴바

myLocationButton	compass	zoomControls	mapToolbar

padding 필드를 사용하면 지도의 가장자리 여백을 추가하여 기본 UI 컴포넌트들의 전체 영역 범위를 조절할 수 있어 UI 겹침을 방지하고 싶을 떄에 사용할 수 있다.

지도에서 제공되는 제스쳐 기능 역시 활성화/비활성화 여부를 지정할 수 있다.

• scrollGesturesEnabled: 지도 스크롤 가능 여부
• zoomGesturesEnabled: 핀치 줌 가능 여부
• rotateGesturesEnabled: 회전 제스쳐 허용 여부
• tiltGesturesEnabled: 기울이기(3D) 허용 여부

fortyFiveDegreeImageryEnabled 필드는 45도 항공뷰 표시 여부인데, 이건 WEB 전용이라 모바일에서는 활성화가 불가능 하다.

기본적으로 3D로 보이는 건물의 표시 여부는 buildingsEnabled 필드를 사용하면 되고, 실시간 교통 상황을 지도에 오버레이 하고 싶을 때는 trafficEnabled를 사용할 수 있다.

indoorViewEnabled라는 필드가 있는데, 이건 내부 지도 활성화 여부를 의미한다. 모든 건물에 지원되는 것이 아니고 활성화시 내부 지도를 제공할 수 있는 건물로 이동 하게되면 옆에 층 수 표시가 나오면서 내부를 지도에서 확인할 수 있다.

buildingsEnabled	indoorViewEnabled	trafficEnabled
true	false	true	false	true	false

Android 전용으로 liteModeEnabled 필드를 사용하면, Google Maps와의 상호작용을 최소화로 하면서 지도를 최대한 가볍게 사용하고 싶을 때 활용할 수 있다.

cameraTargetBounds와 minMaxZoomPreference를 활용하면 지도의 스크롤 허용 범위와 최소/최대 줌 핀치를 조절할 수 있다.

CameraTargetBounds 객체의 남서쪽(southwest), 북동쪽(northeast) 좌표를 지정하면 해당 박스 안에서만 스크롤이 가능하다.

특정 국가만을 제한하고 싶을 때 사용할 수 있다.

cameraTargetBounds: CameraTargetBounds(
	LatLngBounds(
		southwest: LatLng(33.0, 124.0),
		northeast: LatLng(39.5, 131.0),
	),
),

MinMaxZoomPreference에 최소와 최대 줌 레벨을 지정하면 사용자의 지도내 핀치 범위를 제한할 수 있다.

minMaxZoomPreference: MinMaxZoomPreference(10, 16),

GoogleMap 위젯은 다양한 사용자 상호작용에 대한 콜백 함수를 제공한다.

그중 onTap과 onLongPress는 사용자가 화면을 짧게 또는 길게 터치했을 때 호출되며, 터치된 지점의 위치를 나타내는 LatLng 객체를 반환한다.

LatLng은 지도상의 위도(latitude)와 경도(longitude)를 포함한 좌표 정보로, 이후 마커 추가, 경로 생성 등 다양한 기능에 활용될 수 있다.

GoogleMap(
	onTap: (LatLng latLng) {
		print("Tapped at: $latLng");
	},
	onLongPress: (LatLng latLng) {
		print("Long pressed at: $latLng");
    ...
},

지도 이동과 관련된 onCameraMoveStarted, onCameraMove, onCameraIdle에 대해서 알아보자.

지도 이동(스크롤)의 시작 -> 이동 중 -> 종료라는 연속적인 흐름을 호출해주는 콜백이라고 생각하면 된다.

onCameraMoveStarted, onCameraIdel은 각각 이동(스크롤)이 발생한 시작과 끝 지점에 한 번씩만 호출되는 콜백이다.
onCameraMove는 시작과 끝의 사이인 이동 중일 때에 호출되며, CameraPosition 객체를 반환한다.

참고로 CameraPosition에는 bearing, tilt, zoom, target 정보를 포함하고 있다.

 GoogleMap(
	onCameraMoveStarted: () {
		print("Camera move started");
	},
	onCameraMove: (CameraPosition position) {
		print("Camera moving to: ${position.target}");
	},
	onCameraIdle: () {
		print("Camera idle");
	},
    ...
),

gestureRecognizers를 활용하면 지도와 제스쳐(터치) 간의 상호작용을 제어할 수 있으며, 웹을 제공하는 경우에는 webGestureHandling이라는 Web 전용 핸드러를 사용할 수 있다.

Practical Map Features in Action

기본적인 사용 방법과 Google 지도 사용을 위한 필드들에 대해서 살펴 봤으니, 이제 지도를 활용하여 다양한 기능들을 만드는 방법을 알아보자.

Getting the User’s Current Location

여러 지도 앱을 사용해 보면 기본적으로 내 위치를 지도상에 표시해 주는데, 현재 우리가 띄운 구글 맵 위에는 내 위치가 표시되지 않는 것을 확인할 수 있다.

그건 바로 위치 권한을 부여 받지 못하였기 때문에 Google Map SDK가 자동으로 GPS 위치 정보를 디바이스에서 받아오지 못하고 있어서다.

위치 정보를 가져올 때는 GCP의 Geolocation API를 사용해야 하는데, 다행히 모바일에서는 내장 GPS로 위치 정보를 얻을 수 있어 비용 없이 내 위치를 가져올 수 있다.

Dependencies

권한 관련 기능을 사용하기 위해 permission_handler를 추가해 주자.

permission_handler: <latest_version>

Android

- Android > app > src > main > AndroidMenifest.xml

위치 권한을 요청하기 위해 AndroidMenifest 파일에 ACCESS_FINE_LOCATION, ACCESS_COARSE_LOCATION 퍼미션 태그를 추가하자.

<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

    <application
     ...
    />
</manifest>

iOS

- iOS > Runner > Info.plist

위치 권한 메시지에 적절한 내용을 추가해서 Info.plist 파일에 키를 등록해주자.

<key>NSLocationWhenInUseUsageDescription</key>
<string>your_request_message</string>

- iOS > Podfile

Podfile 하단에 아래와 같이 요청 권한을 사용하도록 PERMISSION_LOCATION_WHENINUSE 권한을 등록해 주자

post_install do |installer|
  installer.pods_project.targets.each do |target|
    flutter_additional_ios_build_settings(target)
        # Permission settings
    target.build_configurations.each do |config|
      config.build_settings['GCC_PREPROCESSOR_DEFINITIONS'] ||= [
        '$(inherited)',
        'PERMISSION_LOCATION_WHENINUSE=1',
      ]
    end
  end
end

해당 글은 Google 지도를 다루는 글이기 때문에, 퍼미션에 대한 설명은 진행하지 않겠다.

구글 지도를 노출하기 전에 적절한 단계에서 권한을 요청하자.

await Permission.locationWhenInUse.request();
// status.isGranted (허용)

앱을 다시 실행해 보면, 정상적으로 권한을 요청하고 구글 지도에 내 위치가 표시되는 것을 확인할 수 있다 !

구글 지도에서 제공하는 내 위치는 권한이 있으면 자동으로 Maps SDK가 위치를 지도에 표시해주는 것이기 때문에, 좌표를 확인할 수가 없다.

구글 지도를 사용하면서 내 위치 좌표 정보가 필요하거나 또는 기본으로 제공하는 내 위치 표시 UI가 마음에 들지 않는다면, 결국 내 위치를 알아야 한다.

Flutter에서 위치 정보를 다루는 location 패키지로 좌표 값을 확인해보자.

location: <latest_version>

Location의 내장 함수인 getLocation만 호출해주면 내 현재 위치 정보를 가져올 수 있다.

final Location location = Location();
await location.getLocation();

location 패키지 외에도 geolocator 패키지를 사용해서도 내 위치 정보를 가져올 수 있다.

Controlling the Map View

지도는 일반적으로 사용자의 반응에 따라 정보를 제공하거나 기능을 수행해야 한다. 이번에는 동작을 프로그래밍적으로 제어할 수 있도록, GoogleMapController를 활용해 지도를 제어하는 방법을 알아보도록 하자.

GoogleMapController를 생성해주자.

onMapCreated는 GoogleMap이 처음 렌더링되고 초기화될 때 호출되는 콜백 함수다. 이 시점에 제공되는 GoogleMapController 인스턴스를, 앞에서 선언한 컨트롤러 변수에 넘겨주면 지도를 프로그래밍적으로 제어할 수 있다.

GoogleMapController? _controller;

GoogleMap(
	onMapCreated: (GoogleMapController controller) async {
		_controller = controller;
	},
    ...
),

Flutter에 존재하는 다양한 컨트롤러들과 초기화 과정은 거의 유사하기 때문에, 사용하고 이해하는데 어려움은 없을 것이라 생각한다.

MapController를 사용하여 지도를 이동시켜 보자.

지도를 이동 시키는 방법에는 한 번에 즉시 이동하는 방식과 애니메이션 효과를 주며 부드럽게 이동하는 방식이 있다.

이는 마치 ScrollController에서 jumpTo와 animateTo를 사용하는 방식과 유사하다. 즉, 애니메이션 유무의 차이일 뿐 기능은 동일하다.

MapController에서는 moveCamera, animateCamera를 사용하면 된다.

_controller?.moveCamera(cameraUpdate);
_controller?.animateCamera(cameraUpdate);

공통적으로 CameraUpdate를 사용하여 이동할 위치, 줌 레벨 또는 보여줄 범위(LatLngBounds) 등을 지정할 수 있다.

CameraUpdate의 newLatLng 기능을 사용하면 원하는 좌표로 이동하면서 줌 레벨은 현재 수준을 유지하면서 이동시키고 싶을 떄 사용하면 된다.

CameraUpdate.newLatLng(LatLng(latitude, longitude)),

이번에는 좌표 이동은 하지 않고, 줌 레벨만 조정하고 싶다면 zoomBy, zoomTo, zoomIn, zoomOut을 활용하면 되는데, 각각의 기능에는 미묘한 차이가 있으니 적절하게 사용하셔야 한다.

기본적인 내장 함수를 사용해서 간편하게 구현하려면 zoomIn, zoomOut을 호출해서 사용할 수 있다. 이는 패키지 자체에서 편리하게 사용하라고 만들어 놓은 함수이고, 설명을 보면 zoomBy(±1)와 동일한 기능이라고 안내하고 있다.

그렇다면 zoomBy는 어떤 기능인걸까? 바로 zoom을 상대적으로 증가 또느 감소시키는 것으로 현재 줌 레벨에 비례해서 작동하게 된다.
zoomBy(3) 이라면 현재 줌 레벨에 3만큼 확대된다는 의미이다. 반대로 zoomBy(-1)을 호출하게 되면 현재 줌 레벨에서 -1만큼만 축소된다는 의미가 된다.

결국 zoomIn, zoomOut은 현재 줌에서 ±1만큼 확대/축소하는 내장 함수인 것이다.

zoomTo는 절대적 줌 레벨을 지정하는 것으로, 현재 줌 레벨과 상관없이 특정 줌 레벨로 바로 확대/축소된다.

In & Out	zoomBy(+2/-4)	zoomTo(+20/-2)
jumpTo	animateTo	jumpTo	animateTo	jumpTo	animateTo

- zoomIn & zoomOut

controller?.moveCamera(CameraUpdate.zoomIn());
controller?.animateCamera(CameraUpdate.zoomIn());
controller?.moveCamera(CameraUpdate.zoomOut());
controller?.animateCamera(CameraUpdate.zoomOut());

- zoomBy(by: number)

controller?.moveCamera(CameraUpdate.zoomBy(by));
controller?.animateCamera(CameraUpdate.zoomBy(by));

- zoomTo(to: number)

controller?.moveCamera(CameraUpdate.zoomTo(to));
controller?.animateCamera(CameraUpdate.zoomTo(to));

줌 레벨을 유지하면서 포지션을 이동시킬 때에 CameraUpdate.newLatLng(position: LatLng) 기능을 사용하면 된다고 했는데, 그렇다면 줌 레벨을 지정하면서 포지션을 이동시키고 싶다면 어떤 기능을 사용할 수 있을까 ?

CameraUpdate.newLatLngZoom 함수를 사용하면 줌 레벨과 포지션을 둘 다 지정할 수 있다. 이 경우 포지션과 줌 모두 필수적으로 지정해야 한다.

_controller?.moveCamera(CameraUpdate.newLatLngZoom(position, zoom));
_controller?.animateCamera(CameraUpdate.newLatLngZoom(position, zoom));

추가로 newCameraPosition이라는 함수가 존재하는데, 얼핏보면 newLatLngZoom과 비슷해 보이지만, 포지션의 좌표 값을 전달하는 것이 아닌 CameraPosition 자체를 새롭게 생성해서 적용할 수 있게 해준다. 즉, 초기 GoogleMap 객체에 지정한 initialCameraPosition 필드의 값을 새롭게 만들 수 있으므로 bearing, tilt, zoom, target을 모두 컨트롤이 가능하다.

CameraUpdate.newCameraPosition(CameraPosition(
   target: position,
   zoom: zoom,
   bearing: bearing,
   tilt: tilt
   ),
);

포지션과 줌 레벨을 컨트롤할 수 있지만, 지도를 사용하는 특정 앱들의 경우 단순한 포지션, 줌을 컨트롤 해주는 것이 아닌 정확한 범위 내에 뷰를 보여주는 경우가 있다. 이런 기능은 newLatLngBounds 함수를 사용해 남서쪽, 북동쪽 좌표의 범위 내에 자동으로 포지션을 이동시켜 정확한 범위를 보여줄 수 있게 된다.

final LatLngBounds bounds = LatLngBounds(
	southwest: const LatLng(34.0, 126.0),
	northeast: const LatLng(38.0, 130.0),
);

controller?.moveCamera(CameraUpdate.newLatLngBounds(bounds, zoom));
controller?.animateCamera(CameraUpdate.newLatLngBounds(bounds, zoom));

LatLng	LatLngZoom
jumpTo	animateTo	jumpTo	animateTo

---

LatLngBounds	newCameraPosition
jumpTo	animateTo	jumpTo	animateTo

지금까지는 포지션을 이동시킬 때에 지도상 좌표를 사용해 지도를 움직이는 방법에 대해서 알아봤는데, 디바이스의 물리적 위치로 지도를 이동시켜야 하는 경우도 발생한다.

다행히 CameraUpdate에 scrollBy 함수만 사용하면 손쉽게 물리적 위치로의 이동이 가능하다.

scrollBy를 사용해 x축, y축의 이동하고자 하는 범위를 지정하면 되는데, 여기서 x축과 y축은 현재 위치에서 얼만큼의 픽셀을 움직일지를 결정해주면 된다.

디바이스의 가로사이즈가 400인 경우 x에 200을 넣어주게 되면, 정확히 현재 보고 있는 물리적 뷰의 200 픽셀만큼 움직이게 된다.

controller?.moveCamera(CameraUpdate.scrollBy(x, y));
controller?.animateCamera(CameraUpdate.scrollBy(x, y));

jumpTo	animateTo

MapController의 moveCamera, animateCamera로 포지션을 이동하는 방법에 대해서 모두 알아봤다. 생각보다 쉽게 지도를 컨트롤할 수 있게 되었다 !

추가로 MapController에는 어떤 기능들이 있는지 계속해서 알아보도록 하자.

MapController는 GoogleMap에 연결된 컨트롤러기 때문에 당연히 다양한 정보들도 제공 받을 수 있다.

대표적으로 getLatLng, getScreenCoordinate, getVisibleResion에 대해서 살펴보도록 하자.
위 함수는 모두 비동기적으로 작동되며, 우리가 앞서 다뤘던 컨트롤러 메서드들과 동일한 방식으로 지도의 정보를 가져온다.

getLatLng에는 화면 좌표계(ScreenCoordinate)를 지도 좌표계(LatLng)로 변환해주는 기능으로 디바이스의 물리적 x, y위치가 지도상의 어느 위도/경도인지를 알려준다.

getScreenCoordinate는 getLatLng와는 반대로 위도/경도 좌표를 디바이스의 물리적 픽셀로 변환하여 마커나 커스텀 위젯을 정확한 화면 위치에 Overlay 하고 싶을 때 유용하게 활용할 수 있다.

getVisibleResion은 현재 디바이스 화면에서 보여지고 있는 지도의 남서/북동 좌표 정보인 LatLngBounds 형태로 실제 렌더링 되어지고 있는 지도 좌표를 알려주므로, 불필요한 렌더링이나 UI 제어 등 최적화가 필요한 시점에 활용하기에 유용한 기능이다.

await controller?.getLatLng(ScreenCoordinate(x: x, y: y))
await controller?.getScreenCoordinate(LatLng(latitude, longitude))
await controller?.getVisibleRegion();

지도의 줌 레벨을 알고 싶다면, getZoomLevel을 호출하여 확인할 수 있다.

await controller?.getZoomLevel();

커스텀 타일로 지도를 사용하는 경우 타일의 변경 사항을 적용하기 위해 캐싱을 지워주어야 변경된 타일을 적용할 수 있는데, clearTileCache(tileOverlayId)를 호출하여 이전 타일을 클리어할 수 있다.

마커를 제어할 수 있는 기능들도 제공하는데, 아직 마커에 대해서 제대로 배우지 않았으니 이 부분은 마커 사용법을 알아보면서 다뤄보도록 하자.

Placing Markers Where You Want

단순히 지도만 보여주는 서비스라면 지금까지 알아본 사용법으로도 충분히 서비스를 개발하고 운영할 수 있을 것이다.
하지만 사용자가 원하는 위치에 Marker(마커)를 배치하고 이를 기반으로 기능을 확장하고자 한다면, 마커를 동적으로 추가하고 제어하는 방법을 알아야 한다.

위의 지도에 표시된 것이 바로 Google Map에서 기본적으로 제공해주는 마커이다. 일부 UI 수정은 가능하지만 기본 UI가 마음에 들지 않는다면 당연히 커스텀도 가능하다.

본격적으로 Marker(마커)를 지도 공간위에 노출시키고 제어하는 방법을 알아보자.

GoogleMap 필드를 보면 markers가 있는데, 타입을 보면 Set로 되어 있는 것을 알 수 있다.

왜 List가 아닌 Set일까 ? 마커는 반드시 고유한 markerId를 가져야 하는데, List였다면 실수로 중복된 ID로 마커를 추가해도 막을 방법이 없고, List에 비해 Set은 contains, add, remove 등의 연산이 빠르다고 알려져 있다.

GoogleMap(
	markers: {
    	...markers
    }
)

Marker는 필수로 고유한 ID인 markerId와 지도 좌표계인 position을 전달해야 한다.

Marker(
	markerId: MarkerId(uniqueId),
    position: LatLng(latitude, longitude)
)

만일 중복된 ID로 markerId가 여러개 포함될 경우 Set 타입에 의해 늦게 들어온 id가 앞서 생성된 id를 덮어쓰기 때문에, 결국 가장 마지막으로 선언된 markerId만 남게 된다.

Marker를 추가하여 마커를 탭해보면, 자동으로 포지션이 이동하는 것을 확인할 수 있는데 이건 내장된 기능으로 옵션을 통해 제어가 가능하다.

infoWindow 필드에 InfoWindow를 사용하여 마커가 탭했을 때에, 보여주는 정보창을 노출시킬 수 있다.

title, snippet 필드에 탭의 명칭과 짧은 설명을 추가할 수 있고, anchor로 오프셋 조정이 가능하다. 또한 마커가 탭했을 때에 대한 콜백도 사용할 수 있다.

 infoWindow: InfoWindow(
	title: "NYC",
	snippet: "New York City",
	anchor: const Offset(0.5, 0),
	onTap: () {},
)

마커의 기본 아이콘은 단순한 빨간색이지만, 간단하게 색상을 변경할 수 있다.
BitmapDescriptor의 defaultMarkerWithHue(hue) 메서드에 기본으로 제공되는 색조(Hue)를 넘겨주면 된다.

여기서 Hue는 색조를 의미하며, 색상환(Color Wheel) 상에서의 각도(0°~360°)로 표현된다.

미리 지정된 hueRed(0.0), hueOrange(30.0), hueYellow(60.0), hueGreen(120.0), hueCyan(180.0), hueBlue(240.0), hueViolet(270.0), hueMagenta(300.0), hueRose(330.0)를 사용하여도 되고, 숫자를 직접 넣어주면 색상환에 맞는 색조 값으로 변하게 된다.

icon: BitmapDescriptor.defaultMarkerWithHue(
	BitmapDescriptor.hueAzure,
),
icon: BitmapDescriptor.defaultMarkerWithHue(35),

ratation은 마커를 회전시키는 각도이고, alpha는 투명도를 조정하게 된다. flat은 눕는 효과를 지정하는 것으로, 카메라 각도와 rotation을 설정하여 지도 방향에 맞게 보여줄 수 있다.

마커에서도 infoWindow와 동일하게 anchor로 오프셋 조정을 하여 세밀하게 위치를 조정 하는데 사용하면 된다.

zIndex는 double 타입으로 지도 위에 여러 마커가 오버레이 되는 경우 어떤 마커를 더 위에 보이게 할지를 결정하는 값이다. 특정 마커들을 높히고 싶거나 규칙에 의해 더 위에 보이게 할 마커를 지정하고 싶을 떄 각 마커마다 적절한 값을 세팅하여 사용하면 된다.

infoWindow	icon	alpha	rotation	flat

마커에 대한 콜백으로는 탭 했을 때의 onTap, 길게 탭하면 드래그 기능이 활성화 되면서 onDragStart가 호출되고, 드래그 중인 경우 onDrag, 탭을 놓았을 때의 onDragEnd의 콜백 함수가 작동한다. 드래그에 대한 콜백에는 지도 좌표계 정보가 제공된다.
드래그 기능을 비활성화 하고 싶다면 draggable를 false로 설정하면 마커에 대한 드래그가 작동하지 않는다.

앞서 마커의 기본 아이콘에 대한 색상 변경에 관해서 알아봤는데, 기본 아이콘이 아닌 커스텀 아이콘을 사용하는 방법에 대해서도 알아보도록 하겠다.

마커를 커스텀하게 사용하는 방법에는 디자인된 이미지를 사용할 수도 있고, Flutter에서 생성한 위젯을 사용할 수도 있다.

asset을 사용하는 경우에는 BitmapDescriptor 타입으로 프로젝트 내에 포함된 이미지를 불러와 사용하면 된다.

비동기적으로 asset을 만들어야하기 때문에, 직접 사용하시면 안되고 생성된 BitmapDescriptor를 사용하여야 한다.

BitmapDescriptor? _bikeIcon;

_bikeIcon = await BitmapDescriptor.asset(
	createLocalImageConfiguration(context),
	'assets/images/bike.png',
	width: 64,
	height: 64,
);

Marker(
	markerId: const MarkerId("1"),
	position: const LatLng(40.7128, -74.0059),
	icon: _bikeIcon ?? BitmapDescriptor.defaultMarker,
),

네트워크 이미지는 어떻게 사용해야 할까 ? 여기서부터 조금 복잡해지는데, 네트워크 이미지를 다운받아 바이트 형태(Uint8List)로 변환한 뒤 BitmapDescriptor의 asset이 아닌 bytes 내장 함수를 사용하면 된다.

네트워크 이미지를 다운받기 위해 http 패키지를 추가해 주자.

dependencies:
	http: <latest_version>

마커에 사용할 네트워크 이미지 URL을 추가하고, 다운로드 받은 뒤 Uint8List 타입을 BitmapDescriptor로 변환하는 코드이다.

Future<BitmapDescriptor> getNetworkMarkerIcon() async {
	final http.Response response = await http.get(Uri.parse(imageUrl));
    if (response.statusCode != 200) {
      throw Exception("Failed to load image.");
    }

    final Uint8List imageBytes = response.bodyBytes;

    final ui.Codec codec = await ui.instantiateImageCodec(
      imageBytes,
      targetWidth: 100,
      targetHeight: 100,
    );
    final ui.FrameInfo frameInfo = await codec.getNextFrame();
    final ByteData? byteData =
        await frameInfo.image.toByteData(format: ui.ImageByteFormat.png);
    if (byteData == null) return BitmapDescriptor.defaultMarker;

    return BitmapDescriptor.bytes(byteData.buffer.asUint8List());
  }

Flutter에서 렌더링하는 위젯(Widget)은 어떻게 커스텀 마커로 사용할까 ?

직접 만든 위젯을 Google Maps의 마커로 사용하는 방법은 생각보다 단순하지는 않다. 마커는 기본적으로 BitmapDescriptor형태의 이미지만 아이콘으로 허용하기 때문에, 위젯을 그대로 사용하기는 어렵다.

이를 해결하려면 커스텀 위젯을 이미지로 렌더링한 뒤, 바이트 형태로 변환하는 과정을 거쳐야 하는데, 화면을 캡쳐할 때에 사용되는 RepaintBoundary 위젯으로 생성하여 렌더링이 완료된 위젯을 이미지로 캡처하여 마커 아이콘으로 사용하면 말풍선 형태, 사용자 프로필, 텍스트가 포함된 다양한 디자인 마커를 만들어 사용할 수 있다.

먼저 사용하고자 하는 UI를 위젯으로 분리한 뒤, 구글 지도가 렌더링 되는 화면에 보이지 않는 영역으로 배치시켜 주자. Stack을 사용해서 구글 지도 아래에 배치시켜도 된다.

final GlobalKey _markerKey = GlobalKey();

Positioned(
	top: -9999,
	left: -9999,
	child: RepaintBoundary(
		key: _markerKey,
        child: const CustomMarkerWidget(),
        ),
	),

RepaintBoundary 위젯의 GlobalKey를 전달하여, 렌더링 후 위젯을 이미지로 생성하여 Uint8List 타입을 BitmapDescriptor로 변환해주면 된다.

사실 앞서 살펴본 네트워크 이미지를 사용하는 방식과 거의 동일하다고 보면 된다. 네트워크 이미지를 다운받아 처리하느냐, 위젯 자체를 이미지로 생성하느냐의 방식만 다를 뿐 동일하게 bytes 기능을 사용하는 것이다.

Future<BitmapDescriptor> getMarkerWidgetIcon(GlobalKey key) async {
    final RenderRepaintBoundary boundary =
        key.currentContext!.findRenderObject() as RenderRepaintBoundary;

    final ui.Image image = await boundary.toImage(pixelRatio: 3.0);
    final ByteData? byteData =
        await image.toByteData(format: ui.ImageByteFormat.png);
    if (byteData == null) return BitmapDescriptor.defaultMarker;
    final Uint8List markerIcon = byteData.buffer.asUint8List();
    return BitmapDescriptor.bytes(markerIcon);
  }

위젯의 초기 initState에서 호출시 주의할 점이 렌더링이 완료된 후 호출 되어야 한다는 점이다. 렌더링이 완료되는 시점의 프레임을 딜레이 주고 호출해주면 된다.

@override
void initState() {
	super.initState();
	_loadWidgetIcon();
}


Future<void> _loadWidgetIcon() async {
WidgetsBinding.instance.addPostFrameCallback((_) async {
	await Future.delayed(const Duration(milliseconds: 50));
	 _widgetIcon = await GoogleMapHelper.getMarkerWidgetIcon(_markerKey);
	});
}

커스텀 마커를 만들 때는 비동기 처리가 필수적이기 때문에, 렌더링 지연이나 딜레이가 발생할 가능성이 높다. 따라서 사전에 렌더링한 이미지를 캐싱하거나, 초기화 단계에서 미리 생성해두는 등의 최적화 전략이 중요하다.

이 글에서는 커스텀 마커 생성 방법의 핵심만 간단히 구현했지만, 실제 서비스 환경에서는 마커가 여러 개일 경우에는 큰 문제가 없을 수도 있어도, 지속적으로 반복 생성하는 구조는 불필요한 리소스 낭비로 이어질 수 있다. 따라서 커스텀 마커를 도입할 때에는 성능과 유연성 모두를 고려한 전략이 필요하겠다.

basic	asset	network	widget

마커를 구성할 때에 중요한 디자인 적인 요소와 사용성 개선이 바로 클러스터(Cluster)이다.
수 많은 마커가 한 화면에 동시에 표시될 경우, 지도가 복잡해지고 시인성이 떨어지며, 사용자 경험이 크게 저하되기 때문에 클러스터링을 활용하여 문제를 해결해야 한다.

클러스터는 서로 가까운 위치에 있는 마커들을 그룹으로 묶어 하나의 마커(Icon)로 표현함으로써, 지도를 깔끔하게 유지하면서도 정보를 효과적으로 전달할 수 있도록 돕는 기능이다.

클러스터(Cluster)는 여러 패키지를 활용하면 비교적 손쉽게 적용할 수 있지만, 지도상의 마커 데이터를 어떻게 그룹화할지, 줌 레벨에 따라 어떻게 표현할지, 커스텀 UI는 어떻게 적용할지 등 다뤄야 할 요소들이 많다. 따라서 클러스터에 대한 자세한 내용은 별도의 글에서 다루도록 하고, 이 글에서는 클러스터링 구현에 대한 설명은 생략하도록 하겠다.

Displaying Radius with Map Circles

지도 위에 특정 위치를 중심으로 반경(Radius)을 시각적으로 표현해야 하는 경우가 종종 있게된다. 예를 들어, 내 위치 기준 1km 이내를 표시하거나 특정 지역의 범위나 제한 구역을 시각화해야 하는 경우가 있는데 Circle 위젯을 활용하면 구글 지도 위에 손쉽게 원 형태의 오버레이를 추가할 수 있다.

circles 필드에 위에서 살펴본 마커와 동일하게 Set 타입에 Circle 객체를 사용하면 된다.

고유한 circleId를 생성하고, center 필드에 지도 좌표계를 지정해준뒤 radius에 범위를 미터(meter) 값으로 생성해주면 지도위에 원형의 범위가 지정되게 된다.

범위 안에 색상은 fillColor를 사용하면 되고, 테두리 선은 storkeColor에 원하는 색상을 지정해주면 된다. 테두리 선의 두께를 변경하고 싶다면 strokeWidth 필드에 원하는 두께를 주면된다.

마커를 다룰 때와 동일하게 zIndex, visible, onTap, consumeTapEvents 필드도 동일한 방식으로 활용이 가능하다.

circles: {
	...
	Circle(
		circleId: const CircleId(uniqueId),
		center: const LatLng(latitude, longitude),
		radius: 1000,
        ...
	),
},

Drawing Polygons on the Map

이번에는 범위가 아닌 구역을 지정하는 방법에 대해서 알아보도록 하자.

범위가 아닌 구역(면)을 지도에 오버레이하려면 Polygon을 사용하여야 한다.

예를들어 대한민국, 서울시, 뉴욕처럼 특정 도시/행정구역/단지를 반투명 오버레이로 표시하거나, 지명을 탭했을 때 해당 구획의 경계를 그려 강조하는 데 쓰인다. 다만 폴리곤을 그리려면 해당 지역의 경계 좌표(위도/경도 리스트)가 필요하므로, 행정경계/자적도 같은 경계 데이터(공공데이터, 지도 경계 API, 오픈 지오데이터)를 확보해야 자세한 구역을 보여줄 수 있다.

앞서 살펴본 마커와 써클처럼 사용 방법은 거의 동일하다고 볼 수 있다.

Set 타입의 polygons 필드에 Polygon 객체를 추가해주면 된다.

폴리곤에는 중요한 부분이 있는데, 바로 points와 holes이다.

points는 폴리곤으로 지정하고 싶은 구역의 지도 좌표계들이고, holes는 제외하고자 하는 구역의 지도 좌표계들이다. 쉽게 설명해서 서울시를 폴리곤으로 지정하고 싶은데, 구역 내에 종로구는 제외시키고 싶다면 points 필드에 서울시의 경계 좌표를 배열로 지정한 뒤, holes 필드에 종로구에 해당하는 경계 좌표들을 배열로 넣어주게 되면 서울시의 구역이 잡히면서 그 안에 있는 종로구는 제외되게 된다.

폴리곤의 옵셔널 필드로 geodesic 필드가 있는데, 이건 지구의 곡률을 반영할지 여부를 나타내는 것으로 경계 좌표를 사용하는 경우에는 차이가 없지만 다각형의 각 변을 평면 직선이 아닌 지구 곡률을 반영하고 싶을 때에 사용할 수 있다. 자세한 설명은 아래에서 설명하도록 하겠다.

마커, Circle과 동일하게 색상 컬러나 두께 등의 옵션들의 의미와 사용 방법은 동일하다.

polygons: {
	Polygon(
		polygonId: const PolygonId(uniqueId),
		points: [
			...
			LatLng(latitude, longitude),
		],
		holes: [
			...
			LatLng(latitude, longitude),
		],
	)
},

Creating Routes with Polylines

지도 위에 두 개 이상의 좌표를 연결해 경로를 시각화할 때 사용하는 Polyline에 대해서 알아보도록 하자.

맵이나 지도를 활용하는 서비스들에서 자주 경험해본 기능일 것이다. 예를 들어, 네비게이션 서비스에서 차량의 이동 경로를 표시하거나, 여행 서비스에서 비행기의 운항 루트를 보여주는 경우가 있다.

Polyline은 이러한 경로를 단순한 직선뿐만 아니라, 곡선, 색상 변경, 점선 패턴 등 다양한 스타일로 표현할 수 있기 때문에, 시각적으로 경로를 더욱 직관적이고 이해하기 쉽게 만든다.

이미 앞서 Marker, Circle, Polygon 기능을 살펴보면서, google_maps_flutter 패키지가 기능을 구현하는 전반적인 패턴을 어느 정도 익혔을 것이다. 따라서 Polyline의 사용 방법과 옵션 역시 예상과 크게 다르지 않기 때문에 쉽게 사용할 수 있을 것이다.

Polyline도 Set 타입으로 단일 경로가 아닌 여러 개의 경로를 PolylineId 라는 고유 ID로 생성하게 된다.

Polygon에서와 동일하게 points 필드를 사용하여 지도 좌표들을 순서대로 지정하면, 이를 하나의 이어진 선(Line) 형태로 지도 위에 표시하게 된다.

실제로 네비게이션 서비스에서 경로를 요청하면, 서버로부터 전달받은 경유지와 목적지 좌표들이 Polyline의 points 리스트에 매핑되어, 지도 위에 경로가 시각화 되는 구조라고 생각하면 된다.
선들을 최대한 자연스럽게 매핑하기 위해서는 때로는 경로에 따라 수십 개에서 수천 개 또는 그 이상의 지도 좌표계들을 사용하기도 한다.

라인(Line)을 표시할 때에 중요한 부분이 하나 있는데, 바로 장거리 경로를 그리는 경우이다.

단순히 좌표를 직선으로 연결하면 실제 지구 위의 최단 경로와는 다르게 표시될 수 있기 때문인데, 이러한 현상이 발생하는 이유는 Polyline이 평면 좌표계를 기준으로 선을 그리기 때문이다. 이런 경우에는 geodesic 속성을 설정 해주면 된다.

geodesic는 앞서 Polygon에서도 사용 하였던 옵션 이었는데, 좀 더 자세히 설명을 해보자면 기본적으로 지도는 평면 투영 위에 그려지기 때문에 두 지점을 선으로 이을 때 단순 직선으로 표시된다. 하지만 실제 지구는 구 형태에 가깝고, 두 지점 사이의 실제 최단 경로는 대권(Great-circle) 경로이기 때문에, 단거리나 국소 구역에서 사용할 때에는 큰 차이가 없지만 비행 경로나 국가 간 최단거리처럼 장거리 라인을 시각화가 필요한 경우에는 속성을 사용하여 보다 자연스러운 라인을 그릴 수 잇게 된다.

차이를 시각적으로 지도 상에서 확인하고 싶다면, 대한민국에서 미국의 좌표를 지정해 보면 false(default)인 경우 태평양을 가로지르는 일직선 라인으로 표시되지만, true로 변경해 보면, 실제 비행기 경로와 유사한 북극 라인을 가로지르는 곡률로 표시되는 것을 확인할 수 있다.

Polyline 디자인 요소로는 color, width로 선 색상과 두께를 지정할 수 있고, 투명도는 Color 객체의 withOpacity를 사용하면 된다.

startCap, endCap은 Cap.buttCap(평평), Cap.roundCap(둥근), Cap.squareCap(사각형)으로 시작과 끝의 선 모양을 지정할 수 있는데, iOS Google Map SDK에는 지원하지 않는 기능으로 Android와 Web에서만 적용할 수 있다.

선(Line)의 패턴은 patterns 필드에 배열로 PatternItem을 배열로 추가해주면 하나의 연결된 선이 아닌 특정 구간마다 끊긴 점선 등을 만들어 줄 수 있다. 점선을 만들고 싶다면 PatternItem.dash(double) + PatternItem.gap(double)을 조합해서 원하는 길이와 간격을 커스텀할 수 있다.

라인의 모서리 부분도 디자인 변경이 가능한데 jointType 필드에 JointType으로 .mitered(default), .bevel, .round를 사용하면 된다.

- .mitered : 날카로운 모서리
- .bevel : 모서리를 깍아서 평평하게
- .round : 모서리를 둥글게

구글 지도를 컨트롤하고, 지도 위에 정보를 시각화하기 위해 Marker, Circle, Polygon, Polyline 같은 디자인 요소들을 살펴보았다. 이번 글에서는 기본 사용법과 핵심 옵션 위주로 정리했지만, 실제 서비스에서는 지도 뷰의 줌 레벨, 기울기/회전, 제스처 제어, 동적 스타일링 등 고려해야 할 요소가 많아, 완성도 높은 지도 서비스를 구축하는 일은 결코 간단하지 않다. 앞으로 이러한 고급 기능과 최적화 방법을 실무에 적용할 수 있는 주제로 지속적으로 다뤄볼 예정이다.

Geocoding Basics

지도를 다루다 보면 단순히 마커나 원, 폴리곤 같은 요소를 Overlay(오버레이)하는 것만으로는 부족할 때가 많은데, 사용자는 보통 "이 좌표가 어떤 주소인지" 또는 "이 주소가 지도에서 어디쯤인지"를 알고 싶어한다.

이 과정을 바로 지오코딩(Geocoding), 리버스 지오코딩(Reverse Geocoding) 이라고 한다.

지도 좌표계(위도/경도)를 주소로 바꿔주는 과정을 리버스 지오코딩(Reverse Geocoding)이라고 하며, 지도 위의 특정 공간을 눌렀을 때에, 그 지도 좌표계를 어떤 행정구역이나 도로명 주소 등 사람이 이해할 수 있는 주소로 변환하는 과정이다.

그렇다면 지오코딩(Geocoding)은 주소를 지도 좌표계로 바꿔주는 과정을 말한다.
사용자가 특정 주소에 마커를 찍고 싶다면, 주소를 지오코딩하여 지도 좌표계로 변환하여 지도 공간 위에 표시해주면 되는 것이다.

지도는 본질적으로 좌표계 위에서 동작하지만, 사람은 좌표보다는 주소를 기준으로 사고하기 때문에, 지도 기반 서비스를 만들 때는 주소와 좌표를 상호 변환하는 기능이 반드시 필요하게 된다.

Google Maps에서는 어떻게 이 기능을 구현할 수 있을까 ? GCP의 Google Maps Platform의 Geocoding API를 사용하면 쉽게 구현할 수 있다.

앞서, Android와 iOS에서 지도를 사용하기 위해 API Key를 발급받아 프로젝트에 적용했었다. 그런데 여기서 Geocoding API를 사용하려고 할 떄에 문제가 생기게 된다.

GCP에서 API Key를 발급할 때 보안을 위해 흔히 키 제한사항 - 애플리케이션 제한을 걸어둔 것을 기억하고 있을 것이다.
이 방식은 지도 SDK를 앱에서 직접 호출할 때에는 문제가 없지만, Geoconding API는 보통 HTTP 요청 기반의 Web API 형태로 제공되기 떄문에, 앱 안에서 직접 호출하게 되면 키 제한이 적용된 API 키 사용으로 권한 에러가 발생하게 된다.
즉, 지도를 사용하기 위해 플랫폼 별로 발급 받은 API 키로는 Geocoding API를 사용할 수가 없다.

플랫폼별 API 키 제한을 두지 않고 모든 환경에서 공통으로 사용하도록 설정한다면, Geocoding API를 활성화 해주면 되지만, 보안 강화를 위해 플랫폼별 제한을 유지하고 싶다면, 기존 키는 SDK 전용으로 유지하고 추가로 API Key를 발급받아 사용하면 된다.

테스트 단계에서는 제한 없는 API 키 하나만으로도 충분하다. 하지만 운영 환경에서 키가 그대로 노출되면 보안상 큰 위험이 생기는데, 누구나 키를 사용해 API를 호출할 수 있어 과금이나 쿼터 소진 문제가 발생할 수 있기 때문이다. 따라서 실제 서비스에서는 플랫폼별로 키를 나눠 제한을 두거나, 서버를 통해 Geocoding API를 호출하면서 IP 제한을 적용하는 방식이 안전하다.

새로운 API 키를 발급 받아보자.

키 발급은 앞서 해본 것과 동일한 절차로 GCP > 사용자 인증 정보 만들기 > API 키로 이동하여 애플리케이션 제한사항을 없음으로 해주도록 하자.
다만, 테스트 용도가 아니라 실제 운영 환경에서 사용될 예정이라면 IP 주소 제한과 같은 보안설정을 꼭 적용해 클라이언트에서 직접 호출하지 않고, 서버에서 Geocoding API를 프록시로 호출하는 방식을 사용하는 것이 안전하다.

SDK를 추가한 것과 같이 API 제한사항에 Geocoding API를 선택해 활성화 해주도록 하자.

자 이제 활성화된 Geocoding API 키를 사용하여 지오코딩/역지오코딩을 호출해 보도록 하자.

Geocoding API의 엔드포인트 Base URL이다. 기본은 json이지만 xml을 원할 경우 xml로 호출할 수 있다.

https://maps.googleapis.com/maps/api/geocode/json

옵셔널 파라미터로 key를 추가해야 하는데, 여기서 key가 앞서 생성한 API Key를 사용하면 된다.

언어도 지정할 수 있는데, language=ko로 파라미터에 추가해 주면 한국어로 응답 값을 반환해 준다.

가장 중요한 지오코딩/역지오코딩을 요청하는 파라미터를 알아보자.

지오코딩(Geocoding)은 주소를 지도 좌표계로 변환하는 역할이므로 옵셔널 파라미터에 address를 추가하고 변환하고자 하는 주소를 넣어주면 되고, 반대인 역지오코딩(Reverse Geocoding)을 요청하는 경우 latlng 파라미터를 사용하면 되는데 latitude(위도), longitude(경도)를 콤마로 구분해서 요청해주면 된다.
여기서 주의점은 위도/경도의 순서가 바뀌면 안된다.

?key={api_key}&language=ko&address=서울특별시 종로구 사직로 161
?key={api_key}&language=ko&latlng=37.580467, 126.976944

응답 JSON 구조를 살펴보도록 하자.

공통적으로 응답 상태인 status와 원하는 결과 값 results 필드를 내려준다.

results는 배열 구조로 여러 개의 데이터가 담겨서 내려오게 된다.
일반적으로 지오코딩을 요청하는 경우 대부분 1개의 결과 값만 나오지만, 정확한 주소가 아닌 특정 행정구역까지만 입력하면 동일한 명칭을 사용하는 법정동/행정동이 존재할 수 있어 여러 데이터가 배열에 담겨 반환될 수 있다.

예를 들어, “address=중앙로” 와 같이 요청하면 전국에 존재하는 “중앙로”라는 도로명 주소가 모두 검색되어 여러 결과가 반환된다.
반면, “서울특별시 종로구 사직로 161”처럼 정확한 주소를 입력하면 단일 결과만 반환되므로 이 경우에는 results 배열의 첫 번째 결과값을 사용하면 된다.

역지오코딩의 경우는 조금 다르다.

하나의 좌표 값을 주소로 변환하는 과정에서 그 위치가 속한 도로명 주소, 지번 주소, 행정동, 법정동, 시/군/구, 국가 단위 등 여러 주소 계층이 함께 매칭되기 때문에 여러 개의 결과가 배열로 내려오는 것이 일반적이어서, 특정 타입을 구분해 사용하거나 가장 신뢰도가 높은 첫 번째 결과 값만 사용하는 등의 적절한 방법을 만들어 사용하면 된다.

Google Maps Platform Geocoding API Overview에 접속해 보면 Geocoding API가 어떻게 작동 하는지에 대한 결과 값의 주소 계층들을 시각적으로 확인해 볼 수 있다.

results 배열에 담겨 있는 데이터들은 어떤 구조를 가지고 있는지도 살펴보도록 하자.

Google Maps Platform - Geocoding request and response
❗️Geocoding API에 대한 자세한 내용은 공식문서를 참고하시길 바람

results 배열의 데이터 구조는 지오코딩과 역지오코딩 모두 동일한 형태를 가진다.

이 중에서 가장 중요한 필드는 바로 formatted_address와 geometry이다.

formatted_address는 사람이 읽을 수 있는 최종 주소 문자열을 담고 있고, geometry는 위치 관련 세부 정보를 가지고 있다.

좌표를 주소 값으로 변환하는 역지오코딩의 경우에는 formatted_address 필드에 담긴 주소 문자열을 활용할 수 있고, 반대로 주소를 좌표로 변환하는 지오코딩의 경우에는 geometry 필드의 좌표 정보를 활용하면 된다.

formatted_address는 반환 타입이 문자열로 그대로 사용할 수 있지만 geometry 필드는 location, location_type, viewport 구조로 이루어져 있기 때문에, location의 lat, lng의 위도/경도를 사용하면 된다.

viewport는 northeast(북동쪽), southwest(남서쪽) 좌표 정보를 통해 해당 좌표가 화면에 보여줄 때의 적절한 범위를 제안하는 사각형 영역의 데이터이다. 앞서 Geocoding API 오버뷰에서 확인해 보는 사각형 박스의 영역이라고 보시면 된다.

추가로 경우에 따라서 bounds가 포함되는 경우가 있는데, 행정구역이나 우편번호, 특정 구역처럼 범위를 가지는 결과일 경우 실제 경계를 northeast, southwest 좌표로 제공해준다.
건물이나 도로명 주소처럼 특정 지점(point)을 나타내는 결과에는 포함되지 않기 때문에 옵셔널하게 사용하여야 한다.

결과에 대한 정확도 수준을 location_type으로 반환해 주는데, 해당 타입들에 대해서는 공식문서를 확인하시는 것을 추천드리며 대체적으로 많이 사용하는 타입은 아래와 같다.

• ROOFTOP: 건물 지붕 단위까지 정확(가장 신뢰도가 높음)
• RANGE_INTERPOLATED: 도로 구간 내에서 보간된 좌표
• GEOMETRIC_CENTER: 도로/장소의 중심점
• APPROXIMATE: 대략적인 위치

나머지 필드에 대해서도 간단하게만 살펴보도록 하자.

address_components는 주소를 구성하는 요소들을 배열로 제공하는 필드이다. 각 요소는 longname(전체 이름), short_name(축약/코드), types(해당 요소의 역할/단계) 구조를 가지며, 이를 통해 행정구역의 계층 정보를 확인할 수 있다.
예를 들어, "administrative_area_level_1"은 광역시·도 단위, "sublocality_level_1"은 구 단위, "premise"는 건물 번호처럼 세부적인 단위를 의미한다.
따라서 _types 정보를 활용하면 주소를 시/도/구/동 단위로 손쉽게 분리해 사용할 수 있습니다.

또한 place_id는 Google Maps에서 장소를 식별하는 고유한 ID를 담고 있어, 동일한 장소를 재조회하거나 다른 API와 연동할 때 활용할 수 있다.

최상위 types 필드는 해당 결과의 유형을 나타내며, 도로명 주소인지(street_address), 행정구역인지(administrative_area_level_1), 우편번호인지(postal_code) 등을 알려주어 결과를 필터링하거나 상황에 맞게 사용할 수 있도록 도와준다.

types에 속하는 정확한 타입들은 공식문서에서 확인할 수 있다.

마지막으로 plus_code는 Google이 제공하는 Plus Codes 정보로, 주소가 없는 곳도 좌표 기반 코드로 표현할 수 있게 해주는 기능으로 사막이나 바다 한가운데처럼 기존의 도로명 주소나 행정 구역이 존재하지 않는 곳도 위도·경도를 고유한 코드로 변환해 공유할 수 있다.

Plus Codes는 전 세계 어디서든 고유하게 사용 가능한 global_code와 특정 지역 맥락에서 짧게 쓸 수 있는 compound_code 두 가지 형태를 제공한다.
따라서 plus_code를 활용하면 주소 체계가 없는 위치도 손쉽게 공유하거나 지도에서 찾아볼 수 있다는 장점을 가지고 있다.

참고로 역지오코딩(ReverseGeocoding)에서는 results 필드내 배열 외에도 최상위 필드에서 별도로 plus_code를 포함한다.

이렇게 Google Maps에서 제공하는 Geocoding API를 사요하여 지오코딩(Geocoding)/역지오코딩(ReverseGeocoding) 기능에 대해서 알아보았다.

Geocoding API를 사용하면 손쉽게 변환 기능을 제공하는 것 외에도 디테일한 데이터들도 함께 제공받을 수 있다는 메리트가 있지만 당연히 무료는 아니며 일정량을 초과하면 과금이 발생한다(월별 무료 사용량은 제공).

이번 글에서는 Google Maps를 활용한 지도 서비스 맥락에서 Geocoding API를 소개하였지만, 구글이 아니더라도 다양한 서비스에서 Geocoding 기능을 제한적으로 무료로 제공하기도 하니 Geocoding API를 실제 서비스에 적용 하신다면 반드시 요금 정책을 확인하고 비용을 고려해야 한다.

---

Flutter로 모바일 플랫폼(iOS/Android)만 개발하는 상황에서는 일반적으로 네이티브 API로 이미 내장되어 있는 Geoding 서비스를 그대로 활용할 수 있는데, Android의 Geocoder와 iOS의 CLGeocoder를 호출하는 geocoding 패키지를 사용하시면 무료로 사용이 가능하다. 다만 웹을 지원하지 않으며, OS 네이티브 API에 의존하기 때문에 짧은 시간에 과도한 호출을 하면 요청 제한(Rate Limit)이 걸릴 수 있고 특정 국가에서는 서비스에 제한을 받을 수도 있다.

Geocode.xyz를 사용할 수 있는 geocode 패키지는 모바일뿐만 아니라 웹에서도 1초당 1건의 제한으로는 무료로 사용이 가능하며, 유료 플랜도 제공하고 있다.

소개한 Google Geocoding API와 geocoding, geocode 패키지 외에도 지오코딩/역지오코딩을 제공하는 서비스들이 많이 있으므로 본인의 서비스에 가장 최적화할 수 있는 서비스를 선택해서 사용하시면 된다.

마무리

지금까지 Google Maps Platform의 API 키를 발급받아 Flutter에서 구글 맵을 띄우고, 지도 사용을 위한 기본 옵션 정보 및 Marker/Circle/Polyline/Polygon 등의 오버레이(Overlay) 기능과 지도를 제어하기 위한 방법들에 대해서 알아보았다.

또한 지도를 다루는 데에 핵심 기능인 지오코딩(Geocoding)과 역지오코딩(Reverse Geocoding)을 Geocoding API를 통해 어떻게 구현할 수 있는지도 살펴보았다. 이를 활용하면 단순히 위도/경도 좌표만 다루는 것이 아니라, 사용자가 이해할 수 있는 주소 데이터와의 연결이 가능해져 위치 기반 서비스의 활용도가 크게 높아진다는 것을 확인할 수 있었다.

Google Maps Platform의 기능을 최대한 이번 글에서 다루려고 하였지만, 내용도 너무 길어져 원하는 위치의 장소를 검색해 주는 Places API, 두 지점의 최적 경로를 탐색해 주는 Directions API에 대해서는 별도로 다뤄볼 예정이고, 각 API들의 기능을 이번 글에서 살펴본 오버레이(Overlay) 기능들과 결합하여 좀 더 실용적인 UI를 구현하여 소개해 보도록 하겠다.

긴 글 읽어주셔서 감사합니다 ❗️