Source: https://maps.vietmap.vn/docs/map-api/quickstart/

# 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](https://maps.vietmap.vn/console-v2/register) 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](https://maps.vietmap.vn/docs/map-api/console/register-api-key/).

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

```bash
export VIETMAP_API_KEY="your services key"
```

## 2. Search an address

Call [Autocomplete v4](https://maps.vietmap.vn/docs/map-api/autocomplete-version/autocomplete-v4/) with the services key. `focus` is a `lat,lng` coordinate (latitude first) that ranks results near it first.

```bash
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):

```json
[
  {
    "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](https://maps.vietmap.vn/docs/map-api/place-v4/):

```bash
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):

```json
{
  "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](https://maps.vietmap.vn/docs/map-api/console/request-to-transaction/)). Steps 2 and 3 as one function:

=== "JavaScript"

    ```js
    // 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"));
    ```

=== "Python"

    ```python
    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"))
    ```

=== "AI agent prompt"

    ``` { .text .vm-prompt }
    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:

```html
<!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](https://maps.vietmap.vn/docs/map-api/tilemap/). For mobile apps, see the [Mobile SDKs](https://maps.vietmap.vn/docs/sdk-mobile/overview/).

## 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](https://maps.vietmap.vn/docs/map-api/console/manage-api-key/).
- Your code handles `401`, `423` and `429` and checks `code` on routing responses. See [Error codes](https://maps.vietmap.vn/docs/map-api/errors/).
- You checked your account limits in [Usage limits](https://maps.vietmap.vn/docs/map-api/console/usage-limitation/).
- You estimated monthly usage with [How pricing works](https://maps.vietmap.vn/docs/map-api/console/request-to-transaction/) and the [converter](https://maps.vietmap.vn/docs/map-api/console/pricing-converter/).
- You watch usage in [Monitor API key usage](https://maps.vietmap.vn/docs/map-api/console/monitor-api-key-usage/). VIETMAP emails you at 80% and 100% of the total quota.

## Next steps

- Solutions: [Truck and container routing](https://maps.vietmap.vn/docs/map-api/use-cases/truck-routing/), [Logistics and delivery](https://maps.vietmap.vn/docs/map-api/use-cases/delivery-routing/), [Address autocomplete for checkout](https://maps.vietmap.vn/docs/map-api/use-cases/checkout-address/).
- [Playground](https://tools.vietmap.vn/playground/): try every API on a map.
- [Docs for AI agents](https://maps.vietmap.vn/docs/llms.txt): integrate with an AI assistant.