# Tilemap API — Vietmap API Playground

> Vietmap base maps (tilemap): pick a style, see it live, get setup code for Web, Flutter, Android and iOS.

The Tilemap API serves Vietmap's vector base map to web and mobile apps: a style.json that describes the sources, layers and fonts, so a map library (Vietmap GL JS, the Flutter, Android, iOS or React Native SDK) draws the map itself. Four styles are ready to use — Street, Light, Dark and Hybrid satellite — plus a real-time traffic layer on top. Styles designed in Map Editor work through the same mechanism.

What it is for:
- Base map for order and fleet tracking screens.
- Maps in ride-hailing, food delivery and real-estate apps.
- Dark dashboards for control and monitoring rooms.
- Branded maps with a custom style.

- Interactive page: https://tools.vietmap.vn/playground/en/tilemap
- Endpoint: `GET /maps/styles/{tm|lm|dm|hm}/style.json` on `https://maps.vietmap.vn` (lớp giao thông phủ thêm từ /maps/styles/tf/style.json)
- Official documentation: https://maps.vietmap.vn/docs/map-api/tilemap/
- API key: every request needs the `apikey` parameter. Samples use `YOUR_API_KEY` as the placeholder — when integrating, read the key from an environment variable (e.g. `VIETMAP_API_KEY`). Get a key at https://maps.vietmap.vn/console-v2/consumers
- Error codes: `401` wrong API key · `403` key restricted to another domain/IP · `423` API not enabled for the key's consumer, or out of credit (body contains "exceeded credit") · `429` rate limit exceeded.

## Code samples

### Web (CDN)

```html
<!DOCTYPE html>
<html lang="en">
<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>
    // Client-side key: restrict it by domain / bundle id in the 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] — longitude first
      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";

// Client-side key: restrict it by domain / bundle id in the 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] — longitude first
  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] — longitude first */}
      <Camera zoomLevel={13} centerCoordinate={[106.695921, 10.796668]} />
    </MapView>
  );
}
```

### Style URL

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

## AI prompt

A ready-made prompt for a coding assistant (ChatGPT, Claude, Copilot…) to write the integration:

````text
I need to display a Vietmap map in my application.
Official documentation: https://maps.vietmap.vn/docs/map-api/tilemap/?referer=https%3A%2F%2Ftools.vietmap.vn%2Fplayground%2F
Requirements:
1. Map style: Street (tm) — https://maps.vietmap.vn/maps/styles/tm/style.json?apikey=YOUR_API_KEY
2. Initial view: latitude 10.796668, longitude 106.695921, zoom 13. Note the web and React Native SDKs take [lng, lat]; Flutter/Android/iOS take (lat, lng).
3. No traffic overlay.
4. Read the API key from configuration, never hard-code it. It is a client-side key, so restrict it by domain / bundle id in the Vietmap Console.
5. Keep the map attribution control visible.

Write the code for [my platform / framework], using the official Vietmap SDK for it. If unsure about a class or package name, check the documentation above instead of guessing.
````

## Reopen this exact request in the Playground

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