Geocode

Geocode version 3.0

Updating Geocode 3.0 API is a powerful tool for developers to integrate location search functionality into their applications with optimized performance. Additionally, this latest version utilizes intelligent search algorithms and methods to provide accurate and speedy search results for users.

Important

We suggest to use Geocode v4 API for new integration. Geocode v3 API will be deprecated in the future.

Playground

You can test the Geocode API in our VietMap Geocode API Playground.

URL

https://maps.vietmap.vn/api/search/v3?apikey={your-apikey}&text={text}&focus={lat,long}

Method

GET

Parameter

Parameter	Type	Required	Description	Example
apikey	string	yes	API key provided by VIETMAP for your account. Register here
text	string	yes	User desired input	Công Ty Cổ Phần Ứng Dụng Bản Đồ Việt
focus	string	no	GPS cordinates	10.759540242000032, 106.67660114000005
layers	string	no	Represent for certain type of data such as POI,ADDRESS,VILLAGE,WARD,DIST,CITY,STREET	POI
circle_center	number	no	The central coordinate(lat/lng) position of the area to be searched	10.758867051669924,106.6755666901197
circle_radius	number	no	The radius of the search area (in meters)	200
cats	string	no	Provide full list of POI categories. Click here POI Categories	1002-1
cityId	number	no	Every city has a unique ID, which is used to filter search results	12
distId	number	no	Every district has a unique ID, which is used to filter search results	1292
wardId	number	no	Every ward has a unique ID, which is used to filter search results	984332

Example

Input

https://maps.vietmap.vn/api/search/v3?apikey={your-apikey}&focus=10.75887508,106.67538868&text=Công Ty Cổ Phần Ứng Dụng Bản Đồ Việt,HCM

Respone

If you need detailed information about the place, please use the Vietmap Place API

[
    {
        "ref_id": "vm:POI:7057AB748BFD685B",
        "distance": 0.069199492010845,
        "address": "197 Đường Trần Phú,Phường 4,Quận 5,Thành Phố Hồ Chí Minh",
        "name": "Công Ty Cổ Phần Ứng Dụng Bản Đồ Việt",
        "display": "Công Ty Cổ Phần Ứng Dụng Bản Đồ Việt 197 Đường Trần Phú,Phường 4,Quận 5,Thành Phố Hồ Chí Minh",
        "boundaries": [
            {
                "type": 2,
                "id": 656652,
                "name": "4",
                "prefix": "Phường",
                "full_name": "Phường 4"
            },
            {
                "type": 1,
                "id": 1292,
                "name": "5",
                "prefix": "Quận",
                "full_name": "Quận 5"
            },
            {
                "type": 0,
                "id": 12,
                "name": "Hồ Chí Minh",
                "prefix": "Thành Phố",
                "full_name": "Thành Phố Hồ Chí Minh"
            }
        ],
        "categories": [
            "6001"
        ],
        "entry_points": []
    },
    {
        "ref_id": "vm:POI:37B6A20D8D9190CD",
        "distance": 0.06445065459645513,
        "address": "199 Đường Trần Phú,Phường 4,Quận 5,Thành Phố Hồ Chí Minh",
        "name": "Công Ty Cổ Phần Ứng Dụng Bản Đồ Việt Trung Tâm Bảo Hành",
        "display": "Công Ty Cổ Phần Ứng Dụng Bản Đồ Việt Trung Tâm Bảo Hành 199 Đường Trần Phú,Phường 4,Quận 5,Thành Phố Hồ Chí Minh",
        "boundaries": [
            {
                "type": 2,
                "id": 656652,
                "name": "4",
                "prefix": "Phường",
                "full_name": "Phường 4"
            },
            {
                "type": 1,
                "id": 1292,
                "name": "5",
                "prefix": "Quận",
                "full_name": "Quận 5"
            },
            {
                "type": 0,
                "id": 12,
                "name": "Hồ Chí Minh",
                "prefix": "Thành Phố",
                "full_name": "Thành Phố Hồ Chí Minh"
            }
        ],
        "categories": [
            "6001"
        ],
        "entry_points": []
    }
]

Response description

Geocode API will respond to a list that contains up to 10 places.

Parameter	Type	Description
ref_id	string	Reference ID for the Point of Interest (POI), using for get detail info from Vietmap Place API
address	string	Full address including street, ward, district, and city
name	string	Name of the Point of Interest (POI)
display	string	Display name containing detailed information of the POI address
boundaries	array	Array containing boundary information (ward, district, city)
categories	array	Array containing categories associated with the POI
entry_points	array	Array containing entry points associated with the POI. This value will available for some special address, like airport, hotel,...

For the boundaries array:

Sub-Parameter	Type	Description
type	integer	Administrative level (0 = province/city, 1 = district, 2 = ward)
id	integer	Unique identifier of the administrative unit
name	string	Name of the administrative unit, without its prefix
prefix	string	Administrative level prefix. Example: Phường, Quận, Thành Phố
full_name	string	Full name including the prefix. Example: Phường 9

For the entry_points array:

Sub-Parameter	Type	Description
ref_id	string	Reference ID for the Point of Interest (POI)
name	string	Name of the Point of Interest (POI)

If you need detailed information about the entrypoint, please use the Vietmap Place API