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¶
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:
// 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
Related APIs¶
- Autocomplete v4 — where the
ref_idusually comes from. - Geocode v4 — also returns a
ref_idfor each result. - Route v4 — directions to the place from its
latandlng.