REST APIs

Overview

Forcodes REST API provides endpoints for encoding and decoding geographic coordinates using the Forcodes geocoding system. Forcodes generates compact, human-friendly strings that embed Vietnamese administrative codes and hexagonal spatial indexing.

Base URL

The base URL for all API requests is:

https://mapapis.openmap.vn/v1

Authentication

All API requests must include an API key.

To use the API Key, you need to include apikey parameter in the query of your API requests. This allows the server to identify and authenticate the user or application making the request.

info

To get an API Key, you need to sign up for an account on the Openmap.vn platform here, or reach us at [email protected].

Endpoints

1. Encode Coordinates to Forcode

Convert latitude/longitude coordinates to a Forcode string.

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

Parameters:

• lat (required): Latitude in decimal degrees
• lng (required): Longitude in decimal degrees
• resolution (optional): Hexagon resolution level (0-15). Default: 13

Response:

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

Response Fields:

• forcodes: Generated Forcode string
• lat: Input latitude
• lng: Input longitude
• resolution: Hexagon resolution used
• admin_code: Vietnamese province/city code
• status: Operation status

2. Decode Forcode to Coordinates

Convert a Forcode string back to latitude/longitude coordinates.

Endpoint: POST /forcodes/decode

Parameters:

• forcodes (required): Forcode string to decode

Response:

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

Response Fields:

• lat: Decoded latitude
• lng: Decoded longitude
• resolution: Hexagon resolution level
• forcodes: Input Forcode string
• status: Operation status

Error Response:

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

HTTP Status Codes

• 200 OK: Request successful
• 400 Bad Request: Invalid input parameters
• 404 Not Found: Resource not found

Hexagon Resolution Levels

Forcodes uses hexagonal spatial indexing with different resolution levels:

Resolution	Hexagon Edge Length	Typical Use Case
0	~1,107 km	Continental areas
1	~418 km	Large regions
2	~158 km	Medium regions
3	~59 km	Small regions
4	~22 km	Large cities
5	~8.5 km	City districts
6	~3.2 km	Neighborhoods
7	~1.2 km	Large buildings
8	~461 m	City blocks
9	~174 m	Large buildings
10	~66 m	Building groups
11	~25 m	Individual buildings
12	~9.4 m	Large rooms
13	~3.5 m	Small rooms
14	~1.3 m	Precise locations
15	~0.5 m	Very precise locations

Administrative Codes

Forcodes embed Vietnamese province/city codes based on the 2025 administrative structure:

Code	New Province/City Name	Merged Provinces/Cities
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