Forcodes REST API Documentation

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:

Major Cities (2-3 characters):

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

Provinces (2 characters):

• CB - Cao Bằng
• LS - Lạng Sơn
• QN - Quảng Ninh
• TH - Thanh Hóa
• NA - Nghệ An
• And more...