Skip to content

Place - v4

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
curl -G 'https://maps.vietmap.vn/api/place/v4' \
  --data-urlencode 'apikey=YOUR_API_KEY' \
  --data-urlencode 'refid=auto:RAkPcicmZ3d-NQhac2kADHYlbFAkBiEeAQAkCV0EXwdF_KakgoWOrg0FFWZfh4jFXA1kXfbZFlNRGFUYCAJXAF8BUQBVCAZUC18EA1VMAwUYXwJQBBQFBQVTHVFacANBQlU'
// Node.js 18+. Call from your server so the API key stays private.
const params = new URLSearchParams({
  apikey: "YOUR_API_KEY",
  refid: "auto:RAkPcicmZ3d-NQhac2kADHYlbFAkBiEeAQAkCV0EXwdF_KakgoWOrg0FFWZfh4jFXA1kXfbZFlNRGFUYCAJXAF8BUQBVCAZUC18EA1VMAwUYXwJQBBQFBQVTHVFacANBQlU",
});
const res = await fetch(`https://maps.vietmap.vn/api/place/v4?${params}`);
const data = await res.json();
console.log(data);
import requests

params = {
    "apikey": "YOUR_API_KEY",
    "refid": "auto:RAkPcicmZ3d-NQhac2kADHYlbFAkBiEeAQAkCV0EXwdF_KakgoWOrg0FFWZfh4jFXA1kXfbZFlNRGFUYCAJXAF8BUQBVCAZUC18EA1VMAwUYXwJQBBQFBQVTHVFacANBQlU",
}
resp = requests.get("https://maps.vietmap.vn/api/place/v4", params=params, timeout=10)
resp.raise_for_status()
print(resp.json())
Integrate the VIETMAP Place v4 API into my project.

Sample request (from the example in the docs):
GET https://maps.vietmap.vn/api/place/v4
  refid=auto:RAkPcicmZ3d-NQhac2kADHYlbFAkBiEeAQAkCV0EXwdF_KakgoWOrg0FFWZfh4jFXA1kXfbZFlNRGFUYCAJXAF8BUQBVCAZUC18EA1VMAwUYXwJQBBQFBQVTHVFacANBQlU

Requirements:
- Call the API from the server. Read the API key from the VIETMAP_API_KEY environment variable and send it as `apikey`; never hard-code it.
- Write one function that sends this request, checks the HTTP status and returns the parsed response.
- Read the docs below first. Use only parameters and response fields documented there.

Docs:
- https://maps.vietmap.vn/docs/map-api/place-v4/index.txt
- https://maps.vietmap.vn/docs/assets/agents/search-geocoding.txt

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. All codes and how to handle them: Error codes.

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

  • Autocomplete v4 — where the ref_id usually comes from.
  • Geocode v4 — also returns a ref_id for each result.
  • Route v4 — directions to the place from its lat and lng.
Hotline
Tổng đài hỗ trợ
089.616.4567
Messenger Chat Facebook zalo Chat Zalo