# Tilemap API — Vietmap API Playground

> Bản đồ nền Vietmap (tilemap): chọn style, xem trực tiếp, lấy code khởi tạo cho Web, Flutter, Android, iOS.

- Trang tương tác: https://tools.vietmap.vn/playground/tilemap
- Endpoint: `GET /maps/styles/{tm|lm|dm|hm}/style.json` trên `https://maps.vietmap.vn` (lớp giao thông phủ thêm từ /maps/styles/tf/style.json)
- Tài liệu chính thức: https://maps.vietmap.vn/docs/map-api/tilemap/
- API key: mọi request cần tham số `apikey`. Code mẫu dùng `YOUR_API_KEY` làm chỗ giữ key — khi tích hợp, đọc key từ biến môi trường (ví dụ `VIETMAP_API_KEY`). Lấy key tại https://maps.vietmap.vn/console-v2/consumers
- Mã lỗi: `401` sai API key · `403` key bị giới hạn domain/IP · `423` API chưa bật cho consumer của key, hoặc hết credit (phản hồi có "exceeded credit") · `429` vượt giới hạn tần suất.

## Code mẫu

### Web (CDN)

```html
<!DOCTYPE html>
<html lang="vi">
<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1" />
  <link href="https://unpkg.com/@vietmap/vietmap-gl-js@6.0.1/dist/vietmap-gl.css" rel="stylesheet" />
  <script src="https://unpkg.com/@vietmap/vietmap-gl-js@6.0.1/dist/vietmap-gl.js"></script>
  <style>html, body, #map { margin: 0; height: 100%; }</style>
</head>
<body>
  <div id="map"></div>
  <script>
    // Key dùng phía client: giới hạn theo domain / bundle id trong Console.
    const API_KEY = "YOUR_API_KEY";

    const map = new vietmapgl.Map({
      container: "map",
      style: `https://maps.vietmap.vn/maps/styles/tm/style.json?apikey=${API_KEY}`,
      center: [106.695921, 10.796668], // [lng, lat] — kinh độ trước
      zoom: 13,
    });
    map.addControl(new vietmapgl.NavigationControl());
  </script>
</body>
</html>
```

### Web (npm)

```javascript
// npm install @vietmap/vietmap-gl-js
import vietmapgl from "@vietmap/vietmap-gl-js/dist/vietmap-gl";
import "@vietmap/vietmap-gl-js/dist/vietmap-gl.css";

// Key dùng phía client: giới hạn theo domain / bundle id trong Console.
const API_KEY = "YOUR_API_KEY";

const map = new vietmapgl.Map({
  container: "map", // id of a <div> with a height
  style: `https://maps.vietmap.vn/maps/styles/tm/style.json?apikey=${API_KEY}`,
  center: [106.695921, 10.796668], // [lng, lat] — kinh độ trước
  zoom: 13,
});
map.addControl(new vietmapgl.NavigationControl());
```

### Flutter

```dart
// pubspec.yaml → dependencies: vietmap_flutter_gl: ^4.1.1
import 'package:vietmap_flutter_gl/vietmap_flutter_gl.dart';

const apiKey = 'YOUR_API_KEY';

VietmapGL(
  styleString: 'https://maps.vietmap.vn/maps/styles/tm/style.json?apikey=$apiKey',
  // LatLng(lat, lng) — latitude first here, unlike the web SDK
  initialCameraPosition: CameraPosition(
    target: LatLng(10.796668, 106.695921),
    zoom: 13,
  ),
)
```

### Android

```kotlin
// settings.gradle → repositories { maven { url 'https://jitpack.io' } }
// build.gradle    → implementation 'com.github.vietmap-company:maps-sdk-android:2.0.4'
// layout          → <vn.vietmap.vietmapsdk.maps.MapView android:id="@+id/mapView" … />

private const val API_KEY = "YOUR_API_KEY"

class MainActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        Vietmap.getInstance(this) // before super.onCreate
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)

        val mapView = findViewById<MapView>(R.id.mapView)
        mapView.onCreate(savedInstanceState)
        mapView.getMapAsync { vietMapGL: VietMapGL ->
            vietMapGL.setStyle(
                Style.Builder().fromUri("https://maps.vietmap.vn/maps/styles/tm/style.json?apikey=$API_KEY")
            )
            vietMapGL.cameraPosition = CameraPosition.Builder()
                .target(LatLng(10.796668, 106.695921))
                .zoom(13.0)
                .build()
        }
    }
}
```

### iOS

```swift
// Podfile → pod 'VietMap', '~> 1.2.2'
import UIKit
import VietMap

class ViewController: UIViewController {
    override func viewDidLoad() {
        super.viewDidLoad()
        let apiKey = "YOUR_API_KEY"
        let styleURL = URL(string: "https://maps.vietmap.vn/maps/styles/tm/style.json?apikey=\(apiKey)")

        let mapView = MGLMapView(frame: view.bounds, styleURL: styleURL)
        mapView.autoresizingMask = [.flexibleWidth, .flexibleHeight]
        mapView.setCenter(
            CLLocationCoordinate2D(latitude: 10.796668, longitude: 106.695921),
            zoomLevel: 13,
            animated: false
        )
        view.addSubview(mapView)
    }
}
```

### React Native

```jsx
// npm install @vietmap/vietmap-gl-react-native   (Expo: development build, not Expo Go)
import { MapView, Camera } from "@vietmap/vietmap-gl-react-native";

const API_KEY = "YOUR_API_KEY";

export default function Map() {
  return (
    <MapView
      mapStyle={`https://maps.vietmap.vn/maps/styles/tm/style.json?apikey=${API_KEY}`}
      style={{ flex: 1 }}
    >
      {/* [lng, lat] — kinh độ trước */}
      <Camera zoomLevel={13} centerCoordinate={[106.695921, 10.796668]} />
    </MapView>
  );
}
```

### URL style

```text
https://maps.vietmap.vn/maps/styles/tm/style.json?apikey=YOUR_API_KEY
```

## AI prompt

Prompt soạn sẵn để giao cho trợ lý lập trình (ChatGPT, Claude, Copilot…) viết code tích hợp API này:

````text
Tôi cần hiển thị bản đồ Vietmap trong ứng dụng của mình.
Tài liệu chính thức: https://maps.vietmap.vn/docs/map-api/tilemap/?referer=https%3A%2F%2Ftools.vietmap.vn%2Fplayground%2F
Yêu cầu:
1. Style bản đồ: Street (tm) — https://maps.vietmap.vn/maps/styles/tm/style.json?apikey=YOUR_API_KEY
2. Góc nhìn ban đầu: vĩ độ 10.796668, kinh độ 106.695921, zoom 13. Lưu ý SDK web và React Native nhận [lng, lat]; Flutter/Android/iOS nhận (lat, lng).
3. Không cần lớp giao thông.
4. Đọc API key từ cấu hình, không ghi cứng. Đây là key dùng phía client nên phải giới hạn theo domain / bundle id trong Vietmap Console.
5. Giữ nguyên phần ghi công (attribution) của bản đồ.

Hãy viết code cho [nền tảng / framework của tôi], dùng SDK chính thức của Vietmap cho nền tảng đó. Nếu không chắc tên class hay package, tra tài liệu ở link trên thay vì đoán.
````

## Mở lại đúng request này trong Playground

https://tools.vietmap.vn/playground/tilemap?style=tm&center=10.796668,106.695921&zoom=13