Address API v1 Beta

Tài liệu Address API v1

Base URL https://tradiachi.com. JSON UTF-8. Mọi ví dụ phản hồi bên dưới là kết quả thật của endpoint, lấy khi trang được tạo.

Định dạng phản hồi

Thành công

{
  "apiVersion": "1",
  "status": "beta",
  "data": { … },
  "meta": { "requestId": "…", "tookMs": 3, "sources": [{ "id", "name", "asOf" }] }
}

Lỗi

{
  "apiVersion": "1",
  "status": "beta",
  "error": { "code": "INVALID_INPUT", "message": "…", "details": [{ "path": "address", "message": "…" }] },
  "meta": { "requestId": "…", "tookMs": 1 }
}

meta.sources chỉ liệt kê nguồn dữ liệu thực sự đứng sau kết quả đó: gso-2025 nq-202-2025 gso-history ubtvqh .

Mã lỗi

error.code	HTTP	Khi nào
`INVALID_INPUT`	400	Thiếu/sai tham số, JSON hỏng. error.details liệt kê từng trường.
`UNAUTHORIZED`	401	Có gửi API key nhưng key sai, hết hạn hoặc đã thu hồi. Không gửi key thì dùng hạn mức miễn phí theo IP.
`NOT_FOUND`	404	Endpoint không tồn tại.
`PAYLOAD_TOO_LARGE`	413	Body lớn hơn 16 KB.
`RATE_LIMITED`	429	Vượt 30 yêu cầu/phút/IP. Xem header Retry-After.
`INTERNAL`	500	Lỗi hệ thống.
`UNAVAILABLE`	503	Máy chủ đang khởi động (vài giây).

Xác thực

Không cần key: mọi endpoint dùng được miễn phí trong hạn mức theo IP. Gói trả phí cấp API key (tdc_live_…); gửi kèm để dùng hạn mức của gói, tính theo key:

Header

x-api-key: tdc_live_…
# hoặc
Authorization: Bearer tdc_live_…

Key sai, hết hạn hoặc bị thu hồi trả HTTP 401 UNAUTHORIZED (không tự chuyển về hạn mức miễn phí). Bảng giá.

Giới hạn tần suất

30 yêu cầu/phút cho mỗi IP, tính riêng từng endpoint; body tối đa 16 KB. Mọi phản hồi có header RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset (giây); khi vượt: HTTP 429, error.code = "RATE_LIMITED" và Retry-After.

POST `/v1/address/normalize`

Chuẩn hoá địa chỉ. Địa chỉ viết tự do → địa chỉ hiện hành theo mô hình 2 cấp, dạng Address JSON. Khi chưa chắc, trả danh sách ứng viên thay vì đoán. Giao diện web: /tools/chuan-hoa-dia-chi.

Tham số	Vị trí	Kiểu	Bắt buộc	Mô tả
`address`	body	string	có	Địa chỉ viết tự do, 3–300 ký tự (cũ hoặc mới, có/không dấu).

Trả về

data.address — Address JSON (input, normalized, houseNumber, street, ward, province, historical, sources, confidence)
data.candidates[] — khi confidence.level = "ambiguous"

RequestGọi thử →

POST /v1/address/normalizecontent-type: application/json

{"address":"12 nguyen hue p ben nghe q1 tphcm"}

Phản hồi thật · HTTP 200

{
  "apiVersion": "1",
  "status": "beta",
  "data": {
    "address": {
      "input": "12 nguyen hue p ben nghe q1 tphcm",
      "sources": [
        {
          "id": "gso-2025",
          "name": "Danh mục đơn vị hành chính – Tổng cục Thống kê",
          "asOf": "2025-03-01"
        },
        {
          "id": "nq-202-2025",
          "name": "Nghị quyết 202/2025/QH15 và các nghị quyết sắp xếp cấp xã năm 2025",
          "asOf": "2025-07-01"
        }
      ],
      "confidence": {
        "level": "exact",
        "ai": false
      },
      "dataUpdated": "2026-09-30",
      "normalized": "12 nguyen hue, Phường Sài Gòn, Thành phố Hồ Chí Minh",
      "houseNumber": "12",
      "street": "nguyen hue",
      "ward": {
        "name": "Phường Sài Gòn",
        "code": "26740",
        "slug": "phuong-sai-gon"
      },
      "province": {
        "name": "Thành phố Hồ Chí Minh",
        "code": "79",
        "slug": "ho-chi-minh"
      },
      "historical": {
        "oldWard": {
          "name": "Phường Bến Nghé",
          "code": "26740",
          "slug": "phuong-ben-nghe"
        },
        "oldDistrict": {
          "name": "Quận 1",
          "code": "760",
          "slug": "quan-1"
        },
        "oldProvince": {
          "name": "Thành phố Hồ Chí Minh",
          "code": "79",
          "slug": "thanh-pho-ho-chi-minh"
        }
      }
    },
    "candidates": []
  },
  "meta": {
    "requestId": "req-6y",
    "tookMs": 20,
    "sources": [
      {
        "id": "gso-2025",
        "name": "Danh mục đơn vị hành chính – Tổng cục Thống kê",
        "asOf": "2025-03-01"
      },
      {
        "id": "nq-202-2025",
        "name": "Nghị quyết 202/2025/QH15 và các nghị quyết sắp xếp cấp xã năm 2025",
        "asOf": "2025-07-01"
      }
    ]
  }
}

POST `/v1/address/parse`

Tách địa chỉ. Tách số nhà, đường, phường/xã, quận/huyện, tỉnh/thành đã đối chiếu danh mục; cho biết mô hình 3 cấp hay 2 cấp. Giao diện web: /tools/tach-dia-chi.

Tham số	Vị trí	Kiểu	Bắt buộc	Mô tả
`address`	body	string	có	Địa chỉ viết tự do, 3–300 ký tự (cũ hoặc mới, có/không dấu).

Trả về

data.model — "old-3-level" | "new-2-level" | "unknown"
data.components — houseNumber, street, ward, district, province (kèm mã)
data.current — phường/xã và tỉnh hiện hành

RequestGọi thử →

POST /v1/address/parsecontent-type: application/json

{"address":"12 Nguyễn Huệ, P. Bến Nghé, Q.1, TP.HCM"}

Phản hồi thật · HTTP 200

{
  "apiVersion": "1",
  "status": "beta",
  "data": {
    "input": "12 Nguyễn Huệ, P. Bến Nghé, Q.1, TP.HCM",
    "model": "old-3-level",
    "confidence": "exact",
    "components": {
      "houseNumber": "12",
      "street": "Nguyễn Huệ",
      "ward": {
        "name": "Phường Bến Nghé",
        "code": "26740",
        "slug": "phuong-ben-nghe"
      },
      "district": {
        "name": "Quận 1",
        "code": "760",
        "slug": "quan-1"
      },
      "province": {
        "name": "Thành phố Hồ Chí Minh",
        "code": "79",
        "slug": "thanh-pho-ho-chi-minh"
      }
    },
    "current": {
      "ward": {
        "name": "Phường Sài Gòn",
        "code": "26740",
        "slug": "phuong-sai-gon"
      },
      "province": {
        "name": "Thành phố Hồ Chí Minh",
        "code": "79",
        "slug": "ho-chi-minh"
      }
    }
  },
  "meta": {
    "requestId": "req-6z",
    "tookMs": 25,
    "sources": [
      {
        "id": "gso-2025",
        "name": "Danh mục đơn vị hành chính – Tổng cục Thống kê",
        "asOf": "2025-03-01"
      },
      {
        "id": "nq-202-2025",
        "name": "Nghị quyết 202/2025/QH15 và các nghị quyết sắp xếp cấp xã năm 2025",
        "asOf": "2025-07-01"
      }
    ]
  }
}

POST `/v1/address/validate`

Kiểm tra địa chỉ. Đơn vị hành chính có tồn tại không, đã giải thể chưa, địa chỉ đã viết theo mô hình hiện hành chưa. Giao diện web: /tools/kiem-tra-dia-chi.

Tham số	Vị trí	Kiểu	Bắt buộc	Mô tả
`address`	body	string	có	Địa chỉ viết tự do, 3–300 ký tự (cũ hoặc mới, có/không dấu).

Trả về

data.valid, data.current
data.issues[] — code: PROVINCE_NOT_FOUND | DISTRICT_NOT_FOUND | WARD_NOT_FOUND | AMBIGUOUS | FUZZY_MATCH | OUTDATED_MODEL | DISSOLVED_UNIT
data.suggestion — địa chỉ hiện hành đề xuất

RequestGọi thử →

POST /v1/address/validatecontent-type: application/json

{"address":"Phường 11, Quận 10, TP.HCM"}

Phản hồi thật · HTTP 200

{
  "apiVersion": "1",
  "status": "beta",
  "data": {
    "input": "Phường 11, Quận 10, TP.HCM",
    "valid": true,
    "current": false,
    "model": "old-3-level",
    "confidence": "exact",
    "issues": [
      {
        "code": "OUTDATED_MODEL",
        "field": "address",
        "message": "Địa chỉ theo mô hình 3 cấp (có quận/huyện), không còn dùng từ 01/07/2025."
      },
      {
        "code": "DISSOLVED_UNIT",
        "field": "ward",
        "message": "Phường 11 đã không còn từ 01/01/2025 (1278/NQ-UBTVQH15)."
      }
    ],
    "suggestion": "Phường Vườn Lài, Thành phố Hồ Chí Minh"
  },
  "meta": {
    "requestId": "req-40",
    "tookMs": 7,
    "sources": [
      {
        "id": "gso-2025",
        "name": "Danh mục đơn vị hành chính – Tổng cục Thống kê",
        "asOf": "2025-03-01"
      },
      {
        "id": "nq-202-2025",
        "name": "Nghị quyết 202/2025/QH15 và các nghị quyết sắp xếp cấp xã năm 2025",
        "asOf": "2025-07-01"
      }
    ]
  }
}

POST `/v1/address/compare`

So sánh 2 địa chỉ. Hai địa chỉ có cùng một nơi không, theo phường/xã hiện hành và số nhà/đường. Kết luận theo quy tắc, không có điểm số. Giao diện web: /tools/so-sanh-dia-chi.

Tham số	Vị trí	Kiểu	Bắt buộc	Mô tả
`a`	body	string	có	Địa chỉ thứ nhất, 3–300 ký tự.
`b`	body	string	có	Địa chỉ thứ hai, 3–300 ký tự.

Trả về

data.verdict — "same" | "different" | "uncertain"
data.reason
data.checks — ward, street, oldWard: match | mismatch | unknown
data.a, data.b — Address JSON

RequestGọi thử →

POST /v1/address/comparecontent-type: application/json

{"a":"12 Nguyễn Huệ, P. Bến Nghé, Q.1, TP.HCM","b":"12 nguyen hue, phuong sai gon, ho chi minh"}

Phản hồi thật · HTTP 200

{
  "apiVersion": "1",
  "status": "beta",
  "data": {
    "verdict": "same",
    "reason": "Cùng số nhà/đường và cùng Phường Sài Gòn.",
    "checks": {
      "ward": "match",
      "street": "match",
      "oldWard": "unknown"
    },
    "a": {
      "input": "12 Nguyễn Huệ, P. Bến Nghé, Q.1, TP.HCM",
      "sources": [
        {
          "id": "gso-2025",
          "name": "Danh mục đơn vị hành chính – Tổng cục Thống kê",
          "asOf": "2025-03-01"
        },
        {
          "id": "nq-202-2025",
          "name": "Nghị quyết 202/2025/QH15 và các nghị quyết sắp xếp cấp xã năm 2025",
          "asOf": "2025-07-01"
        }
      ],
      "confidence": {
        "level": "exact",
        "ai": false
      },
      "dataUpdated": "2026-09-30",
      "normalized": "12 Nguyễn Huệ, Phường Sài Gòn, Thành phố Hồ Chí Minh",
      "houseNumber": "12",
      "street": "Nguyễn Huệ",
      "ward": {
        "name": "Phường Sài Gòn",
        "code": "26740",
        "slug": "phuong-sai-gon"
      },
      "province": {
        "name": "Thành phố Hồ Chí Minh",
        "code": "79",
        "slug": "ho-chi-minh"
      },
      "historical": {
        "oldWard": {
          "name": "Phường Bến Nghé",
          "code": "26740",
          "slug": "phuong-ben-nghe"
        },
        "oldDistrict": {
          "name": "Quận 1",
          "code": "760",
          "slug": "quan-1"
        },
        "oldProvince": {
          "name": "Thành phố Hồ Chí Minh",
          "code": "79",
          "slug": "thanh-pho-ho-chi-minh"
        }
      }
    },
    "b": {
      "input": "12 nguyen hue, phuong sai gon, ho chi minh",
      "sources": [
        {
          "id": "nq-202-2025",
          "name": "Nghị quyết 202/2025/QH15 và các nghị quyết sắp xếp cấp xã năm 2025",
          "asOf": "2025-07-01"
        }
      ],
      "confidence": {
        "level": "exact",
        "ai": false
      },
      "dataUpdated": "2026-09-30",
      "normalized": "12 nguyen hue, Phường Sài Gòn, Thành phố Hồ Chí Minh",
      "houseNumber": "12",
      "street": "nguyen hue",
      "ward": {
        "name": "Phường Sài Gòn",
        "code": "26740",
        "slug": "phuong-sai-gon"
      },
      "province": {
        "name": "Thành phố Hồ Chí Minh",
        "code": "79",
        "slug": "ho-chi-minh"
      }
    }
  },
  "meta": {
    "requestId": "req-70",
    "tookMs": 49,
    "sources": [
      {
        "id": "gso-2025",
        "name": "Danh mục đơn vị hành chính – Tổng cục Thống kê",
        "asOf": "2025-03-01"
      },
      {
        "id": "nq-202-2025",
        "name": "Nghị quyết 202/2025/QH15 và các nghị quyết sắp xếp cấp xã năm 2025",
        "asOf": "2025-07-01"
      }
    ]
  }
}

POST `/v1/address/history`

Lịch sử hành chính. Các lần đổi tên, chuyển huyện, sáp nhập của đơn vị trong địa chỉ từ 2004, kèm nghị quyết; và các đơn vị cũ đã gộp vào phường/xã hiện hành. Giao diện web: /tools/lich-su-dia-chi.

Tham số	Vị trí	Kiểu	Bắt buộc	Mô tả
`address`	body	string	có	Địa chỉ viết tự do, 3–300 ký tự (cũ hoặc mới, có/không dấu).

Trả về

data.address — Address JSON
data.dissolved — { on, by[] } nếu đơn vị cũ đã giải thể
data.timeline[] — { from, to, name, district, province, event, doc }
data.mergedInto — { ward, from[] }

RequestGọi thử →

POST /v1/address/historycontent-type: application/json

{"address":"Phường 11, Quận 10, TP.HCM"}

Phản hồi thật · HTTP 200

{
  "apiVersion": "1",
  "status": "beta",
  "data": {
    "address": {
      "input": "Phường 11, Quận 10, TP.HCM",
      "sources": [
        {
          "id": "gso-2025",
          "name": "Danh mục đơn vị hành chính – Tổng cục Thống kê",
          "asOf": "2025-03-01"
        },
        {
          "id": "nq-202-2025",
          "name": "Nghị quyết 202/2025/QH15 và các nghị quyết sắp xếp cấp xã năm 2025",
          "asOf": "2025-07-01"
        },
        {
          "id": "gso-history",
          "name": "Danh mục Tổng cục Thống kê qua các thời kỳ",
          "asOf": "2025-03-01"
        },
        {
          "id": "ubtvqh",
          "name": "Nghị quyết của Ủy ban Thường vụ Quốc hội về sắp xếp đơn vị hành chính",
          "asOf": "2025-03-01"
        }
      ],
      "confidence": {
        "level": "exact",
        "ai": false
      },
      "dataUpdated": "2026-09-30",
      "normalized": "Phường Vườn Lài, Thành phố Hồ Chí Minh",
      "ward": {
        "name": "Phường Vườn Lài",
        "code": "27190",
        "slug": "phuong-vuon-lai"
      },
      "province": {
        "name": "Thành phố Hồ Chí Minh",
        "code": "79",
        "slug": "ho-chi-minh"
      },
      "historical": {
        "oldWard": {
          "name": "Phường 11",
          "code": "27175",
          "slug": "phuong-11"
        },
        "oldDistrict": {
          "name": "Quận 10",
          "code": "771",
          "slug": "quan-10"
        },
        "oldProvince": {
          "name": "Thành phố Hồ Chí Minh",
          "code": "79",
          "slug": "thanh-pho-ho-chi-minh"
        },
        "dissolved": {
          "on": "2025-01-01",
          "by": [
            "1278/NQ-UBTVQH15"
          ]
        },
        "timeline": [
          {
            "from": "2004-08-31",
            "to": "2025-01-01",
            "name": "Phường 11",
            "district": "Quận 10",
            "province": "Thành phố Hồ Chí Minh",
            "event": "nhập vào Phường 10 (Quận 10)",
            "doc": "1278/NQ-UBTVQH15"
          }
        ]
      }
    },
    "dissolved": {
      "on": "2025-01-01",
      "by": [
        "1278/NQ-UBTVQH15"
      ]
    },
    "timeline": [
      {
        "from": "2004-08-31",
        "to": "2025-01-01",
        "name": "Phường 11",
        "district": "Quận 10",
        "province": "Thành phố Hồ Chí Minh",
        "event": "nhập vào Phường 10 (Quận 10)",
        "doc": "1278/NQ-UBTVQH15"
      }
    ],
    "mergedInto": {
      "ward": {
        "name": "Phường Vườn Lài",
        "code": "27190",
        "slug": "phuong-vuon-lai"
      },
      "from": [
        {
          "ward": "Phường 1",
          "district": "Quận 10",
          "province": "Thành phố Hồ Chí Minh",
          "dissolved": false
        },
        {
          "ward": "Phường 2",
          "district": "Quận 10",
          "province": "Thành phố Hồ Chí Minh",
          "dissolved": false
        },
        {
          "ward": "Phường 4",
          "district": "Quận 10",
          "province": "Thành phố Hồ Chí Minh",
          "dissolved": false
        },
        {
          "ward": "Phường 9",
          "district": "Quận 10",
          "province": "Thành phố Hồ Chí Minh",
          "dissolved": false
        },
        {
          "ward": "Phường 10",
          "district": "Quận 10",
          "province": "Thành phố Hồ Chí Minh",
          "dissolved": false
        },
        {
          "ward": "Phường 11",
          "district": "Quận 10",
          "province": "Thành phố Hồ Chí Minh",
          "dissolved": true
        },
        {
          "ward": "Phường 3",
          "district": "Quận 10",
          "province": "Thành phố Hồ Chí Minh",
          "dissolved": true
        }
      ]
    }
  },
  "meta": {
    "requestId": "req-71",
    "tookMs": 52,
    "sources": [
      {
        "id": "gso-2025",
        "name": "Danh mục đơn vị hành chính – Tổng cục Thống kê",
        "asOf": "2025-03-01"
      },
      {
        "id": "nq-202-2025",
        "name": "Nghị quyết 202/2025/QH15 và các nghị quyết sắp xếp cấp xã năm 2025",
        "asOf": "2025-07-01"
      },
      {
        "id": "gso-history",
        "name": "Danh mục Tổng cục Thống kê qua các thời kỳ",
        "asOf": "2025-03-01"
      },
      {
        "id": "ubtvqh",
        "name": "Nghị quyết của Ủy ban Thường vụ Quốc hội về sắp xếp đơn vị hành chính",
        "asOf": "2025-03-01"
      }
    ]
  }
}

GET `/v1/address/autocomplete`

Gợi ý đơn vị hành chính. Gợi ý phường/xã, quận/huyện, tỉnh/thành (cũ và mới) khi người dùng đang gõ; không cần dấu. Giao diện web: /tools/moi-sang-cu.

Tham số	Vị trí	Kiểu	Bắt buộc	Mô tả
`q`	query	string	có	2–100 ký tự.
`limit`	query	integer	không	1–10, mặc định 10.
`scope`	query	string	không	"all" (mặc định) \| "new" \| "old".

Trả về

data.items[] — { type, model, name, label, code, slug, dissolved }

RequestGọi thử →

GET /v1/address/autocomplete?q=vuon+lai&limit=5&scope=all

Phản hồi thật · HTTP 200

{
  "apiVersion": "1",
  "status": "beta",
  "data": {
    "items": [
      {
        "type": "ward_new",
        "model": "new",
        "name": "Phường Vườn Lài",
        "label": "Phường Vườn Lài, Thành phố Hồ Chí Minh",
        "code": "27190",
        "slug": "phuong-vuon-lai",
        "dissolved": false
      },
      {
        "type": "ward_old",
        "model": "old",
        "name": "Xã Lai Vu",
        "label": "Xã Lai Vu, Huyện Kim Thành, Tỉnh Hải Dương",
        "code": "10753",
        "slug": "xa-lai-vu",
        "dissolved": true
      },
      {
        "type": "ward_new",
        "model": "new",
        "name": "Xã Lai Vung",
        "label": "Xã Lai Vung, Tỉnh Đồng Tháp",
        "code": "30226",
        "slug": "xa-lai-vung",
        "dissolved": false
      },
      {
        "type": "district_old",
        "model": "old",
        "name": "Huyện Lai Vung",
        "label": "Huyện Lai Vung, Tỉnh Đồng Tháp",
        "code": "876",
        "slug": "huyen-lai-vung",
        "dissolved": false
      },
      {
        "type": "ward_old",
        "model": "old",
        "name": "Thị trấn Lai Vung",
        "label": "Thị trấn Lai Vung, Huyện Lai Vung, Tỉnh Đồng Tháp",
        "code": "30208",
        "slug": "thi-tran-lai-vung",
        "dissolved": false
      }
    ]
  },
  "meta": {
    "requestId": "req-72",
    "tookMs": 434,
    "sources": [
      {
        "id": "gso-2025",
        "name": "Danh mục đơn vị hành chính – Tổng cục Thống kê",
        "asOf": "2025-03-01"
      },
      {
        "id": "nq-202-2025",
        "name": "Nghị quyết 202/2025/QH15 và các nghị quyết sắp xếp cấp xã năm 2025",
        "asOf": "2025-07-01"
      }
    ]
  }
}