Place - v4

Place version for merged location search¶

Place v4 returns the address components and lat/lng for a ref_id obtained from Autocomplete v4 or Geocode v4. Each call counts as one transaction.

Playground¶

Try it on the Playground

Place v4 runs after a suggestion is picked: type an address into Autocomplete, pick a result, and the Playground calls Place v4 with its ref_id to get the coordinates. Open the Playground

AI Agent Integration NEW

Download the optimized doc for AI agent integration: Search & Geocoding Agent Doc · Machine-readable schema: OpenAPI 3.1

Or try it with Postman.

URL¶

https://maps.vietmap.vn/api/place/v4?apikey={your-apikey}&refid={refid}

Method¶

GET

Parameter¶

Parameter	Type	Required	Description	Example
apikey	string	yes	API key provided by VIETMAP for your account. Register here
refid	string	yes	The `ref_id` value from an Autocomplete v4 or Geocode v4 result, passed verbatim including its `auto:` / `geocode:` prefix	auto:RAkPcicmZ3d-NQhac2kADHYlbFAkBiEeAQAkCV0EXwdF_KakgoWOrg0FFWZfh4jFXA1kXfbZFlNRGFUYCAJXAF8BUQBVCAZUC18EA1VMAwUYXwJQBBQFBQVTHVFacANBQlU

Example¶

Try the Autocomplete → Place flow on the Playground

Input:

 https://maps.vietmap.vn/api/place/v4?apikey={your-apikey}&refid=auto:RAkPcicmZ3d-NQhac2kADHYlbFAkBiEeAQAkCV0EXwdF_KakgoWOrg0FFWZfh4jFXA1kXfbZFlNRGFUYCAJXAF8BUQBVCAZUC18EA1VMAwUYXwJQBBQFBQVTHVFacANBQlU

Response body:

Note: The response uses the same administrative format as the search result the refid came from. A refid from a new-format (2-level) result returns district_id: 0 and district: ""; a refid from an old-format (3-level) result returns all three levels.

{
    "display": "197 Đường Trần Phú,Phường Chợ Quán,Thành Phố Hồ Chí Minh",
    "name": "",
    "hs_num": "197",
    "street": "Đường Trần Phú",
    "address": "197 Đường Trần Phú",
    "city_id": 12,
    "city": "Thành Phố Hồ Chí Minh",
    "district_id": 0,
    "district": "",
    "ward_id": 18700,
    "ward": "Phường Chợ Quán",
    "lat": 10.759222947000069,
    "lng": 106.67590269100003
}

Response description¶

Parameter	Type	Description
display	string	Display name containing detailed information of the address
name	string	POI name. Empty string when the result is a plain street address.
hs_num	string	House number or building number
street	string	Street name, with its prefix (e.g. `Đường Trần Phú`)
address	string	House number and street (`hs_num` + `street`)
city_id	int	Unique identifier for the city
city	string	Name of the city
district_id	int	Unique identifier for the district. Currently, it is always `0` for the new display format. For the old display format, it will be the district ID.
district	string	Name of the district. Currently, it is always an empty string for the new display format. For the old display format, it will be the district name.
ward_id	int	Unique identifier for the ward
ward	string	Name of the ward
lat	number	Latitude coordinate of the address
lng	number	Longitude coordinate of the address

Error codes¶

HTTP	Meaning	Response body
`200`	Success	JSON as in the example above
`401`	Wrong or unknown API key	Empty
`423`	Quota used up, or this API is not enabled for the key	Plain text, e.g. `Your request is limited`

On 423, check the remaining quota in Monitor API key usage and whether the API is enabled for the key in Manage API keys.

Try it with your own data

Enter your own addresses, coordinates or parameters and see the result on a map, with a cURL command to copy: Open Place v4 on the Playground