tmap_flutter_sdk
π English Docs
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
- π μλμ°¨ κ²½λ‘ νμ (
π μμνκΈ°
1. TMAP AppKey λ°κΈ
- SK OpenAPI ν¬νΈ(openapi.sk.com)μ κ°μ /λ‘κ·ΈμΈν©λλ€.
- μ μ ν리μΌμ΄μ μ μμ±νκ³ TMAP Vector Map μνμ μ΄μ© μ μ²ν©λλ€.
- λ°κΈλ°μ AppKeyλ₯Ό 볡μ¬ν©λλ€.
2. νλ«νΌ κΆν μ€μ
Android (android/app/src/main/AndroidManifest.xml)
μΈν°λ· μ κ·Ό κΆνμ μΆκ°ν©λλ€:
<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>
iOS (ios/Runner/Info.plist)
λ€νΈμν¬ ν΅μ μ€μ μ μΆκ°ν©λλ€:
<key>NSAppTransportSecurity</key>
<dict>
<key>NSAllowsArbitraryLoads</key>
<true/>
</dict>
3. AppKey μ΄κΈ°ν
μ± μμ μ 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());
}
π μ¬μ© μμ
1. κΈ°λ³Έ μ§λ νλ©΄ λ λλ§
μ½λ 보기
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');
},
),
);
}
}
2. λ§μ»€ λ° λ§νμ μΈν¬μλμ° μΆκ°
μ½λ 보기
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');
},
)
3. μ¬λ¬ κ°μ λ§μ»€ ν΄λ¬μ€ν°λ§
μ½λ 보기
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}κ° λ¬Άμ');
},
)
4. μλμ°¨ κ²½λ‘ νμ λ° μ£Όνμ (Polyline) νμ
μ½λ 보기
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,
);
}
}
5. μ£Όλ³ POI λ§μ§/μ₯μ κ²μ
μ½λ 보기
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');
}
}
π οΈ μ£Όμ API μμ½
| ν΄λμ€ / λ©μλ | μ€λͺ |
|---|---|
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 κ°λ°μ μ΄μ μ μ± μ λ°λμ μ€μν΄μΌ ν©λλ€.
English Documentation
π νκ΅μ΄
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.
β¨ Features
- 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 (
π Getting Started
1. Issue TMAP AppKey
- 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.
2. Platform Permission Configuration
Android (android/app/src/main/AndroidManifest.xml)
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>
iOS (ios/Runner/Info.plist)
Add network communication settings:
<key>NSAppTransportSecurity</key>
<dict>
<key>NSAllowsArbitraryLoads</key>
<true/>
</dict>
3. Initialize AppKey
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());
}
π Usage Examples
1. Basic Map Screen Rendering
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');
},
),
);
}
}
2. Adding Markers and InfoWindows
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');
},
)
3. Clustering Large Numbers of Markers (Clusterer)
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');
},
)
4. Car Route Navigation and Polyline Display
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,
);
}
}
5. Search Nearby POI Places / Restaurants
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');
}
}
π οΈ API Summary
| 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 |
π License
This project is licensed under the MIT License.
β οΈ Disclaimer and Trademark Notice
- 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.