Tài liệu API

Điều hướng

Giới thiệu

Chào mừng đến với API Đơn vị hành chính Việt Nam. API này cung cấp quyền truy cập vào dữ liệu đơn vị hành chính và dịch vụ chuyển đổi địa chỉ.

URL cơ sở
https://tinhthanhpho.com/api/v1
Thông tin chung
  • Định dạng phản hồi: JSON
  • Content Type: application/json

Xác thực

Một số endpoints yêu cầu xác thực bằng API key. Bao gồm API key của bạn trong header Authorization:

Header xác thực
Authorization: Bearer YOUR_API_KEY
Tạo khóa API

Giới hạn tốc độ

Loại truy cập Giới hạn tốc độ
API công khai 100 yêu cầu/phút
API đã xác thực Dựa trên cài đặt khóa API

Endpoints

Cấu trúc cũ (Trước 1/7/2025)

GET /api/v1/provinces

Tỉnh/Thành phố (Cấu trúc cũ (Trước 1/7/2025))

Tham số:
Tên Kiểu Bắt buộc Mô tả
keyword string Không Từ khóa tìm kiếm hoặc ID
limit integer Không Số kết quả mỗi trang (default: 20)
page integer Không Số trang (default: 1)
Phản hồi:
{
  "success": true,
  "data": [
    {
      "code": "01",
      "name": "Hà Nội",
      "type": "Thành phố"
    },
    ...
  ],
  "metadata": {
    "total": 63,
    "page": 1,
    "limit": 20
  }
}
GET /api/v1/provinces/{provinceCode}/districts

Quận/Huyện theo Tỉnh/Thành phố

Tham số:
Tên Kiểu Bắt buộc Mô tả
provinceCode (path) string Có Mã tỉnh
keyword string Không Từ khóa tìm kiếm hoặc ID
limit integer Không Số kết quả mỗi trang (default: 20)
page integer Không Số trang (default: 1)
Phản hồi:
{
  "success": true,
  "data": [
    {
      "code": "001",
      "name": "Ba Đình",
      "type": "Quận",
      "province_code": "01"
    },
    ...
  ],
  "metadata": {
    "total": 30,
    "page": 1,
    "limit": 20
  }
}
GET /api/v1/districts/{districtCode}/wards

Phường/Xã theo Quận/Huyện

Tham số:
Tên Kiểu Bắt buộc Mô tả
districtCode (path) string Có Mã quận/huyện
keyword string Không Từ khóa tìm kiếm hoặc ID
limit integer Không Số kết quả mỗi trang (default: 20)
page integer Không Số trang (default: 1)
Phản hồi:
{
  "success": true,
  "data": [
    {
      "code": "00001",
      "name": "Phúc Xá",
      "type": "Phường",
      "district_code": "001",
      "province_code": "01"
    },
    ...
  ],
  "metadata": {
    "total": 15,
    "page": 1,
    "limit": 20
  }
}
GET /api/v1/full-address

Địa chỉ đầy đủ (Cấu trúc cũ (Trước 1/7/2025))

Tham số:
Tên Kiểu Bắt buộc Mô tả
provinceCode string Không Mã tỉnh
districtCode string Không Mã quận/huyện
wardCode string Không Mã phường/xã
Phản hồi:
{
  "success": true,
  "data": {
    "province": {
      "code": "01",
      "name": "Hà Nội",
      "type": "Thành phố"
    },
    "district": {
      "code": "001",
      "name": "Ba Đình",
      "type": "Quận"
    },
    "ward": {
      "code": "00001",
      "name": "Phúc Xá", 
      "type": "Phường"
    }
  }
}

Cấu trúc mới (Sau 1/7/2025)

GET /api/v1/new-provinces

Tỉnh/Thành phố (Cấu trúc mới (Sau 1/7/2025))

Tham số:
Tên Kiểu Bắt buộc Mô tả
keyword string Không Từ khóa tìm kiếm hoặc ID
limit integer Không Số kết quả mỗi trang (default: 20)
page integer Không Số trang (default: 1)
Phản hồi:
{
  "success": true,
  "data": [
    {
      "code": "01",
      "name": "Hà Nội",
      "type": "Thành phố"
    },
    ...
  ],
  "metadata": {
    "total": 37,
    "page": 1,
    "limit": 20
  }
}
GET /api/v1/new-provinces/{provinceCode}/wards

Phường/Xã theo Tỉnh/Thành phố (Cấu trúc mới (Sau 1/7/2025))

Tham số:
Tên Kiểu Bắt buộc Mô tả
provinceCode (path) string Có Mã tỉnh
keyword string Không Từ khóa tìm kiếm hoặc ID
limit integer Không Số kết quả mỗi trang (default: 20)
page integer Không Số trang (default: 1)
Phản hồi:
{
  "success": true,
  "data": [
    {
      "code": "00070",
      "name": "Hoàn Kiếm",
      "type": "Phường",
      "province_code": "01"
    },
    ...
  ],
  "metadata": {
    "total": 100,
    "page": 1,
    "limit": 20
  }
}
GET /api/v1/new-full-address

Địa chỉ đầy đủ (Cấu trúc mới (Sau 1/7/2025))

Tham số:
Tên Kiểu Bắt buộc Mô tả
provinceCode string Không Mã tỉnh
wardCode string Không Mã phường/xã
Phản hồi:
{
  "success": true,
  "data": {
    "province": {
      "code": "01",
      "name": "Hà Nội",
      "type": "Thành phố"
    },
    "ward": {
      "code": "00070",
      "name": "Hoàn Kiếm",
      "type": "Phường"
    }
  }
}
GET /api/v1/search-address

Tra cứu đơn vị hành chính (Cấu trúc cũ (Trước 1/7/2025))

Tham số:
Tên Kiểu Bắt buộc Mô tả
keyword string Có Từ khóa tìm kiếm hoặc ID
limit integer Không Số kết quả mỗi trang (default: 20)
Phản hồi:
{
  "success": true,
  "data": [
    {
      "type": "province",
      "code": "01",
      "name": "Hà Nội",
      "full_name": "Thành phố Hà Nội",
      "address": "Thành phố Hà Nội"
    },
    {
      "type": "district",
      "code": "001",
      "name": "Ba Đình",
      "full_name": "Quận Ba Đình",
      "address": "Quận Ba Đình, Thành phố Hà Nội",
      "province_code": "01"
    },
    ...
  ]
}
GET /api/v1/search-new-address

Tra cứu đơn vị hành chính (Cấu trúc mới (Sau 1/7/2025))

Tham số:
Tên Kiểu Bắt buộc Mô tả
keyword string Có Từ khóa tìm kiếm hoặc ID
limit integer Không Số kết quả mỗi trang (default: 20)
Phản hồi:
{
  "success": true,
  "data": [
    {
      "type": "province",
      "code": "01",
      "name": "Hà Nội",
      "full_name": "Thành phố Hà Nội",
      "address": "Thành phố Hà Nội"
    },
    {
      "type": "ward",
      "code": "00070",
      "name": "Hoàn Kiếm",
      "full_name": "Phường Hoàn Kiếm",
      "address": "Phường Hoàn Kiếm, Thành phố Hà Nội",
      "province_code": "01"
    },
    ...
  ]
}

API chuyển đổi

POST /api/v1/convert/address Yêu cầu xác thực

Chuyển đổi địa chỉ đơn lẻ

Nội dung yêu cầu:
{
  "provinceCode": "01",
  "districtCode": "001",
  "wardCode": "00001",
  "streetAddress": "15 Nguyễn Văn A"
}
Phản hồi:
{
  "success": true,
  "data": {
    "old": {
      "province": {"code": "01", "name": "Hà Nội", "type": "Thành phố"},
      "district": {"code": "001", "name": "Ba Đình", "type": "Quận"},
      "ward": {"code": "00001", "name": "Phúc Xá", "type": "Phường"},
      "fullAddress": "15 Nguyễn Văn A, Phường Phúc Xá, Quận Ba Đình, Thành phố Hà Nội"
    },
    "new": {
      "province": {"code": "01", "name": "Hà Nội", "type": "Thành phố"},
      "ward": {"code": "00004", "name": "Ba Đình", "type": "Phường"},
      "fullAddress": "15 Nguyễn Văn A, Phường Ba Đình, Thành phố Hà Nội"
    },
    "mergeInfo": {
      "notes": "Quận Ba Đình đã được sáp nhập, Phường Phúc Xá đã được sáp nhập vào Phường Ba Đình"
    }
  }
}
POST /api/v1/convert/batch Yêu cầu xác thực

Chuyển đổi địa chỉ hàng loạt

Nội dung yêu cầu:
{
  "addresses": [
    {
      "id": "addr_001",
      "provinceCode": "01",
      "districtCode": "001",
      "wardCode": "00001",
      "streetAddress": "15 Nguyễn Văn A"
    },
    {
      "id": "addr_002",
      "provinceCode": "01",
      "districtCode": "002",
      "wardCode": "00037",
      "streetAddress": "28 Lê Lợi"
    }
  ]
}
Phản hồi:
{
  "success": true,
  "data": {
    "total": 2,
    "converted": 2,
    "failed": 0,
    "results": [
      {
        "id": "addr_001",
        "old": { /* Thông tin địa chỉ cũ */ },
        "new": { /* Thông tin địa chỉ mới */ }
      },
      {
        "id": "addr_002",
        "old": { /* Thông tin địa chỉ cũ */ },
        "new": { /* Thông tin địa chỉ mới */ }
      }
    ],
    "errors": []
  }
}
GET /api/v1/merge-history/province/{code} Yêu cầu xác thực

Lịch sử sáp nhập - Tỉnh/Thành phố

Tham số:
Tên Kiểu Bắt buộc Mô tả
code (path) string Có Mã tỉnh
Phản hồi:
{
  "success": true,
  "data": [
    {
      "id": 1,
      "old_province_code": "02",
      "new_province_code": "01",
      "notes": "Tỉnh Hà Tây đã sáp nhập vào Thành phố Hà Nội",
      "created_at": "2025-05-01T00:00:00.000000Z",
      "updated_at": "2025-05-01T00:00:00.000000Z",
      "old_province": {
        "code": "02",
        "name": "Hà Tây",
        "type": "Tỉnh"
      },
      "new_province": {
        "code": "01",
        "name": "Hà Nội",
        "type": "Thành phố"
      }
    }
  ]
}
GET /api/v1/merge-history/ward/{code} Yêu cầu xác thực

Lịch sử sáp nhập - Phường/Xã

Tham số:
Tên Kiểu Bắt buộc Mô tả
code (path) string Có Mã phường/xã
Phản hồi:
{
  "success": true,
  "data": [
    {
      "id": 1,
      "old_ward_code": "00001",
      "new_ward_code": "00004",
      "old_district_code": "001",
      "notes": "Phường Phúc Xá đã sáp nhập vào Phường Ba Đình",
      "created_at": "2025-05-01T00:00:00.000000Z",
      "updated_at": "2025-05-01T00:00:00.000000Z",
      "old_ward": {
        "code": "00001",
        "name": "Phúc Xá",
        "type": "Phường",
        "district": {
          "code": "001",
          "name": "Ba Đình",
          "type": "Quận"
        }
      },
      "new_ward": {
        "code": "00004",
        "name": "Ba Đình",
        "type": "Phường"
      }
    }
  ]
}

Quản lý API

Bạn có thể tạo và quản lý khóa API thông qua giao diện web.

Tạo khóa API
  1. Đăng nhập vào hệ thống
  2. Đi đến phần Khóa API
  3. Nhấp vào "Tạo khóa API"
  4. Nhập tên và giới hạn tốc độ
  5. Lưu khóa của bạn an toàn
Quản lý khóa API
Tính năng quản lý
  • Xem danh sách khóa API
  • Kích hoạt/Vô hiệu hóa khóa
  • Xóa khóa
  • Theo dõi sử dụng API

Ví dụ sử dụng


# Tỉnh/Thành phố
curl -X GET "https://tinhthanhpho.com/api/v1/provinces?keyword=hanoi&limit=10" \
     -H "Accept: application/json"

# Chuyển đổi địa chỉ đơn lẻ
curl -X POST "https://tinhthanhpho.com/api/v1/convert/address" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
           "provinceCode": "01",
           "districtCode": "001",
           "wardCode": "00001",
           "streetAddress": "15 Nguyễn Văn A"
         }'

// Tỉnh/Thành phố
fetch('https://tinhthanhpho.com/api/v1/provinces?keyword=hanoi&limit=10', {
    headers: {
        'Accept': 'application/json'
    }
})
.then(response => response.json())
.then(data => console.log(data));

// Chuyển đổi địa chỉ đơn lẻ
fetch('https://tinhthanhpho.com/api/v1/convert/address', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        provinceCode: '01',
        districtCode: '001',
        wardCode: '00001',
        streetAddress: '15 Nguyễn Văn A'
    })
})
.then(response => response.json())
.then(data => console.log(data));

<?php
// Tỉnh/Thành phố
$response = file_get_contents('https://tinhthanhpho.com/api/v1/provinces?keyword=hanoi&limit=10');
$data = json_decode($response, true);
print_r($data);

// Chuyển đổi địa chỉ đơn lẻ
$url = 'https://tinhthanhpho.com/api/v1/convert/address';
$data = [
    'provinceCode' => '01',
    'districtCode' => '001',
    'wardCode' => '00001',
    'streetAddress' => '15 Nguyễn Văn A'
];

$options = [
    'http' => [
        'header'  => "Content-Type: application/json\r\n" .
                     "Authorization: Bearer YOUR_API_KEY\r\n",
        'method'  => 'POST',
        'content' => json_encode($data)
    ]
];
$context  = stream_context_create($options);
$response = file_get_contents($url, false, $context);
$result = json_decode($response, true);
print_r($result);
?>

import requests
import json

# Tỉnh/Thành phố
response = requests.get('https://tinhthanhpho.com/api/v1/provinces', params={
    'keyword': 'hanoi',
    'limit': 10
})
data = response.json()
print(data)

# Chuyển đổi địa chỉ đơn lẻ
url = 'https://tinhthanhpho.com/api/v1/convert/address'
headers = {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
}
payload = {
    'provinceCode': '01',
    'districtCode': '001',
    'wardCode': '00001',
    'streetAddress': '15 Nguyễn Văn A'
}
response = requests.post(url, headers=headers, data=json.dumps(payload))
data = response.json()
print(data)

Phản hồi lỗi

Mã trạng thái Mô tả
400 Yêu cầu không hợp lệ - Tham số không đúng
401 Chưa xác thực - Thiếu hoặc khóa API không hợp lệ
403 Bị cấm - Truy cập bị từ chối
404 Không tìm thấy - Tài nguyên không tồn tại
422 Không thể xử lý - Xác thực thất bại
429 Quá nhiều yêu cầu - Vượt quá giới hạn tốc độ
500 Lỗi máy chủ nội bộ
Phản hồi lỗi
{
  "success": false,
  "message": "Error message here",
  "errors": {
    "provinceCode": ["The province code field is required."]
  }
}

Thông tin bổ sung

Giới hạn batch

Kích thước batch tối đa: 10000

Định dạng file kết quả: conversion_result_YYYYMMDD_HHMMSS.xlsx

Cập nhật dữ liệu

Dữ liệu đơn vị hành chính được cập nhật theo quyết định của chính phủ. Nếu bạn phát hiện bất kỳ sai sót nào, vui lòng liên hệ với chúng tôi qua trang Liên hệ.