Geocode - v4

Geocode version for merged location search¶

geocode

Geocode v4 takes a full address string (e.g. 197 Trần Phú, phường 4, quận 5, TP.HCM) and returns up to 10 matching places, each with a ref_id, a normalized address and its administrative units. The response has no coordinates — pass the ref_id to Place v4 to get lat/lng.

Important

Geocode v4 expects a full address string; partial input may return an empty array. For search-as-you-type, use Autocomplete v4.

Playground¶

Try it in the Playground

Call Geocode v4 with real data, no code required: Open Playground

AI Agent Integration NEW

Download the optimized doc for AI agent integration (Geocode + Reverse): Geocode & Reverse Geocoding Agent Doc

Or try it in Postman.

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¶

Endpoint changes from /api/search/v3 to /api/search/v4; add display_type to control output (1=new, 2=old, 3=auto, 5 or 6=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.
V4 api uses different ref_id, please refer to Place v4 API for more detail, which replaces the old Place API.
We suggest to use display_type=5 for better migration experience.

See the previous version docs: Geocode v3.

Parameter¶

Parameter	Type	Required	Description	Example
apikey	string	yes	API key provided by VIETMAP for your account. Register here
text	string	yes	Full address string to geocode, e.g. `197 Trần Phú, phường 4, quận 5, TP.HCM`. Not for partial input — see the warning above	197 Trần Phú, phường 4, quận 5, thành phố Hồ Chí Minh
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	Filter results to one province/city. Look the ID up in the administrative address dataset	12
distId	number	no	Filter results to one district. Look the ID up in the administrative address dataset	1292
wardId	number	no	Filter results to one ward. Look the ID up in the administrative address dataset	984332
admin_new	boolean	no	Flag to indicate use of new or old administrative boundaries. Only work with filter by admin id (city, district, ward). Example, if it receive `false`, while filter HoChiMinh City by Id, it only response data in old geometries, does not include BinhDuong and VungTau	false

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=6&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

Response both Old & New
display_type=6Response both New & Old
display_type=5Response as Input Format
display_type=3Response Old Format
display_type=2Response New Format
display_type=1

[
    {
        "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	Administrative units of the address, from the smallest level up. In the new display format each entry is a ward or a province.
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	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)

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