# Address Migration API — Vietmap API Playground

> Converts addresses between the old and new formats after the province and ward merger.

The Address Migration API, an address conversion API, converts an address between the old and new formats after the administrative reorganisation (merged provinces, no district level, merged wards). Old → new needs only the address; new → old also needs an approximate coordinate (focus), because several former wards now share one name. The result lists the matching administrative units with their ids and names.

What it is for:
- Updating customer addresses in a database to the new units.
- Reconciling records and contracts still on old addresses.
- Showing old and new addresses side by side.
- Cleaning data before batch geocoding.

- Interactive page: https://tools.vietmap.vn/playground/en/migrate-address
- Endpoint: `GET /api/migrate-address/v3` on `https://maps.vietmap.vn`
- Official documentation: https://maps.vietmap.vn/docs/migrate-address/migrate-address-docs/
- 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

_This is an example request with sample parameters; open the interactive page to change them and run it for real._

### cURL

```bash
curl 'https://maps.vietmap.vn/api/migrate-address/v3?apikey=YOUR_API_KEY&text=197+tran+phu+p4+q5&focus=10.75887508%2C106.67538868&migrate_type=1'
```

### JavaScript

```javascript
// In production, read the key from an environment variable instead.
const API_KEY = "YOUR_API_KEY";

const params = new URLSearchParams([
  ["apikey", API_KEY],
  ["text", "197 tran phu p4 q5"],
  ["focus", "10.75887508,106.67538868"],
  ["migrate_type", "1"],
]);

const response = await fetch(`https://maps.vietmap.vn/api/migrate-address/v3?${params}`);
if (!response.ok) {
  throw new Error(`Vietmap ${response.status}: ${await response.text()}`);
}
const data = await response.json();
console.log(data);
```

### Python

```python
import requests

# In production, read the key from an environment variable instead.
API_KEY = "YOUR_API_KEY"

params = [
    ("apikey", API_KEY),
    ("text", "197 tran phu p4 q5"),
    ("focus", "10.75887508,106.67538868"),
    ("migrate_type", "1"),
]

response = requests.get("https://maps.vietmap.vn/api/migrate-address/v3", params=params, timeout=30)
response.raise_for_status()
print(response.json())
```

### URL

```text
https://maps.vietmap.vn/api/migrate-address/v3?apikey=YOUR_API_KEY&text=197+tran+phu+p4+q5&focus=10.75887508%2C106.67538868&migrate_type=1
```

## AI prompt

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

````text
I need to integrate Vietmap's Address Migration API v3 into my application.

Official documentation: https://maps.vietmap.vn/docs/migrate-address/migrate-address-docs/

Here is a sample request that works in the Vietmap API Playground:

GET https://maps.vietmap.vn/api/migrate-address/v3?apikey=YOUR_API_KEY&text=197+tran+phu+p4+q5&focus=10.75887508%2C106.67538868&migrate_type=1

Parameters in use:
- text = 197 tran phu p4 q5
- focus = 10.75887508,106.67538868
- migrate_type = 1

Write code in [my language / framework] that calls this API, with these requirements:
1. Read the API key from the VIETMAP_API_KEY environment variable; never hard-code it.
2. Send the parameters in the query string exactly as in the sample; repeated parameters (such as `point`) must keep their order.
3. Handle Vietmap's HTTP errors:
   - 401: the API key is wrong or revoked.
   - 403: the key is restricted to a domain / IP that does not match.
   - 423: the API is not enabled for the key's consumer, OR the account is out of credit — tell them apart by the response body ("exceeded credit" means out of credit).
   - 429: rate limit exceeded — retry with increasing backoff.
4. Set a request timeout, and define types (type / interface / dataclass) for the response.

If unsure about a field name, look it up in the documentation linked above instead of guessing.
````

## Reopen this exact request in the Playground

https://tools.vietmap.vn/playground/en/migrate-address?text=197+tran+phu+p4+q5&focus=10.75887508,106.67538868&migrate_type=1