# Geocode v4 Source: https://maps.vietmap.vn/docs/vi/map-api/geocode-version/geocode-v4/ ## Geocode cho tìm kiếm địa chỉ sau sáp nhập ![geocode](https://maps.vietmap.vn/docs/assets/geocode.webp) Geocode API nhận một chuỗi địa chỉ đầy đủ (ví dụ `197 Trần Phú, phường 4, quận 5, TP.HCM`) và trả về tối đa 10 địa điểm khớp, mỗi địa điểm kèm `ref_id`, địa chỉ chuẩn hóa và các đơn vị hành chính. Phản hồi không có tọa độ — truyền `ref_id` sang [Place v4](https://maps.vietmap.vn/docs/vi/map-api/place-v4/) để lấy lat/lng. !!! warning "Quan trọng" Geocode v4 nhận chuỗi địa chỉ đầy đủ; gửi chuỗi gõ dở có thể nhận mảng rỗng. Cần gợi ý theo từng phím gõ thì dùng [Autocomplete v4](https://maps.vietmap.vn/docs/vi/map-api/autocomplete-version/autocomplete-v4/). ### Playground !!! tip "Thử ngay trên Playground" Gọi thử Geocode v4 với dữ liệu thật, không cần viết code: **[Mở Playground](https://tools.vietmap.vn/playground/geocode)** !!! tip "Tích hợp AI Agent :sparkles: MỚI" Tải bộ tài liệu đã tối ưu cho AI agent (Geocode + Reverse): **Geocode & Reverse Geocoding Agent Doc** · 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 ```swift https://maps.vietmap.vn/api/search/v4?apikey={your-apikey}&text={text}&focus={lat,long}&display_type={display_type} ``` ### Method GET ### Chuyển từ v3 lên v4 - Endpoint đổi từ `/api/search/v3` sang `/api/search/v4`; thêm `display_type` để chọn định dạng trả về (1=mới, 2=cũ, 3=tự động, 5 hoặc 6=cả hai). - Phản hồi có thể dùng mô hình hành chính 2 cấp mới (phường/xã → tỉnh/thành); nếu chọn `display_type=5` hoặc `6`, v4 trả thêm `data_old`/`data_new` chứa định dạng còn lại. - Muốn giữ payload tương thích v3 thì gọi v4 với `display_type=2`. - API v4 dùng `ref_id` khác, xem [Place v4 API](https://maps.vietmap.vn/docs/vi/map-api/place-v4/) để biết chi tiết — API này thay cho Place API cũ. - Chúng tôi khuyên dùng `display_type=5` để quá trình chuyển đổi nhẹ nhàng nhất. Xem tài liệu bản cũ: [Geocode v3](https://maps.vietmap.vn/docs/vi/map-api/geocode-version/geocode-ver3.0/). ### 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)|| |text|string|có|Chuỗi địa chỉ đầy đủ cần geocode (số nhà, đường, phường/xã, tỉnh/thành), ví dụ `197 Trần Phú, phường 4, quận 5, TP.HCM`. Không gửi chuỗi gõ dở — xem cảnh báo đầu trang|197 Trần Phú, phường 4, quận 5, thành phố Hồ Chí Minh| |focus|string|không|Tọa độ vị trí hiện tại của người dùng, dùng để ưu tiên kết quả ở gần. Định dạng `lat,lng` — **vĩ độ trước**. Bỏ trống thì kết quả chỉ xếp theo độ khớp chữ|10.762622,106.660172| |display_type|number|không|Định dạng kết quả trả về. Chi tiết xem [Các giá trị display_type](#cac-gia-tri-display_type)|1| |layers|string|không|Giới hạn loại dữ liệu trả về. **Giá trị cho phép:** `POI`, `ADDRESS`, `VILLAGE`, `WARD`, `DIST`, `CITY`, `STREET`. Bỏ trống thì tìm trong mọi loại|POI| |circle_center|number|không|Tọa độ tâm của vùng tròn cần tìm, định dạng `lat,lng`. Đi kèm `circle_radius`|10.758867,106.675566| |circle_radius|number|không|Bán kính vùng tròn cần tìm, tính bằng **mét**. Chỉ có tác dụng khi đã gửi `circle_center`|200| |cats|string|không|Danh sách nhóm địa điểm (POI). Xem tại [POI Categories](https://vietmapcorp-my.sharepoint.com/:x:/g/personal/sennd_vietmap_vn/EacvkT3kgtBHmYUPnI5Nuj8BKHfvM6_HFNS_THOuxDty8A?e=5M8IAM&clickparams=eyJBcHBOYW1lIjoiVGVhbXMtRGVza3RvcCIsIkFwcFZlcnNpb24iOiIyNy8yMzAyMDUwMTQyMSIsIkhhc0ZlZGVyYXRlZFVzZXIiOmZhbHNlfQ%3D%3D){:target="_blank}|1002-1 | |cityId|number|không|Lọc kết quả trong một tỉnh/thành. Tra ID tại [kho dữ liệu hành chính](https://github.com/vietmap-company/vietnam_administrative_address)|12| |distId|number|không|Lọc kết quả trong một quận/huyện. Tra ID tại [kho dữ liệu hành chính](https://github.com/vietmap-company/vietnam_administrative_address)|1292| |wardId|number|không|Lọc kết quả trong một phường/xã. Tra ID tại [kho dữ liệu hành chính](https://github.com/vietmap-company/vietnam_administrative_address)|984332| |admin_new|boolean|không|Chọn ranh giới hành chính mới (`true`) hay cũ (`false`). Chỉ có tác dụng khi lọc theo `cityId`/`distId`/`wardId`. Đặt `false` rồi lọc theo ID TP.HCM thì chỉ trả dữ liệu trong ranh giới cũ, không gồm Bình Dương và Vũng Tàu|false| #### Các giá trị display_type | Giá trị | Tên | Mô tả | |------:|------------------------|---------------------------------------------------------------------------------------------------------| | 1 | Trả định dạng mới | Định dạng hành chính mới sau sáp nhập (2 cấp: phường/xã, tỉnh/thành). | | 2 | Trả định dạng cũ | Định dạng hành chính cũ (3 cấp: phường/xã, quận/huyện, tỉnh/thành). | | 3 | Trả theo định dạng đầu vào | API tự nhận diện kiểu người dùng nhập và trả về đúng kiểu đó. | | 5 | Trả cả Mới & Cũ | Kết quả chính theo định dạng mới, kèm bản theo đơn vị hành chính cũ trong `data_old`. | | 6 | Trả cả Cũ & Mới | Kết quả chính theo định dạng cũ, kèm bản theo đơn vị hành chính mới trong `data_new`. | ### Ví dụ **Đầu vào** ```url 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 ``` [:material-play-circle: Chạy ví dụ này trên Playground](https://tools.vietmap.vn/playground/geocode?text=197%20Tr%E1%BA%A7n%20Ph%C3%BA,%20ph%C6%B0%E1%BB%9Dng%204,%20qu%E1%BA%ADn%205,%20th%C3%A0nh%20ph%E1%BB%91%20H%E1%BB%93%20Ch%C3%AD%20Minh&focus=10.75887508,106.67538868&display_type=6){ .md-button .md-button--primary } **Phản hồi** Cần thông tin chi tiết của địa điểm thì bạn dùng [VIETMAP Place API](https://maps.vietmap.vn/docs/vi/map-api/place-v4/) === "Trả cả Cũ & Mới
`display_type=6`" ```json [ { "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 } ] ``` === "Trả cả Mới & Cũ
`display_type=5`" ```json [ { "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 } } ] ``` === "Trả theo định dạng đầu vào
`display_type=3`" ```json [ { "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 } ] ``` === "Trả định dạng cũ
`display_type=2`" ```json [ { "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 } ] ``` === "Trả định dạng mới
`display_type=1`" ```json [ { "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 } ] ``` ### Mô tả phản hồi Geocode API trả về một `list` chứa `tối đa 10 địa điểm`. | Trường | Kiểu | Mô tả | | ----------- | ------ | -------------------------------------------------------------- | | ref_id | string | Mã tham chiếu của địa điểm (POI), có thể kèm tiền tố ứng với display_type. Dùng [VIETMAP Place API](https://maps.vietmap.vn/docs/vi/map-api/place-v4/) để lấy thông tin chi tiết. | | distance | number | Khoảng cách, tính bằng `km` | | address | string | Địa chỉ đầy đủ gồm `đường`, `phường/xã`, `quận/huyện` và `tỉnh/thành` | | name | string | Tên địa điểm (POI) | | display | string | Tên hiển thị, chứa đầy đủ thông tin địa chỉ của địa điểm | | boundaries | array | Mảng các đơn vị hành chính của địa chỉ, xếp từ cấp nhỏ đến cấp lớn (`phường/xã`, `quận/huyện`, `tỉnh/thành`). Với định dạng hiển thị mới, mảng này gồm các object chứa `phường/xã` và `tỉnh/thành`.| | categories | array | Mảng các nhóm mà địa điểm thuộc về (mã nhóm xem ở tham số “cats”). | | entry_points| array | Mảng các lối vào của địa điểm. Chỉ có ở một số địa điểm đặc biệt như sân bay, khách sạn... | | data_old | object hoặc null | Bản định dạng cũ của kết quả này (khi display_type có yêu cầu), còn lại là `null`. | | data_new | object hoặc null | Bản định dạng mới của kết quả này (khi display_type có yêu cầu), còn lại là `null`. | Với mảng `boundaries`: | Trường con | Kiểu | Mô tả | | ------------- | ------ | ---------------------------------------------- | | type | integer| Cấp hành chính (`0` = tỉnh/thành, `1` = quận/huyện, `2` = phường/xã) | | id | integer| Mã định danh của đơn vị hành chính | | name | string | Tên đơn vị hành chính, chưa kèm tiền tố | | prefix | string | Tiền tố cấp hành chính. **Ví dụ:** `Phường`, `Quận`, `Thành Phố` | | full_name | string | Tên đầy đủ gồm cả tiền tố. **Ví dụ:** `Phường 9` | Với mảng `entry_points`: | Trường con | Kiểu | Mô tả | | ------------- | ------- | ---------------------------------------------- | | ref_id | string | Mã tham chiếu của địa điểm (POI) | | name | string | Tên địa điểm (POI) | Với object `data_old` và `data_new`: | Trường con | Kiểu | Mô tả | | ------------- | ------ | ------------------------------------------------------------- | | ref_id | string | Mã tham chiếu của bản kết quả này | | distance | number | Khoảng cách, tính bằng `km` | | address | string | Địa chỉ đầy đủ | | name | string | Tên địa điểm | | display | string | Chuỗi hiển thị chứa đầy đủ thông tin địa chỉ | | boundaries | array | Cấu trúc giống mảng `boundaries` ở trên | | categories | array | Mã nhóm địa điểm | | entry_points | array | Lối vào của địa điểm (nếu có) | Cần thông tin chi tiết của lối vào thì bạn dùng [VIETMAP Place v4 API](https://maps.vietmap.vn/docs/vi/map-api/place-v4/) ### 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ở Geocode v4 trên Playground](https://tools.vietmap.vn/playground/geocode)**