Bỏ qua

Geocode v4

Geocode cho tìm kiếm địa chỉ sau sáp nhập

geocode

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 để lấy lat/lng.

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.

Playground

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

Tích hợp AI Agent ✨ MỚI

Tải bộ tài liệu đã tối ưu cho AI agent (Geocode + Reverse): Geocode & Reverse Geocoding Agent Doc

Hoặc dùng thử bằng Postman.

URL

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 để 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.

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
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 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 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 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 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 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 

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

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

[
    {
        "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
    }
]

[
    {
        "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
        }
    }
]

[
    {
        "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
    }
]

[
    {
        "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
    }
]

[
    {
        "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 để 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

facebook
Tổng đài hỗ trợ
089.616.4567 facebook Chat Facebook zalo Chat Zalo