Skip to content

Search - v4

geocode

Updating Geocode 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.

URL

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

Method

GET

Migrate from v3 → v4 (short)

  • Endpoint changes from /api/search/v3 to /api/search/v4; add display_type to control output (1=new, 2=old, 3=auto, ⅚=both).
  • Responses can use a new 2-level admin model (ward → province); v4 may include data_old/data_new to carry the alternate format if you choose display_type=5 or 6.
  • For v3-compatible payloads, call v4 with display_type=2; for side-by-side comparison during migration, use display_type=5 or 6.
  • V4 api uses different ref_id, please refer to Place v4 API for more detail, which replaces the old Place API.

See the previous version docs: Geocode v3.

Parameter

Parameter Type Required Description Example
apikey string yes API provided by VIETMAP for customer's account.
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
display_type number no Result display type. Follow Display Type Options for more detail 1
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

Display type options

Value Label Description
1 Response New Format New merged administrative format (2 levels: ward, city).
2 Response Old Format Old administrative format (3 levels: ward, district, city).
3 Response as Input Format API will detect user input and response model like input format.
5 Response both New & Old Returns new-format object and indicates old (legacy) boundaries.
6 Response both Old & New Returns old-format object and indicates updated (new) boundaries.

Example

Input 

https://maps.vietmap.vn/api/search/v4?apikey={your-apikey}&focus=10.75887508,106.67538868&display_type=1&text=197 Trần Phú, phường 4, quận 5, thành phố Hồ Chí Minh

Response

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

[
    {
        "ref_id": "geocode:RAkPcicmZ3d-NQhac2kADHYlbFAkBiEeAQAkCV0EXwdFbESDiMNbEzMK9ogWVwJMBRgNBwdRFFZWBlIdAQZcCVcFUB5TDwNbAlYDClJSBQIdVQk2QFhR",
        "distance": 0.06911172534949989,
        "address": "Phường 4,Quận 5,Thành Phố Hồ Chí Minh",
        "name": "197 Trần Phú",
        "display": "197 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": [],
        "data_new": {
            "ref_id": "geocode:RAkPcicmZ3d-NQhac2kADHYlbFAkBiEeAQAkCV0EXwdFbESDiMNbEzMK9ogWVwJMBRgNBwdRFFZWBlIdAQZcCVcFUB5TDwNbAlYDClJSBQIdVQkkU0FHUA",
            "distance": 0.06911172534949989,
            "address": "Phường Chợ Quán,Thành Phố Hồ Chí Minh",
            "name": "197 Trần Phú",
            "display": "197 Trần Phú Phường Chợ Quán,Thành Phố Hồ Chí Minh",
            "boundaries": [
                {
                    "type": 2,
                    "id": 18700,
                    "name": "Chợ Quán",
                    "prefix": "Phường",
                    "full_name": "Phường Chợ Quán"
                },
                {
                    "type": 0,
                    "id": 12,
                    "name": "Hồ Chí Minh",
                    "prefix": "Thành Phố",
                    "full_name": "Thành Phố Hồ Chí Minh"
                }
            ],
            "categories": [],
            "entry_points": [],
            "data_new": null,
            "data_old": null
        },
        "data_old": null
    }
]

[
    {
        "ref_id": "geocode:RAkPcicmZ3d-NQhac2kADHYlbFAkBiEeAQAkCV0EXwdFbESDiMNbEzMK9ogWVwJMBRgNBwdRFFZWBlIdAQZcCVcFUB5TDwNbAlYDClJSBQIdVQkkU0FHUA",
        "distance": 0.06911172534949989,
        "address": "Phường Chợ Quán,Thành Phố Hồ Chí Minh",
        "name": "197 Trần Phú",
        "display": "197 Trần Phú Phường Chợ Quán,Thành Phố Hồ Chí Minh",
        "boundaries": [
            {
                "type": 2,
                "id": 18700,
                "name": "Chợ Quán",
                "prefix": "Phường",
                "full_name": "Phường Chợ Quán"
            },
            {
                "type": 0,
                "id": 12,
                "name": "Hồ Chí Minh",
                "prefix": "Thành Phố",
                "full_name": "Thành Phố Hồ Chí Minh"
            }
        ],
        "categories": [],
        "entry_points": [],
        "data_new": null,
        "data_old": {
            "ref_id": "geocode:RAkPcicmZ3d-NQhac2kADHYlbFAkBiEeAQAkCV0EXwdFbESDiMNbEzMK9ogWVwJMBRgNBwdRFFZWBlIdAQZcCVcFUB5TDwNbAlYDClJSBQIdVQk2QFhR",
            "distance": 0.06911172534949989,
            "address": "Phường 4,Quận 5,Thành Phố Hồ Chí Minh",
            "name": "197 Trần Phú",
            "display": "197 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": [],
            "data_new": null,
            "data_old": null
        }
    }
]

[
    {
        "ref_id": "geocode:RAkPcicmZ3d-NQhac2kADHYlbFAkBiEeAQAkCV0EXwdFbESDiMNbEzMK9ogWVwJMBRgNBwdRFFZWBlIdAQZcCVcFUB5TDwNbAlYDClJSBQIdVQk2QFhR",
        "distance": 0.06911172534949989,
        "address": "Phường 4,Quận 5,Thành Phố Hồ Chí Minh",
        "name": "197 Trần Phú",
        "display": "197 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": [],
        "data_new": null,
        "data_old": null
    }
]

[
    {
        "ref_id": "geocode:RAkPcicmZ3d-NQhac2kADHYlbFAkBiEeAQAkCV0EXwdFbESDiMNbEzMK9ogWVwJMBRgNBwdRFFZWBlIdAQZcCVcFUB5TDwNbAlYDClJSBQIdVQk2QFhR",
        "distance": 0.06911172534949989,
        "address": "Phường 4,Quận 5,Thành Phố Hồ Chí Minh",
        "name": "197 Trần Phú",
        "display": "197 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": [],
        "data_new": null,
        "data_old": null
    }
]

[
    {
        "ref_id": "geocode:RAkPcicmZ3d-NQhac2kADHYlbFAkBiEeAQAkCV0EXwdFbESDiMNbEzMK9ogWVwJMBRgNBwdRFFZWBlIdAQZcCVcFUB5TDwNbAlYDClJSBQIdVQkkU0FHUA",
        "distance": 0.06911172534949989,
        "address": "Phường Chợ Quán,Thành Phố Hồ Chí Minh",
        "name": "197 Trần Phú",
        "display": "197 Trần Phú Phường Chợ Quán,Thành Phố Hồ Chí Minh",
        "boundaries": [
            {
                "type": 2,
                "id": 18700,
                "name": "Chợ Quán",
                "prefix": "Phường",
                "full_name": "Phường Chợ Quán"
            },
            {
                "type": 0,
                "id": 12,
                "name": "Hồ Chí Minh",
                "prefix": "Thành Phố",
                "full_name": "Thành Phố Hồ Chí Minh"
            }
        ],
        "categories": [],
        "entry_points": [],
        "data_new": null,
        "data_old": null
    }
]

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). May include a prefix reflecting display type. Use Vietmap Place API to get detail info.
distance number Distance value, in kilometer
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). For the new display format, the boundaries will be returned as an array of objects, each containing ward and city.
categories array Array containing categories associated with the POI (see POI category codes in the parameter section: “cats”).
entry_points array Array containing entry points associated with the POI. This value will available for some special address, like airport, hotel,...
data_old object or null Old-format variant of this result (when applicable to the chosen display type), otherwise null.
data_new object or null New-format variant of this result (when applicable to the chosen display type), otherwise null.

For the boundaries array:

Sub-Parameter Type Description
type integer Type of boundary (0 for city, 1 for district, 2 for ward)
id integer 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)

For the data_old and data_new objects:

Sub-Parameter Type Description
ref_id string Reference ID for the result variant
distance number Distance value, in kilometer
address string Full address
name string POI name
display string Display text containing detailed address info
boundaries array Same schema as the boundaries array above
categories array POI category codes
entry_points array Entry points for the POI (if available)

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

facebook
Tổng đài hỗ trợ
089.616.4567 facebook Chat Facebook zalo Chat Zalo