Tài liệu API REST Forcodes

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:

Thành phố lớn (2-3 ký tự):

• HN - Hà Nội
• HCM - Hồ Chí Minh
• DNG - Đà Nẵng
• HP - Hải Phòng
• CT - Cần Thơ

Tỉnh (2 ký tự):

• CB - Cao Bằng
• LS - Lạng Sơn
• QN - Quảng Ninh
• TH - Thanh Hóa
• NA - Nghệ An
• Và nhiều hơn nữa...