Flutter 환경에서 TMAP Vector Map v3와 TMAP OpenAPI를 손쉽게 사용할 수 있는 Flutter 지도 플러그인입니다.
webview_flutter와 JavaScript SDK를 이용하여 구현하였으며 Web 플랫폼에서의 구현은 아직 실험 단계이기 때문에 다소 불안정할 수 있습니다. Flutter SDK 3.27 이상에서 작동합니다.
-
3D 벡터 지도 & 카메라 제어
회전(
bearing, 0~360°), 기울기(pitch, 0~60°), 줌(zoom, 0~19), 중심 좌표 및 카메라 애니메이션 이동 등 -
다양한 지도 스타일
ROAD(기본 도로명),HYBRID(위성 지도),PUBLIC(대중교통 강조),NIGHT(야간 다크 테마) -
오버레이 & 그래픽:
Marker: 커스텀 아이콘, 텍스트 라벨, HTML 스타일 마커, 드래그 지원InfoWindow: 마커 핀 상단에 말풍선 꼬리 형태로 밀착되는 팝업 오버레이Clusterer: 대량의 마커를 화면 줌 레벨에 맞춰 자동으로 묶어주는 고성능 클러스터링Polyline,Polygon,Circle,Rectangle: 경로선, 구역 다각형, 반경 원형, 사각형 오버레이
-
TData & OpenAPI 연동:
- 🚘 자동차 경로 탐색 (
getRoutePlan): 경로 좌표 목록, 총 거리, 소요 시간, 통행료/택시비 계산 - 🚶 보행자 경로 탐색 (
getRoutePlanPedestrian): 도보 최적 이동 경로 탐색 - 🔍 POI 장소 검색 (
searchPoi,searchPoiAround): 키워드 검색 및 특정 좌표 반경 내 주변 장소/맛집 검색 - 📍 지오코딩 & 역지오코딩 (
getGeoFromAddress,getAddressFromGeo): 주소 ↔ 위경도 상호 변환. - 💡 키워드 자동완성 (
getAutoCompleteSearch): 검색어 실시간 추천 - 🚦 실시간 교통정보 (
toggleTrafficInfo): 지도 위 실시간 교통 흐름 레이어 On/Off
- 🚘 자동차 경로 탐색 (
- SK OpenAPI 포털(openapi.sk.com)에 가입/로그인합니다.
- 새 애플리케이션을 생성하고 TMAP Vector Map 상품을 이용 신청합니다.
- 발급받은 AppKey를 복사합니다.
인터넷 접근 권한을 추가합니다:
<manifest xmlns:android="http://schemas.android.com/apk/res/android">
<uses-permission android:name="android.permission.INTERNET"/>
<application
android:usesCleartextTraffic="true"
android:label="your_app_name"
android:icon="@mipmap/ic_launcher">
...
</application>
</manifest>네트워크 통신 설정을 추가합니다:
<key>NSAppTransportSecurity</key>
<dict>
<key>NSAllowsArbitraryLoads</key>
<true/>
</dict>앱 시작 시 main() 함수에서 발급받은 TMAP AppKey를 초기화합니다:
import 'package:flutter/material.dart';
import 'package:tmap_flutter_sdk/tmap_flutter_sdk.dart';
void main() {
WidgetsFlutterBinding.ensureInitialized();
// TMAP AppKey 등록
AuthRepository.initialize(
appKey: 'YOUR_TMAP_APP_KEY',
);
runApp(const MyApp());
}코드 보기
import 'package:flutter/material.dart';
import 'package:tmap_flutter_sdk/tmap_flutter_sdk.dart';
class MapScreen extends StatefulWidget {
const MapScreen({super.key});
@override
State<MapScreen> createState() => _MapScreenState();
}
class _MapScreenState extends State<MapScreen> {
TMapController? _controller;
@override
Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(title: const Text('TMAP 지도')),
body: TMap(
center: const LatLng(37.5665, 126.9780), // 서울시청
zoom: 16,
pitch: 30, // 3D 기울기 (0~60도)
bearing: 0, // 회전각 (0~360도)
mapType: TMapType.road,
onMapCreated: (controller) {
_controller = controller;
},
onMapTap: (latLng) {
debugPrint('지도 클릭: $latLng');
},
),
);
}
}코드 보기
final markers = <Marker>[
const Marker(
markerId: 'seoul_city_hall',
position: LatLng(37.5665, 126.9780),
label: '서울특별시청',
labelBackgroundColor: Color(0xFF0064FF),
labelTextColor: Colors.white,
),
];
final infoWindows = <InfoWindow>[
const InfoWindow(
infoWindowId: 'city_hall_popup',
position: LatLng(37.5665, 126.9780),
content: '<div style="padding: 6px 12px; font-weight: bold; font-size: 13px;">🏢 서울특별시청</div>',
type: 1, // 말풍선 꼬리 형태
offset: Point(0, -42), // 마커 핀 상단에 위치
),
];
TMap(
center: const LatLng(37.5665, 126.9780),
markers: markers,
infoWindows: infoWindows,
onMarkerTap: (markerId, position, zoom) {
debugPrint('마커 클릭: $markerId');
},
)코드 보기
final clusterer = Clusterer(
markers: [
Marker(markerId: 'm1', position: LatLng(37.5665, 126.9780)),
Marker(markerId: 'm2', position: LatLng(37.5670, 126.9790)),
Marker(markerId: 'm3', position: LatLng(37.5650, 126.9770)),
],
maxZoom: 17,
minClusterSize: 2,
);
TMap(
center: const LatLng(37.5665, 126.9780),
clusterer: clusterer,
onMarkerClustererTap: (center, zoom, markerIds) {
debugPrint('클러스터 클릭: 마커 ${markerIds.length}개 묶음');
},
)코드 보기
Future<void> findRoute(TMapController controller) async {
const start = LatLng(37.5665, 126.9780); // 서울시청
const end = LatLng(37.4979, 127.0276); // 강남역
final route = await controller.getRoutePlan(start: start, end: end);
if (route != null && route.path.isNotEmpty) {
debugPrint('총 거리: ${(route.totalDistance / 1000).toStringAsFixed(1)}km');
debugPrint('예상 시간: ${(route.totalTime / 60).round()}분');
debugPrint('예상 택시비: ${route.taxiFare}원');
// 지도 상에 경로선 그리기
await controller.drawPolyline(
points: route.path,
strokeColor: const Color(0xFF0064FF),
strokeWidth: 6,
);
}
}코드 보기
Future<void> searchNearbyPlaces(TMapController controller) async {
final results = await controller.searchPoi(
keyword: '맛집',
center: const LatLng(37.5665, 126.9780),
radius: 1, // 반경 1km
count: 10,
);
for (final poi in results) {
debugPrint('${poi.name} (${poi.roadAddress}) - 거리: ${poi.distance}km');
}
}| 클래스 / 메서드 | 설명 |
|---|---|
TMap |
TMAP 벡터 지도를 렌더링하는 핵심 위젯 |
TMapController |
카메라 회전/기울기/줌, 오버레이 제어 및 TData API 호출 컨트롤러 |
Marker |
지도 핀 마커 (커스텀 아이콘, 라벨, HTML 지원) |
InfoWindow |
마커나 특정 좌표 위에 띄우는 말풍선 팝업 |
Clusterer |
다수의 마커를 효율적으로 그룹화하는 클러스터러 엔진 |
Polyline / Polygon |
경로선 및 구역 다각형 오버레이 |
Circle / Rectangle |
반경 원형 및 사각형 오버레이 |
getRoutePlan |
자동차 최적 주행 경로 및 요금 계산 |
getRoutePlanPedestrian |
보행자 전용 도보 이동 경로 계산 |
searchPoi / searchPoiAround |
키워드 및 반경 기준 장소 검색 |
getGeoFromAddress / getAddressFromGeo |
주소 ↔ 좌표 지오코딩 및 역지오코딩 |
이 프로젝트는 MIT License에 따라 배포됩니다.
- 본 플러그인(
tmap_flutter_sdk)은 개인이 제작한 비공식 Flutter 플러그인이며, SK텔레콤(SK Telecom Co., Ltd.) 및 티맵모빌리티(TMAP Mobility Co., Ltd.)와 어떠한 공식적인 제휴, 승인, 후원 관계도 없습니다. - 'SK', 'SK텔레콤', 'TMAP' 및 관련 모든 상표, 상호, 로고의 지식재산권과 권리는 SK텔레콤과 티맵모빌리티 및 관련 권리자에게 귀속됩니다.
- 본 플러그인을 사용하여 서비스를 개발/배포할 때는 SK OpenAPI 이용약관 및 TMAP 개발자 운영 정책을 반드시 준수해야 합니다.
🌐 한국어
A Flutter map plugin that allows you to easily use TMAP Vector Map v3 and TMAP OpenAPI in Flutter applications.
Implemented using webview_flutter and the JavaScript SDK. Compatible with Flutter SDK 3.27 or above.
Note that Web platform implementation is currently experimental and may be unstable.
- 3D Vector Map & Camera Control
Rotation (
bearing, 0–360°), Pitch/Tilt (pitch, 0–60°), Zoom (zoom, 0–19), center coordinates, and animated camera movements. - Multiple Map Styles
ROAD(Standard road),HYBRID(Satellite map),PUBLIC(Public transit),NIGHT(Night dark theme) - Overlays & Graphics:
Marker: Custom icons, text labels, HTML-style markers, drag supportInfoWindow: Speech bubble popup overlay that docks on top of marker pinsClusterer: High-performance clustering that automatically groups dense markers based on zoom levelPolyline,Polygon,Circle,Rectangle: Polylines, polygon areas, circular radius, and rectangular overlays
- TData & OpenAPI Integration:
- 🚘 Driving Route Navigation (
getRoutePlan): Route coordinates, total distance, travel time, toll/taxi fare estimates - 🚶 Pedestrian Route Navigation (
getRoutePlanPedestrian): Optimal walking route calculation - 🔍 POI Place Search (
searchPoi,searchPoiAround): Keyword search and nearby places/restaurants within a given radius - 📍 Geocoding & Reverse Geocoding (
getGeoFromAddress,getAddressFromGeo): Address ↔ Latitude/Longitude conversion - 💡 Search Auto-complete (
getAutoCompleteSearch): Real-time keyword recommendations - 🚦 Real-time Traffic Info (
toggleTrafficInfo): Toggle real-time traffic flow overlay on/off
- 🚘 Driving Route Navigation (
- Sign up/Log in to the SK OpenAPI Portal (openapi.sk.com).
- Create a new application and request subscription for the TMAP Vector Map product.
- Copy the issued AppKey.
Add Internet permission:
<manifest xmlns:android="http://schemas.android.com/apk/res/android">
<uses-permission android:name="android.permission.INTERNET"/>
<application
android:usesCleartextTraffic="true"
android:label="your_app_name"
android:icon="@mipmap/ic_launcher">
...
</application>
</manifest>Add network communication settings:
<key>NSAppTransportSecurity</key>
<dict>
<key>NSAllowsArbitraryLoads</key>
<true/>
</dict>Initialize the TMAP AppKey in the main() function when the app launches:
import 'package:flutter/material.dart';
import 'package:tmap_flutter_sdk/tmap_flutter_sdk.dart';
void main() {
WidgetsFlutterBinding.ensureInitialized();
// Register TMAP AppKey
AuthRepository.initialize(
appKey: 'YOUR_TMAP_APP_KEY',
);
runApp(const MyApp());
}View Code
import 'package:flutter/material.dart';
import 'package:tmap_flutter_sdk/tmap_flutter_sdk.dart';
class MapScreen extends StatefulWidget {
const MapScreen({super.key});
@override
State<MapScreen> createState() => _MapScreenState();
}
class _MapScreenState extends State<MapScreen> {
TMapController? _controller;
@override
Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(title: const Text('TMAP Map')),
body: TMap(
center: const LatLng(37.5665, 126.9780), // Seoul City Hall
zoom: 16,
pitch: 30, // 3D tilt (0~60 deg)
bearing: 0, // rotation (0~360 deg)
mapType: TMapType.road,
onMapCreated: (controller) {
_controller = controller;
},
onMapTap: (latLng) {
debugPrint('Map tapped: $latLng');
},
),
);
}
}View Code
final markers = <Marker>[
const Marker(
markerId: 'seoul_city_hall',
position: LatLng(37.5665, 126.9780),
label: 'Seoul City Hall',
labelBackgroundColor: Color(0xFF0064FF),
labelTextColor: Colors.white,
),
];
final infoWindows = <InfoWindow>[
const InfoWindow(
infoWindowId: 'city_hall_popup',
position: LatLng(37.5665, 126.9780),
content: '<div style="padding: 6px 12px; font-weight: bold; font-size: 13px;">🏢 Seoul City Hall</div>',
type: 1, // Speech bubble style
offset: Point(0, -42), // Placed on top of the marker pin
),
];
TMap(
center: const LatLng(37.5665, 126.9780),
markers: markers,
infoWindows: infoWindows,
onMarkerTap: (markerId, position, zoom) {
debugPrint('Marker tapped: $markerId');
},
)View Code
final clusterer = Clusterer(
markers: [
Marker(markerId: 'm1', position: LatLng(37.5665, 126.9780)),
Marker(markerId: 'm2', position: LatLng(37.5670, 126.9790)),
Marker(markerId: 'm3', position: LatLng(37.5650, 126.9770)),
],
maxZoom: 17,
minClusterSize: 2,
);
TMap(
center: const LatLng(37.5665, 126.9780),
clusterer: clusterer,
onMarkerClustererTap: (center, zoom, markerIds) {
debugPrint('Cluster tapped: ${markerIds.length} markers grouped');
},
)View Code
Future<void> findRoute(TMapController controller) async {
const start = LatLng(37.5665, 126.9780); // Seoul City Hall
const end = LatLng(37.4979, 127.0276); // Gangnam Station
final route = await controller.getRoutePlan(start: start, end: end);
if (route != null && route.path.isNotEmpty) {
debugPrint('Total Distance: ${(route.totalDistance / 1000).toStringAsFixed(1)}km');
debugPrint('Estimated Time: ${(route.totalTime / 60).round()} mins');
debugPrint('Estimated Taxi Fare: ${route.taxiFare} KRW');
// Draw route line on the map
await controller.drawPolyline(
points: route.path,
strokeColor: const Color(0xFF0064FF),
strokeWidth: 6,
);
}
}View Code
Future<void> searchNearbyPlaces(TMapController controller) async {
final results = await controller.searchPoi(
keyword: 'Restaurant',
center: const LatLng(37.5665, 126.9780),
radius: 1, // radius 1km
count: 10,
);
for (final poi in results) {
debugPrint('${poi.name} (${poi.roadAddress}) - Distance: ${poi.distance}km');
}
}| Class / Method | Description |
|---|---|
TMap |
Core widget for rendering the TMAP vector map |
TMapController |
Controller for camera control (rotation/tilt/zoom), overlays, and TData API calls |
Marker |
Map pin marker (custom icons, labels, HTML support) |
InfoWindow |
Speech bubble popup displayed over markers or coordinates |
Clusterer |
Clustering engine to efficiently group large sets of markers |
Polyline / Polygon |
Polyline paths and polygon area overlays |
Circle / Rectangle |
Circular radius and rectangular area overlays |
getRoutePlan |
Driving route calculation and estimated toll/fares |
getRoutePlanPedestrian |
Pedestrian-only walking route calculation |
searchPoi / searchPoiAround |
Place search by keyword and radius |
getGeoFromAddress / getAddressFromGeo |
Address ↔ Coordinates geocoding & reverse geocoding |
This project is licensed under the MIT License.
- This plugin (
tmap_flutter_sdk) is an unofficial Flutter plugin created by an individual and is not affiliated with, endorsed by, or sponsored by SK Telecom Co., Ltd. or TMAP Mobility Co., Ltd. - 'SK', 'SK Telecom', 'TMAP' and all related trademarks, trade names, and logos are the intellectual property and rights of SK Telecom Co., Ltd., TMAP Mobility Co., Ltd., and their respective owners.
- When developing and distributing services using this plugin, you must comply with the SK OpenAPI Terms of Use and TMAP developer operating policies.