Autocomplete

Updating Autocomplete 3.0 API is a valuable resources that allows developers to integrate autocomplete functionality into their applications. This API is designed to help users quickly find and select items from a large set of options by suggesting potential matches as they type.

The API is built on a machine learning model that analyzes user input and suggests potential matches based on the context of the search. This model can be updated in real-time, allowing the API to continuously improve its suggestions as more data becomes available.

Important

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

Playground

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

URL

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

Method

GET

Parameters

Parameter	Type	Required	Description	Example
apikey	string	yes	API provided by VIETMAP for customer's account
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
circle_center	string	no	The central coordinate (lat,lng) position of the area to be searched	10.758867,106.6755666
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
focus	number	no	Specify the center of the search context expressed as coordinates.	10.758867,106.675566
text	string	yes	User desired input	Cong ty
layers	string	no	Represent for certain type of data such as POI,ADDRESS,VILLAGE,WARD,DIST,CITY,STREET	POI

Example

Input

https://maps.vietmap.vn/api/autocomplete/v3?apikey={your-apikey}&text=197 tran phu&focus=10.75887508,106.67538868

Response

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

[
    {
        "ref_id": "vm:ADDRESS:8AD49CFA2E0C300A",
        "distance": 0.06911172534949989,
        "address": "Phường 4, Quận 5, Thành Phố Hồ Chí Minh",
        "name": "197 Đường Trần Phú",
        "display": "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": [],
        "entry_points": []
    },
    {
        "ref_id": "vm:ADDRESS:A4DFA42575DEA254",
        "distance": 23.712993485603697,
        "address": "Phường Chánh Nghĩa, Thành Phố Thủ Dầu Một, Tỉnh Bình Dương",
        "name": "197 Đường Trần Phú",
        "display": "197 Đường Trần Phú Phường Chánh Nghĩa, Thành Phố Thủ Dầu Một, Tỉnh Bình Dương",
        "boundaries": [
            {
                "type": 2,
                "id": 327959,
                "name": "Chánh Nghĩa",
                "prefix": "Phường",
                "full_name": "Phường Chánh Nghĩa"
            },
            {
                "type": 1,
                "id": 279,
                "name": "Thủ Dầu Một",
                "prefix": "Thành Phố",
                "full_name": "Thành Phố Thủ Dầu Một"
            },
            {
                "type": 0,
                "id": 23,
                "name": "Bình Dương",
                "prefix": "Tỉnh",
                "full_name": "Tỉnh Bình Dương"
            }
        ],
        "categories": [],
        "entry_points": []
    }
]

Response description

Autocomplete 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 for the POI. This value will available for some special address, like airport, hotel,...

For the boundaries array:

Sub-Parameter	Type	Description
type	int	Type of boundary (0 for city, 1 for district, 2 for ward)
id	int	Unique identifier for the boundary
name	string	Name of the boundary
prefix	string	Prefix of the boundary (e.g., "Phường" for ward)
full_name	string	Full name of the boundary (e.g., "Phường 9" for ward)

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