REST APIs

Tổng quan

API REST Forcodes cung cấp các endpoint để mã hóa và giải mã tọa độ địa lý sử dụng hệ thống mã hóa địa lý Forcodes. Forcodes tạo ra các chuỗi ngắn gọn, thân thiện với người dùng có nhúng mã hành chính Việt Nam và lập chỉ mục không gian lục giác.

Base URL

Base URL cho tất cả các yêu cầu API là:

https://mapapis.openmap.vn/v1

Xác thực

Tất cả các yêu cầu API phải bao gồm một API key.

Để sử dụng API Key, bạn cần bao gồm tham số apikey trong truy vấn của các yêu cầu API. Điều này cho phép máy chủ xác định và xác thực người dùng hoặc ứng dụng đang thực hiện yêu cầu.

thông tin

Để có được API Key, bạn cần đăng ký tài khoản trên nền tảng Openmap.vn tại đây, hoặc liên hệ với chúng tôi tại [email protected].

Endpoints

1. Mã hóa tọa độ thành Forcode

Chuyển đổi tọa độ vĩ độ/kinh độ thành chuỗi Forcode.

Endpoint: POST /forcodes/encode?lat={lat}&lng={lng}&resolution={resolution}

Tham số:

• lat (bắt buộc): Vĩ độ theo độ thập phân
• lng (bắt buộc): Kinh độ theo độ thập phân
• resolution (tùy chọn): Mức độ phân giải lục giác (0-15). Mặc định: 13

Phản hồi:

{
    "forcodes": "HN4TZUZBPKRN0F",
    "lat": 20.990396,
    "lng": 105.868825,
    "resolution": 13,
    "admin_code": "HN",
    "status": "OK"
}

Các trường phản hồi:

• forcodes: Chuỗi Forcode được tạo
• lat: Vĩ độ đầu vào
• lng: Kinh độ đầu vào
• resolution: Mức độ phân giải lục giác được sử dụng
• admin_code: Mã tỉnh/thành phố Việt Nam
• status: Trạng thái thao tác

2. Giải mã Forcode thành tọa độ

Chuyển đổi chuỗi Forcode trở lại thành tọa độ vĩ độ/kinh độ.

Endpoint: POST /forcodes/decode

Tham số:

• forcodes (bắt buộc): Chuỗi Forcode cần giải mã

Phản hồi:

{
    "lat": 20.99029428701167,
    "lng": 105.86868969733383,
    "resolution": 11,
    "forcodes": "HNO4DT45BQNZ",
    "status": "OK"
}

Các trường phản hồi:

• lat: Vĩ độ đã giải mã
• lng: Kinh độ đã giải mã
• resolution: Mức độ phân giải lục giác
• forcodes: Chuỗi Forcode đầu vào
• status: Trạng thái thao tác

Phản hồi lỗi:

{
  "lat": null,
  "lng": null,
  "resolution": null,
  "forcodes": "INVALID",
  "status": "INVALID_FORCODES"
}

Mã trạng thái HTTP

• 200 OK: Yêu cầu thành công
• 400 Bad Request: Tham số đầu vào không hợp lệ
• 404 Not Found: Không tìm thấy tài nguyên

Mức độ phân giải lục giác

Forcodes sử dụng lập chỉ mục không gian lục giác với các mức độ phân giải khác nhau:

Mức độ phân giải	Chiều dài cạnh lục giác	Trường hợp sử dụng điển hình
0	~1,107 km	Khu vực lục địa
1	~418 km	Vùng lớn
2	~158 km	Vùng trung bình
3	~59 km	Vùng nhỏ
4	~22 km	Thành phố lớn
5	~8.5 km	Quận huyện thành phố
6	~3.2 km	Khu phố
7	~1.2 km	Tòa nhà lớn
8	~461 m	Khu phố
9	~174 m	Tòa nhà lớn
10	~66 m	Nhóm tòa nhà
11	~25 m	Tòa nhà riêng lẻ
12	~9.4 m	Phòng lớn
13	~3.5 m	Phòng nhỏ
14	~1.3 m	Vị trí chính xác
15	~0.5 m	Vị trí rất chính xác

Mã hành chính

Forcodes nhúng mã tỉnh/thành phố Việt Nam dựa trên cấu trúc hành chính năm 2025:

Mã	Tên tỉnh/thành mới	Các tỉnh/thành hợp nhất
TQ	Tuyên Quang	Hà Giang, Tuyên Quang
CB	Cao Bằng	Cao Bằng
LCU	Lai Châu	Lai Châu
LCI	Lào Cai	Lào Cai, Yên Bái
TN	Thái Nguyên	Bắc Kạn, Thái Nguyên
DB	Điện Biên	Điện Biên
LS	Lạng Sơn	Lạng Sơn
SL	Sơn La	Sơn La
PT	Phú Thọ	Hòa Bình, Vĩnh Phúc, Phú Thọ
BN	Bắc Ninh	Bắc Giang, Bắc Ninh
QNH	Quảng Ninh	Quảng Ninh
HN	Hà Nội	Hà Nội
HP	Hải Phòng	Hải Dương, Hải Phòng
HY	Hưng Yên	Thái Bình, Hưng Yên
NB	Ninh Bình	Hà Nam, Ninh Bình, Nam Định
TH	Thanh Hóa	Thanh Hóa
NA	Nghệ An	Nghệ An
HT	Hà Tĩnh	Hà Tĩnh
QT	Quảng Trị	Quảng Bình, Quảng Trị
HUE	Huế	Huế
DNG	Đà Nẵng	Quảng Nam, Đà Nẵng
QNG	Quảng Ngãi	Quảng Ngãi, Kon Tum
GL	Gia Lai	Gia Lai, Bình Định
DLK	Đắk Lắk	Phú Yên, Đắk Lắk
KH	Khánh Hòa	Khánh Hòa, Ninh Thuận
LD	Lâm Đồng	Đắk Nông, Lâm Đồng, Bình Thuận
DN	Đồng Nai	Bình Phước, Đồng Nai
TNH	Tây Ninh	Long An, Tây Ninh
HCM	TP. Hồ Chí Minh	Bình Dương, TP.HCM, Bà Rịa - Vũng Tàu
DT	Đồng Tháp	Tiền Giang, Đồng Tháp
AG	An Giang	Kiên Giang, An Giang
VL	Vĩnh Long	Bến Tre, Vĩnh Long, Trà Vinh
CT	Cần Thơ	Sóc Trăng, Hậu Giang, Cần Thơ
CM	Cà Mau	Bạc Liêu, Cà Mau