Skip to content

Quickstart

This guide takes you from sign-up to your first API call and an address on a map.

1. Get your API keys

Register an account and confirm your email. A second email, Account Registration Information, brings two keys that work right away:

Key Use it for Where it lives
Services key Map APIs: address search, geocoding, routing, matrix, route optimization Your backend only
Tilemap key Rendering the base map in the SDKs Client code, restricted by domain in the Console

New accounts start with 60,000 free transactions, worth about 3,000,000 VND. Step-by-step registration with screenshots: Register an API key.

The examples below read the services key from an environment variable:

export VIETMAP_API_KEY="your services key"

2. Search an address

Call Autocomplete v4 with the services key. focus is a lat,lng coordinate (latitude first) that ranks results near it first.

curl -G 'https://maps.vietmap.vn/api/autocomplete/v4' \
  --data-urlencode "apikey=$VIETMAP_API_KEY" \
  --data-urlencode 'text=197 tran phu' \
  --data-urlencode 'focus=10.7588,106.6753'

Response (trimmed):

[
  {
    "ref_id": "auto:RAkPcicmZ3d-NQ...",
    "address": "Phường 4,Quận 5,Thành Phố Hồ Chí Minh",
    "name": "197 Trần Phú",
    "display": "197 Trần Phú Phường 4,Quận 5,Thành Phố Hồ Chí Minh"
  }
]

Each result has a ref_id that returns its coordinates in the next step.

3. Get the coordinates

Pass the ref_id the user picked, unchanged and with its prefix, to Place v4:

curl -G 'https://maps.vietmap.vn/api/place/v4' \
  --data-urlencode "apikey=$VIETMAP_API_KEY" \
  --data-urlencode 'refid=<ref_id from step 2>'

Response (trimmed):

{
  "display": "197 Đường Trần Phú,Phường Chợ Quán,Thành Phố Hồ Chí Minh",
  "ward": "Phường Chợ Quán",
  "city": "Thành Phố Hồ Chí Minh",
  "lat": 10.759222947000069,
  "lng": 106.67590269100003
}

Each Autocomplete or Place request costs 1 transaction (How pricing works). Steps 2 and 3 as one function:

// Node.js 18+. Call from your server so the API key stays private.
const KEY = process.env.VIETMAP_API_KEY;
const API = "https://maps.vietmap.vn/api";

async function getJson(url) {
  const res = await fetch(url);
  if (!res.ok) throw new Error(`HTTP ${res.status}: ${await res.text()}`);
  return res.json();
}

// Address text -> best match, with coordinates
async function locate(text, focus) {
  const q = new URLSearchParams({ apikey: KEY, text });
  if (focus) q.set("focus", focus);
  const results = await getJson(`${API}/autocomplete/v4?${q}`);
  if (results.length === 0) return null;
  const p = new URLSearchParams({ apikey: KEY, refid: results[0].ref_id });
  return getJson(`${API}/place/v4?${p}`); // { display, lat, lng, ... }
}

console.log(await locate("197 tran phu", "10.7588,106.6753"));

import os

import requests

KEY = os.environ["VIETMAP_API_KEY"]
API = "https://maps.vietmap.vn/api"


def get_json(url, params):
    resp = requests.get(url, params=params, timeout=10)
    resp.raise_for_status()
    return resp.json()


def locate(text, focus):
    """Address text -> best match, with coordinates."""
    results = get_json(f"{API}/autocomplete/v4", {"apikey": KEY, "text": text, "focus": focus})
    if not results:
        return None
    return get_json(f"{API}/place/v4", {"apikey": KEY, "refid": results[0]["ref_id"]})


print(locate("197 tran phu", "10.7588,106.6753"))

Integrate VIETMAP address search into my project.

1. GET https://maps.vietmap.vn/api/autocomplete/v4
     text=<what the user typed>
     focus=<user's latitude,longitude, if known>
   Returns an array of suggestions, each with ref_id and display.
2. GET https://maps.vietmap.vn/api/place/v4
     refid=<the ref_id the user picked, prefix included>
   Returns display, lat, lng and the address parts.

Requirements:
- Call the APIs from the server. Read the API key from the VIETMAP_API_KEY environment variable and send it as `apikey`; never hard-code it.
- Write locate(text, focus) that returns the best match with lat and lng, and checks the HTTP status (401: wrong key, 423: quota used up or API not enabled).
- Read the docs below first. Use only parameters and response fields documented there.

Docs:
- https://maps.vietmap.vn/docs/map-api/quickstart/index.txt
- https://maps.vietmap.vn/docs/map-api/autocomplete-version/autocomplete-v4/index.txt
- https://maps.vietmap.vn/docs/map-api/place-v4/index.txt
- https://maps.vietmap.vn/docs/assets/agents/search-geocoding.txt

4. Show it on a map

The map uses the tilemap key. Save this code as map.html and open it in a browser:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1" />
  <link rel="stylesheet" href="https://unpkg.com/@vietmap/vietmap-gl-js@6.0.1/dist/vietmap-gl.css" />
  <script src="https://unpkg.com/@vietmap/vietmap-gl-js@6.0.1/dist/vietmap-gl.js"></script>
  <style>html, body, #map { height: 100%; margin: 0; }</style>
</head>
<body>
  <div id="map"></div>
  <script>
    // Coordinates from step 3. The order here is [longitude, latitude].
    const lngLat = [106.67590269100003, 10.759222947000069];
    const map = new vietmapgl.Map({
      container: "map",
      style: "https://maps.vietmap.vn/maps/styles/tm/style.json?apikey=YOUR_TILEMAP_KEY",
      center: lngLat,
      zoom: 16,
    });
    map.addControl(new vietmapgl.NavigationControl());
    new vietmapgl.Marker().setLngLat(lngLat).addTo(map);
  </script>
</body>
</html>

tm in the URL is the street style; the other styles (light, dark, satellite) and how to switch them are on Tile Map. For mobile apps, see the Mobile SDKs.

5. Before going live

  • The services key lives only on your server, read from an environment variable, never in browser or app code.
  • The tilemap key is restricted to your domains (and IPs) in Manage API key.
  • Your code handles 401, 423 and 429 and checks code on routing responses. See Error codes.
  • You checked your account limits in Usage limits.
  • You estimated monthly usage with How pricing works and the converter.
  • You watch usage in Monitor API key usage. VIETMAP emails you at 80% and 100% of the total quota.

Next steps

Hotline
Tổng đài hỗ trợ
089.616.4567 Messenger Chat Facebook zalo Chat Zalo