Skip to main content

tmap_flutter_sdk 0.1.0 copy "tmap_flutter_sdk: ^0.1.0" to clipboard
tmap_flutter_sdk: ^0.1.0 copied to clipboard

A Flutter plugin for TMAP (SK Open API) Vector Map v3. Supports 3D camera control, markers, clustering, geometries, route planning, and POI search.

tmap_flutter_sdk #

pub package License: MIT Flutter Platform

🌐 English Docs

Flutter ν™˜κ²½μ—μ„œ TMAP Vector Map v3와 TMAP OpenAPIλ₯Ό μ†μ‰½κ²Œ μ‚¬μš©ν•  수 μžˆλŠ” Flutter 지도 ν”ŒλŸ¬κ·ΈμΈμž…λ‹ˆλ‹€.

webview_flutter와 JavaScript SDKλ₯Ό μ΄μš©ν•˜μ—¬ κ΅¬ν˜„ν•˜μ˜€μœΌλ©° Web ν”Œλž«νΌμ—μ„œμ˜ κ΅¬ν˜„μ€ 아직 μ‹€ν—˜ 단계이기 λ•Œλ¬Έμ— λ‹€μ†Œ λΆˆμ•ˆμ •ν•  수 μžˆμŠ΅λ‹ˆλ‹€. Flutter SDK 3.27 μ΄μƒμ—μ„œ μž‘λ™ν•©λ‹ˆλ‹€.

✨ μ£Όμš” κΈ°λŠ₯ #

  • 3D 벑터 지도 & 카메라 μ œμ–΄

    νšŒμ „(bearing, 0360Β°), 기울기(pitch, 060Β°), 쀌(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 λ°œκΈ‰ #

  1. SK OpenAPI 포털(openapi.sk.com)에 κ°€μž…/λ‘œκ·ΈμΈν•©λ‹ˆλ‹€.
  2. μƒˆ μ• ν”Œλ¦¬μΌ€μ΄μ…˜μ„ μƒμ„±ν•˜κ³  TMAP Vector Map μƒν’ˆμ„ 이용 μ‹ μ²­ν•©λ‹ˆλ‹€.
  3. λ°œκΈ‰λ°›μ€ 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 support
    • InfoWindow: Speech bubble popup overlay that docks on top of marker pins
    • Clusterer: High-performance clustering that automatically groups dense markers based on zoom level
    • Polyline, 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

πŸš€ Getting Started #

1. Issue TMAP AppKey #

  1. Sign up/Log in to the SK OpenAPI Portal (openapi.sk.com).
  2. Create a new application and request subscription for the TMAP Vector Map product.
  3. 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.
0
likes
130
points
14
downloads

Documentation

API reference

Publisher

verified publisherven0m.kr

Weekly Downloads

A Flutter plugin for TMAP (SK Open API) Vector Map v3. Supports 3D camera control, markers, clustering, geometries, route planning, and POI search.

Repository (GitHub)
View/report issues

Topics

#maps #tmap #navigation #location #flutter

License

MIT (license)

Dependencies

flutter, flutter_web_plugins, http, plugin_platform_interface, web, webview_flutter, webview_flutter_android, webview_flutter_web, webview_flutter_wkwebview

More

Packages that depend on tmap_flutter_sdk