1. REST API

Phương thức HTTP tiêu chuẩn (POST), Content-Type: application/json.

Endpoint URL:

https://api.maichiparser.com/v1/solutions/parser

Header (API Key):

x-maichi-key: <my-key>

Ví dụ mẫu (Example Request):

curl --location 'https://api.maichiparser.com/v1/solutions/parser' \
    --header 'Content-Type: application/json' \
    --header 'x-maichi-key: my-key' \
    --data '{
            "config": {
                "enableCode": true,
                "enableNormalization": true,
                "enableInference": false,
                "enableDisplayNormalization": false,
                "enableLooseMode": false
            },
            "addresses": [
                {
                    "key": "testing",
                    "address": "tp.hcm, quận bình tân, phường tân tạo a, số nhà 110 bờ tuyến, khu phố 3"
                }
            ]
    }'

Kết quả trả về (Response):

{
    "data": {
        "addresses": [
            {
                "key": "testing",
                "percent": 89.61,
                "administrativeType": 3,
                "isCurrent": false,
                "conflictDetected": false,
                "formattedAddress": "số nhà 110 bờ tuyến, khu phố 3, tân tạo a, bình tân, hồ chí minh",
                "houseNumber": {
                    "value": "110",
                    "useInference": false,
                    "percent": 100
                },
                "street": {
                    "value": "số nhà 110 bờ tuyến",
                    "normalization": "bờ tuyến",
                    "useInference": false,
                    "percent": 95
                },
                "village": {
                    "value": "khu phố 3",
                    "normalization": "khu phố 3",
                    "useInference": false,
                    "percent": 100
                },
                "locality": {
                    "value": "tân tạo a",
                    "normalization": "tân tạo a",
                    "useInference": false,
                    "code": "27457",
                    "percent": 100
                },
                "county": {
                    "value": "bình tân",
                    "normalization": "bình tân",
                    "useInference": false,
                    "code": "777",
                    "percent": 100
                },
                "region": {
                    "value": "hcm",
                    "normalization": "hồ chí minh",
                    "useInference": false,
                    "code": "79",
                    "percent": 100
                }
            }
        ],
        "total": 1
    },
    "statusCode": "99",
    "version": "1.0.0",
    "message": "Thành công"
}

Định nghĩa dữ liệu

Request Parameters

Trường (Field)	Kiểu	Mô tả
`config`	Object	Các thông số cấu hình tùy chỉnh
`enableInference`	Boolean	[Mặc định: false] Cấu hình cho phép bổ sung đơn vị hành chính bị khuyết thiếu (nếu có thể) - True: Tự động trả về thêm thông tin đơn vị hành chính bị khuyết thiếu - False: Không tự động trả về Ví dụ: Đức Thắng, Hà Nội (thiếu đơn vị cấp huyện) -> Đức Thắng, Bắc Từ Liêm, Hà Nội (bổ sung đơn vị cấp huyện còn thiếu)
`enableNormalization`	Boolean	[Mặc định: false] Cấu hình cho phép bổ sung thông tin tên đơn vị hành chính đã chuẩn hóa (nếu có thể) - True: Trả thêm thông tin normalization - False: Không trả về thông tin normalization Ví dụ: "hn" -> "hà nội"
`enableDisplayNormalization`	Boolean	[Mặc định: false] Cấu hình cho phép làm đẹp hiển thị thông tin đơn vị hành chính đã chuẩn hóa (normalization) - True: Làm đẹp hiển thị normalization - False: Giữ nguyên giá trị của normalization Ví dụ: "hà nội" -> "Hà Nội"
`enableCode`	Boolean	[Mặc định: false] Cấu hình cho phép bổ sung thông tin mã đơn vị hành chính của tổng cục thống kê (nếu có thể) - True: Trả thêm thông tin code - False: Không trả thông tin code Ví dụ: Hà Nội (mã GSO: 01)
`enableLooseMode`	Boolean	[Mặc định: false] Cấu hình cho phép trả thông tin hành chính (tỉnh - huyện - xã) ngay cả khi các cấp hành chính này không tồn tại trong thực tế. - True: Cho phép - False: Không cho phép Ví dụ: đầu vào địa chỉ là "phường Phan Chu Trinh, Hai Bà Trưng, HN" đây là một địa chỉ có các cấp hành chính không hợp lệ (vì không tồn tại phường "Phan Chu Trinh" thuộc quận "Hai Bà Trưng"). Khi bật chế độ enableLooseMode nó cho phép trả về cả kết quả locality: "phan chu trinh" và county: "hai bà trưng", đồng thời đánh dấu dữ liệu có conflictDetected: true (tức phát hiện quan hệ hành chính không hợp lệ).
`addresses[]`	Array	Danh sách địa chỉ đầu vào (tối đa: 100 địa chỉ)
`key`	String	Mã định danh do người dùng tự định nghĩa (tối đa: 64 kí tự)
`address`	String	Chuỗi thông tin địa chỉ (tối đa: 150 kí tự)

Response Fields

Trường (Field)	Kiểu	Mô tả
`statusCode`	String	Mã trạng thái ("99" = Thành công)
`message`	String	Thông báo từ hệ thống
`version`	String	Phiên bản ứng dụng
`data`	Object	Dữ liệu kết quả xử lí
`total`	Int	Tổng số bản ghi
`addresses[]`	Array	Danh sách kết quả
`key`	String	Mã định danh do người dùng tự định nghĩa
`percent`	Double	Độ chính xác của kết quả (giá trị 0-100%) - Ở cấp độ đơn vị hành chính ngưỡng an toàn >= 80% - Tùy thuộc vào hệ thống tích hợp, bạn có thể điều chỉnh giá trị phù hợp.
`isCurrent`	Boolean	Xác định đơn vị hành chính đang có giá trị hiện hành (mới nhất): - True: Đang hiện hành - False: Không còn hiện hành Thông tin này giúp xác định được địa chỉ đầu vào có các cấp hành chính hợp lệ và có giá trị hiện hành.
`conflictDetected`	Boolean	Xác định các cấp hành chính (tỉnh - huyện - xã) trong kết quả trả về có vi phạm tính đúng đắn hoặc không tồn tại: - True: Kết quả cấp hành chính vi phạm tính đúng đắn - False: Kết quả cấp hành chính không vi phạm
`administrativeType`	Int	Thông tin về loại cấp đơn vị hành chính: - 0: Không xác định - 2: Đơn vị 2 cấp (mới 2025) - 3: Đơn vị 3 cấp (cũ)
`formattedAddress`	String	Thông tin địa chỉ đã làm sạch, yêu cầu bật chức năng enableNormalization
`houseNumber`	Object	Đơn vị số nhà
`place`	Object	Đơn vị địa điểm
`street`	Object	Đơn vị tên đường
`village`	Object	Đơn vị thôn, xóm,...
`locality`	Object	Đơn vị phường, xã, thị trấn,...
`county`	Object	Đơn vị quận, huyện,...
`region`	Object	Đơn vị tỉnh, thành phố,...

`[Đơn vị hành chính]`	Object	Thông tin đơn vị hành chính được trích xuất
`value`	String	Giá trị thông tin gốc
`normalization`	String	Giá trị thông tin đã chuẩn hóa
`useInference`	Boolean	Giá trị xác định đơn vị hành chính này được tự động bổ sung (do dữ liệu gốc bị khuyết thiếu)
`code`	String	Mã đơn vị hành chính theo chuẩn của tổng cục thống kê
`percent`	Double	Độ chính xác của kết quả (giá trị 0-100%) - Ở cấp độ đơn vị hành chính ngưỡng an toàn >= 80% - Tùy thuộc vào hệ thống tích hợp, bạn có thể điều chỉnh giá trị phù hợp.

2. gRPC API

Giao thức hiệu năng cao thích hợp cho Microservices.

Server Address:

https://grpc.maichiparser.com

Meta Data (API Key):

x-maichi-key: <my-key>

Service Name:

maichi.ParserService

Protobuf Definition (.proto)

syntax = "proto3";

package maichi;

// Service

service ParserService {
  rpc Processing (ParserRequest) returns (DataResponse);
}

// Request

message ParserRequest {
  repeated AddressRequest addresses = 1;
  optional ConfigRequest config = 2;
}

message AddressRequest {
  string key = 1;
  string address = 2;
}

message ConfigRequest {
  optional bool enable_inference = 1;
  optional bool enable_normalization = 2;
  optional bool enable_code = 3;
  optional bool enable_display_normalization = 4;
  optional bool enable_loose_mode = 5;
}

// Response

message DataResponse {
  ParserResponse data = 1;
  string status_code = 2;
  string version = 3;
  string message = 4;
}

message ParserResponse {
  repeated Result addresses = 1;
  int32 total = 2;
}

message Result {
  optional string key = 1;
  optional double percent = 2;
  optional bool is_current = 3;
  optional int32 administrative_type = 4;
  optional Item house_number = 5;
  optional Item place = 6;
  optional Item street = 7;
  optional Item village = 8;
  optional Item locality = 9;
  optional Item county = 10;
  optional Item region = 11;
  optional bool conflict_detected = 12;
  optional string formatted_address = 13;
}

message Item {
  optional string value = 1;
  optional string normalization = 2;
  optional bool use_inference = 3;
  optional string code = 4;
  optional double percent = 5;
}

3. Health Check

Kiểm tra tình trạng hoạt động của dịch vụ

Endpoint URL:

https://api.maichiparser.com/health/live

API Documentation

1. REST API

Định nghĩa dữ liệu

2. gRPC API

3. Health Check