# Place v4

Source: https://maps.vietmap.vn/docs/vi/map-api/place-v4/

## Place phiên bản dùng cho tìm kiếm địa chỉ sau sáp nhập

Place v4 trả về chi tiết một địa điểm (số nhà, đường, phường, tỉnh, lat/lng) theo `ref_id` lấy từ [Autocomplete v4](https://maps.vietmap.vn/docs/vi/map-api/autocomplete-version/autocomplete-v4/) hoặc [Geocode v4](https://maps.vietmap.vn/docs/vi/map-api/geocode-version/geocode-v4/). Đây là bước lấy tọa độ — hai API kia không trả lat/lng. Mỗi lượt gọi tính một transaction.

### Playground
!!! tip "Thử ngay trên Playground"
    Place v4 chạy sau khi chọn một gợi ý: gõ địa chỉ vào Autocomplete, chọn kết quả, Playground gọi Place v4 bằng `ref_id` để lấy toạ độ. **[Mở Playground](https://tools.vietmap.vn/playground/autocomplete)**

!!! tip "Tích hợp AI Agent :sparkles: MỚI"
    Tải bộ tài liệu đã tối ưu cho AI agent: **<a href="/docs/assets/agents/search-geocoding.txt" download="search-geocoding.txt">Search & Geocoding Agent Doc</a>** · Schema máy đọc: **[OpenAPI 3.1](/docs/openapi.json)**

Hoặc dùng thử bằng [Postman](https://app.getpostman.com/run-collection/10912981-433d17b2-76d7-416e-beb2-468b9682b7a7?action=collection%2Ffork).

### URL

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

### Method
GET

### Tham số
|Tham số|Kiểu|Bắt buộc|Mô tả|Ví dụ|
|--- |--- |--- |--- |--- |
|apikey|string|có|API key VIETMAP cấp cho tài khoản của bạn. Đăng ký tại [đây](https://maps.vietmap.vn/console-v2/register)||
|refid|string|có|Mã `refid` lấy nguyên xi từ kết quả Autocomplete hoặc Geocode. Giữ cả tiền tố (`auto:`, `geocode:`) — tiền tố quyết định định dạng phản hồi|auto:RAkPcicmZ3d-NQ...|

### Ví dụ

[:material-play-circle: Thử luồng Autocomplete → Place trên Playground](https://tools.vietmap.vn/playground/autocomplete){ .md-button .md-button--primary }


**Đầu vào:**
``` 
 https://maps.vietmap.vn/api/place/v4?apikey={your-apikey}&refid=auto:RAkPcicmZ3d-NQhac2kADHYlbFAkBiEeAQAkCV0EXwdF_KakgoWOrg0FFWZfh4jFXA1kXfbZFlNRGFUYCAJXAF8BUQBVCAZUC18EA1VMAwUYXwJQBBQFBQVTHVFacANBQlU
```

**Phản hồi:**

**Lưu ý:** Cấu trúc phản hồi tự động khớp với **định dạng của API đã sinh ra refid**. Nếu refid lấy từ phản hồi định dạng mới thì phản hồi cũng theo định dạng mới, và ngược lại.
```json
{
    "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
}
```


### Mô tả phản hồi
| Trường  | Kiểu   | Mô tả                                                   |
| ---------- | ------ | ------------------------------------------------------------- |
| display    | string | Tên hiển thị chứa đầy đủ thông tin của địa chỉ   |
| name       | string | Tên POI. Rỗng nếu kết quả là địa chỉ số nhà, không phải POI |
| hs_num     | string | Số nhà hoặc số tòa nhà                                |
| street     | string | Tên đường                                             |
| address    | string | Số nhà + tên đường (`hs_num` + `street`)              |
| city_id    | int    | Mã định danh của tỉnh/thành phố                                 |
| city       | string | Tên tỉnh/thành phố                                 |
| district_id| int    | Mã định danh của quận/huyện. Hiện luôn là `0` với định dạng hiển thị mới. Với định dạng cũ thì đây là mã quận/huyện. |
| district   | string | Tên quận/huyện. Hiện luôn là chuỗi rỗng với định dạng hiển thị mới. Với định dạng cũ thì đây là tên quận/huyện. |
| ward_id    | int    | Mã định danh của phường/xã                                 |
| ward       | string | Tên phường/xã                                 |
| lat        | number | Vĩ độ của địa chỉ                             |
| lng        | number | Kinh độ của địa chỉ                            |

### Mã lỗi

| HTTP | Ý nghĩa | Thân phản hồi |
| --- | --- | --- |
| `200` | Thành công | JSON như ví dụ ở trên |
| `401` | API key sai hoặc không tồn tại | Rỗng |
| `423` | Hết hạn mức, hoặc API này chưa được mở cho key | Văn bản, ví dụ `Your request is limited` |

Gặp `423` thì xem hạn mức còn lại ở [Theo dõi mức dùng](https://maps.vietmap.vn/docs/vi/map-api/console/monitor-api-key-usage/) và kiểm tra API đã được bật cho key ở [Quản lý API Key](https://maps.vietmap.vn/docs/vi/map-api/console/manage-api-key/).

!!! tip "Gọi thử với dữ liệu của bạn"
    Nhập địa chỉ, toạ độ hoặc tham số của bạn và xem kết quả ngay trên bản đồ, kèm lệnh cURL để sao chép: **[Mở Place v4 trên Playground](https://tools.vietmap.vn/playground/autocomplete)**