Skip to content
Since98
Documentation · REST and MCP

Vietnam address API and MCP server

The data behind our address converter, open to code and AI assistants: a REST API and a remote MCP server. No key and no sign-up. Responses are read-only and carry the data version, the source and the resolution numbers.

02 — Start

Quick start

MCP server URL. Add it as a remote (custom) MCP server in your client:

https://since98.vn/api/mcp/address

Or call the REST API directly (POST keeps the address out of server logs):

curl -X POST "https://since98.vn/api/v1/address/normalize" \
  -H "Content-Type: application/json" \
  -d '{"address":"12 Nguyễn Huệ, P. Bến Nghé, Q.1, TP.HCM"}'
OpenAPI: /api/v1/address/openapi.json
03 — Short answers

How it works

How do I connect the address data to an AI assistant?

Short answer
Add a remote MCP server with the URL https://since98.vn/api/mcp/address. It uses Streamable HTTP, needs no key and no sign-in, and exposes 7 read-only tools.
How we do it
The server is stateless: every POST is answered on its own, without sessions. Current clients and older clients that start with initialize are both supported.
Limits
60 requests per minute and 2,000 per day per IP address, shared with the REST API. Results are reference data.
04 — Clients

Connect the MCP server

  1. Claude (web and desktop app)

    1. Open Customize → Connectors, choose “+ Add” → “Add custom connector”. On Team and Enterprise plans, an owner adds it in Organization settings → Connectors.
    2. Enter a name, for example Vietnam addresses, and the URL https://since98.vn/api/mcp/address.
    3. Choose “No sign in” for authentication and click Add.
    4. In a chat, ask for example: “What is the new address for Phường 16, Quận 8, TP.HCM?”
    Client documentation
  2. Claude Code

    1. Run the command below in a terminal.
    2. Check the connection with /mcp inside a session.
    Terminal
    claude mcp add --transport http since98-address https://since98.vn/api/mcp/address
    Client documentation
  3. Cursor

    1. Add the server to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project).
    2. Reload the MCP list in Cursor settings.
    mcp.json
    {
      "mcpServers": {
        "since98-address": {
          "url": "https://since98.vn/api/mcp/address"
        }
      }
    }
    Client documentation
  4. VS Code (GitHub Copilot)

    1. Open the Command Palette and run “MCP: Add Server”.
    2. Choose HTTP, paste https://since98.vn/api/mcp/address and give the server an ID, for example since98-address.
    3. Use it in Copilot Chat in agent mode.
    Client documentation
  5. Windsurf

    1. Add the server to ~/.codeium/windsurf/mcp_config.json.
    2. Refresh the MCP servers in Cascade.
    mcp_config.json
    {
      "mcpServers": {
        "since98-address": {
          "serverUrl": "https://since98.vn/api/mcp/address"
        }
      }
    }
    Client documentation
  6. ChatGPT

    1. On chatgpt.com, open the plugins page and choose “+” → “Add custom MCP server”.
    2. Paste https://since98.vn/api/mcp/address as the server URL and choose no authentication.
    3. Availability depends on your ChatGPT plan and workspace settings.
    Client documentation
  7. Any other MCP client

    1. Add a remote (custom) MCP server by URL: https://since98.vn/api/mcp/address.
    2. Transport: Streamable HTTP. No key, no OAuth, no headers needed.
05 — Tools

MCP tools

This list is generated from the same definitions the server registers, so it matches what tools/list returns.

convert_old_to_newConvert old address to new (2025 reform)
Convert a Vietnamese administrative address from BEFORE 1 July 2025 (old province, district, commune) to the unit(s) valid AFTER the 2025 reform. Use when the user has an old address, an old ID card or registration address, or asks "what is my ward called now". Pass the parts you have; names may be written with or without diacritics, with prefixes or abbreviations, or as official codes. Returns the old unit, the new commune and province, the new address line, transition type (merge, unchanged, rename, retype, special_zone), partial=true when only part of the old commune went there, and resolution numbers. If the old commune was split between several new communes, ALL of them are returned and ambiguous=true: do not pick one, ask for the street or hamlet. Examples: {"province":"TP.HCM","district":"Quận 8","ward":"Phường 16"}; {"province":"Bình Dương","district":"Thủ Dầu Một","ward":"Phú Cường"}; {"ward":"27430"}.
find_unitsFind administrative units by name
Search Vietnamese administrative units by name or code, ignoring case and diacritics. scope "new" (default) searches the post-reform units (34 provinces, 3,321 communes); scope "old" searches units as of 30 June 2025 (63 provinces, districts, communes). Use to check spelling, get a code, or see every place with the same name before converting. Returns code, full name, level, match quality (code, exact, partial) and parent district/province. Examples: {"query":"Bến Nghé","scope":"old"}; {"query":"thu duc"}; {"query":"Tân Phú","scope":"old","level":"ward","province":"79","limit":20}.
list_provincesList provinces (34 new or 63 old)
List Vietnam's provinces and centrally-run cities. scope "new" (default): the 34 provinces in force since 1 July 2025, each with its code, number of communes and the old provinces merged into it. scope "old": the 63 provinces before the reform, each with the new province it became part of. Use for overviews or to answer "which provinces were merged into X". Example: {"scope":"old"}.
list_wardsList communes of a province
List all commune-level units (phường, xã, đặc khu) of one province. scope "new" (default): communes after the reform with codes and any 2026 changes; scope "old": communes as of 30 June 2025 with their district. The province may be a 2-digit code or a name. Example: {"province":"79"}; {"province":"Đà Nẵng","scope":"old"}. Output can be long (up to a few hundred entries); prefer find_units for a single name.
explain_mergeExplain how a new unit was formed
Explain what a NEW (post-1 July 2025) commune or province was formed from: the old communes or provinces merged into it, whether each came whole or partially (split communes list the other new units their parts went to), the transition type and the resolution numbers. Use when the user asks "which wards were merged into X" or needs the legal basis. Takes the new unit code (5 digits for a commune, 2 for a province); get it from find_units or convert_old_to_new. Examples: {"code":"26734"}; {"code":"79"}.
normalize_addressRewrite a free-form address to the new units
Parse a free-form Vietnamese address line (street, commune, district, province; with or without diacritics, commas or abbreviations) and rewrite it with the post-reform units: drops the district and replaces the old commune and province. Returns status (converted, already_new, province_level when only a province was given, ambiguous, partial when the commune is missing, e.g. a district alone, not_found), confidence, the rewritten address, all candidates when ambiguous, which parts were recognised and which were not. Never invents a unit. Examples: {"address":"12 Nguyễn Huệ, P. Bến Nghé, Q.1, TP.HCM"}; {"address":"so 1 phu cuong thu dau mot binh duong"}.
data_infoDataset version and sources
Return the dataset version, the official source (National Statistics Office of Viet Nam transition table, with checksum and fetch date), the list of resolutions with issue and effective dates (2025 reform and 2026 changes), unit counts and the coverage note. Use when the user asks how current or reliable the data is. Takes no arguments: {}.
06 — REST

REST API

Every endpoint accepts GET with query parameters; normalize, convert and search also accept POST with the same fields in a JSON body. For addresses typed by people, use POST: a GET query string ends up in proxy and web-server logs, a request body does not. JSON responses, CORS open for any site. The REST endpoints and the MCP tools share the same input rules and the same response format.

Endpoints
EndpointParametersMCP tool
GET, POST /api/v1/address/normalizeaddressnormalize_address
GET, POST /api/v1/address/convertprovince, district, wardconvert_old_to_new
GET, POST /api/v1/address/searchq, scope, level, province, limitfind_units
GET /api/v1/address/provincesscopelist_provinces
GET /api/v1/address/wardsprovince, scopelist_wards
GET /api/v1/address/explaincodeexplain_merge
GET /api/v1/address/meta—data_info

Rewrite a free-form address

curl -X POST "https://since98.vn/api/v1/address/normalize" \
  -H "Content-Type: application/json" \
  -d '{"address":"12 Nguyễn Huệ, P. Bến Nghé, Q.1, TP.HCM"}'
Response (real output on the current data)
{
  "status": "converted",
  "ambiguous": false,
  "confidence": "high",
  "address": "12 Nguyễn Huệ, Phường Sài Gòn, Thành phố Hồ Chí Minh",
  "provinceCode": "79",
  "province": "Thành phố Hồ Chí Minh",
  "street": "12 Nguyễn Huệ",
  "candidates": [
    {
      "code": "26740",
      "name": "Phường Sài Gòn",
      "provinceCode": "79",
      "province": "Thành phố Hồ Chí Minh",
      "address": "12 Nguyễn Huệ, Phường Sài Gòn, Thành phố Hồ Chí Minh",
      "transition": "merge",
      "acts": [
        "1685/NQ-UBTVQH15"
      ],
      "from": {
        "code": "26740",
        "name": "Phường Bến Nghé",
        "district": "Quận 1",
        "province": "Thành phố Hồ Chí Minh"
      }
    }
  ],
  "recognized": {
    "province": "TP.HCM",
    "district": "Q.1",
    "ward": "P. Bến Nghé"
  },
  "dataVersion": "2026.11.20",
  "source": "Official administrative-unit transition table, National Statistics Office of Viet Nam (Cục Thống kê)",
  "disclaimer": "Reference data only. For legally significant actions, verify against the official resolutions."
}

Convert an old address given as parts (a split commune)

curl -X POST "https://since98.vn/api/v1/address/convert" \
  -H "Content-Type: application/json" \
  -d '{"province":"TP.HCM","district":"Quận 8","ward":"Phường 16"}'
Response (real output on the current data)
{
  "status": "ambiguous",
  "ambiguous": true,
  "level": "ward",
  "matches": [
    {
      "old": {
        "code": "27430",
        "name": "Phường 16",
        "districtCode": "776",
        "district": "Quận 8",
        "provinceCode": "79",
        "province": "Thành phố Hồ Chí Minh"
      },
      "split": 3,
      "results": [
        {
          "code": "27364",
          "name": "Phường Bình Phú",
          "provinceCode": "79",
          "province": "Thành phố Hồ Chí Minh",
          "address": "Phường Bình Phú, Thành phố Hồ Chí Minh",
          "transition": "merge",
          "partial": true,
          "acts": [
            "1685/NQ-UBTVQH15"
          ]
        },
        {
          "code": "27427",
          "name": "Phường Phú Định",
          "provinceCode": "79",
          "province": "Thành phố Hồ Chí Minh",
          "address": "Phường Phú Định, Thành phố Hồ Chí Minh",
          "transition": "merge",
          "partial": true,
          "acts": [
            "1685/NQ-UBTVQH15"
          ]
        },
        {
          "code": "27595",
          "name": "Xã Tân Nhựt",
          "provinceCode": "79",
          "province": "Thành phố Hồ Chí Minh",
          "address": "Xã Tân Nhựt, Thành phố Hồ Chí Minh",
          "transition": "merge",
          "partial": true,
          "acts": [
            "1685/NQ-UBTVQH15"
          ]
        }
      ]
    }
  ],
  "messages": [
    "the old commune was split between several new communes; the exact one depends on the street or hamlet"
  ],
  "dataVersion": "2026.11.20",
  "source": "Official administrative-unit transition table, National Statistics Office of Viet Nam (Cục Thống kê)",
  "disclaimer": "Reference data only. For legally significant actions, verify against the official resolutions."
}

What a new commune was formed from

curl "https://since98.vn/api/v1/address/explain?code=26740"
Response (real output on the current data)
{
  "status": "ok",
  "level": "ward",
  "code": "26740",
  "name": "Phường Sài Gòn",
  "provinceCode": "79",
  "province": "Thành phố Hồ Chí Minh",
  "kind": "merge",
  "sources": [
    {
      "code": "26737",
      "name": "Phường Đa Kao",
      "districtCode": "760",
      "district": "Quận 1",
      "provinceCode": "79",
      "province": "Thành phố Hồ Chí Minh",
      "transition": "merge",
      "partial": true,
      "alsoSplitInto": [
        {
          "code": "26737",
          "name": "Phường Tân Định"
        }
      ]
    },
    {
      "code": "26740",
      "name": "Phường Bến Nghé",
      "districtCode": "760",
      "district": "Quận 1",
      "provinceCode": "79",
      "province": "Thành phố Hồ Chí Minh",
      "transition": "merge"
    },
    {
      "code": "26746",
      "name": "Phường Nguyễn Thái Bình",
      "districtCode": "760",
      "district": "Quận 1",
      "provinceCode": "79",
      "province": "Thành phố Hồ Chí Minh",
      "transition": "merge",
      "partial": true,
      "alsoSplitInto": [
        {
          "code": "26743",
          "name": "Phường Bến Thành"
        }
      ]
    }
  ],
  "acts": [
    "1685/NQ-UBTVQH15"
  ],
  "dataVersion": "2026.11.20",
  "source": "Official administrative-unit transition table, National Statistics Office of Viet Nam (Cục Thống kê)",
  "disclaimer": "Reference data only. For legally significant actions, verify against the official resolutions."
}
07 — Rules

Limits, privacy and versions

Limits

Each IP address can make 60 requests per minute and 2,000 per day, REST and MCP together. Over the limit, the REST API answers 429 with a Retry-After header, and the MCP server returns a JSON-RPC error with the same wait time.

Need a higher volume, bulk processing of your own database, or these tools built into your system? Write to us at [email protected] or through the contact page.

Responses of provinces, wards, explain, meta and openapi.json are marked as publicly cacheable for a short time. Responses of normalize, convert and search carry what a person typed, so they are sent with Cache-Control: no-store. Errors and 429 responses are not cached.

What we keep

The application does not save addresses or query text, in a database or in its logs. For the rate limit it keeps a counter per IP address in memory until the time window ends, and a daily count of calls per tool, saved in our database without addresses, IP addresses or query text.

The logs of our web server and Cloudflare record technical request data (time, IP address, path), not the request body. A GET query string is part of the path and is logged with it, so send addresses typed by people with POST, in the request body; the converter page does this. MCP requests are always POST.

API and MCP privacy

Read-only, versioned

All tools only read data and return the same answer for the same input. Every response contains dataVersion, source and disclaimer, so you can store the version next to a converted address.

When the official data changes, we rebuild the dataset and the version changes. The data_info tool and the meta endpoint return the current version and the list of acts.

08 — Sources

Data and sources

The dataset is built from official files with a checksum and a version, and tests check the unit counts after every update.

Acts adopted after the reform and included in the data
ActTitleIn force from
30/2026/QH16Nghị quyết về việc thành lập thành phố Đồng Nai30 April 2026
237/NQ-UBTVQH16Nghị quyết về việc thành lập 10 phường thuộc tỉnh Đồng Nai30 April 2026
36/2026/QH16Về việc thành lập thành phố Quảng Ninh1 September 2026
39/2026/QH16Về việc thành lập thành phố Bắc Ninh20 September 2026
388/NQ-UBTVQH16Nghị quyết Về việc thành lập các phường thuộc tỉnh Bắc Ninh20 September 2026

Reference data, not legal advice. For legally significant actions, rely on the text of the resolutions.

09 — FAQ

Developer questions

Do I need an API key?

No. Both the REST API and the MCP server are open and read-only; only the per-address rate limit applies.

What does ambiguous=true mean?

The old commune was split between several new communes. All of them are returned with partial=true; ask the user for the street or hamlet instead of picking one.

Which MCP transport and protocol versions are supported?

Streamable HTTP over POST, without sessions and without server-sent events. Current clients and older clients that start with initialize both work; GET and DELETE return 405.

Where is the machine-readable description?

The OpenAPI document is at /api/v1/address/openapi.json. MCP clients get tool schemas from tools/list.

10 — Contact

Questions and data errors

Found a wrong or missing unit, or need a different limit for a project? Write to us; one of the founders replies.