Chuyển tới nội dung chính

Autocomplete Geocoding

API Autocomplete Geocoding GTEL MAPS cho phép tìm kiếm một địa điểm bằng chuỗi văn bản dựa trên từ khoá người dùng nhập và trả về danh sách địa chỉ được chuẩn hóa, ngữ cảnh địa lý và tọa độ của địa điểm đó để dễ dàng lựa chọn.

Dịch vụ Autocomplete Geocoding​

Loading...
Chọn phiên bản dữ liệu

Luôn truyền query parameter data_version hoặc header X-Data-Version trong mọi request. Xem Data Versions.

Tham số​

Tham số bắt buộcKiểu dữ liệuMô tả
textstringĐịa chỉ muốn tra cứu có thể là đường, thành phố, v.v.
Tham số tuỳ chọnKiểu dữ liệuMô tả
data_versionstringMã phiên bản dữ liệu — xem Data Versions; không truyền thì đọc dữ liệu trước sáp nhập, tức 63 tỉnh/thành phố còn cấp quận/huyện
layersstringLọc kết quả theo lớp dữ liệu. Có thể là một hoặc nhiều giá trị, phân cách bằng dấu phẩy. Ví dụ: address,poi. Xem danh sách đầy đủ tại lớp dữ liệu.
typesstringLọc kết quả theo danh mục địa điểm (POI). Có thể là một hoặc nhiều giá trị, phân cách bằng dấu phẩy. Ví dụ: hospital,restaurant. Xem danh sách đầy đủ tại loại địa điểm.
region_codeintegerLọc kết quả theo mã tỉnh/thành phố. Xem danh sách mã tại đây.
localadmin_codeintegerLọc kết quả theo mã xã/phường. Xem danh sách mã tại đây.
sizeintegerSố lượng kết quả trả về, mặc định là 10.
focus.point.latnumberVĩ độ của điểm cần tập trung cần tìm kiếm.
focus.point.lonnumberKinh độ của điểm cần tập trung cần tìm kiếm.

Headers​

HeaderKiểu dữ liệuMô tả
X-Data-VersionstringCách khác để chọn phiên bản dữ liệu thay cho data_version. Gửi cả hai thì tham số thắng.

Cấu trúc phản hồi​

Root (response)​

TrườngKiểu dữ liệuMô tả
typestringLuôn là "FeatureCollection".
geocoding.data_versionstringPhiên bản dữ liệu đã trả lời request này.
featuresFeature[]Mảng kết quả tìm kiếm. Rỗng [] nếu không tìm thấy kết quả.
bboxnumber[]Bounding box bao quanh tất cả kết quả: [min_lon, min_lat, max_lon, max_lat].
licencestringGiấy phép dữ liệu: "© GTEL Maps".

Features (response.features[])​

TrườngKiểu dữ liệuMô tả
typestringLuôn là "Feature".
propertiesobjectThông tin chi tiết của địa điểm.
geometryobjectThông tin hình học của địa điểm.

Geometry (response.features[].geometry)​

TrườngKiểu dữ liệuMô tả
typestringLuôn là "Point".
coordinatesnumber[]Tọa độ theo thứ tự [longitude, latitude].

Properties (response.features[].properties)​

TrườngKiểu dữ liệuMô tả
idstringID nội bộ của địa điểm.
gidstringMã toàn cục. Dùng để truy vấn Place Detail. Ví dụ: gm:address:72dcb4b8-....
layerstringLớp dữ liệu. Xem đầy đủ lớp dữ liệu.
sourcestringNguồn dữ liệu. Luôn là "gm".
namestringTên địa điểm hoặc tên hiển thị.
housenumberstringSố nhà (nếu có).
streetstringTên đường (nếu có).
accuracystringĐộ chính xác tọa độ: point (chính xác), centroid (trung tâm vùng).
countrystringTên quốc gia.
regionstringTên tỉnh/thành phố.
localadminstringTên phường/xã.
plus_codestringMã Plus Code toàn cầu. Ví dụ: 7P28QM8M+C8.
region_codestringMã tỉnh/thành phố.
localadmin_codestringMã phường/xã.
locality_codestringMã địa phương.
countystringTên quận/huyện. Chỉ có ở phiên bản legacy.
county_codestringMã quận/huyện. Chỉ có ở phiên bản legacy.
localitystringTên phường/xã, trùng giá trị với localadmin. Chỉ có ở phiên bản legacy.
addressstringĐịa chỉ đầy đủ đã định dạng.
typesstring[]Phân loại kết quả. Ví dụ: ["street_address"], ["hospital"]. Xem loại địa điểm.
address_componentsobject[]Thành phần địa chỉ phân tách. Xem định nghĩa đầy đủ tại trường address_components.

Xử lý lỗi​

Mã HTTPTình huốngNguyên nhân
401 UnauthorizedThiếu apikeyKhông truyền tham số apikey hoặc giá trị không hợp lệ.
400 Bad RequestThiếu tham số texttext không được truyền hoặc là chuỗi rỗng.
400 Bad Requestdata_version không hợp lệMã không tồn tại, sai chữ hoa chữ thường, hoặc truyền nhiều lần trong một request.

Yêu cầu và phản hồi mẫu​

Loading API request...
{
  "geocoding": {
    "data_version": "2025-07.r2",
    "query": {
      "text": "47a Phạm Viết Chánh",
      "parser": "pelias",
      "parsed_text": {
        "subject": "47a Phạm Viết Chánh"
      },
      "size": 1,
      "layers": ["address", "venue", "country", "region", "localadmin"],
      "sources": ["gm"],
      "private": false,
      "lang": {
        "name": "Vietnamese",
        "iso6391": "vi",
        "iso6393": "vie",
        "via": "querystring",
        "defaulted": false
      },
      "querySize": 20
    }
  },
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [106.683321, 10.766121]
      },
      "properties": {
        "id": "72dcb4b8-8ea4-4277-a5e7-eecc9d795a6f",
        "gid": "gm:address:72dcb4b8-8ea4-4277-a5e7-eecc9d795a6f",
        "layer": "address",
        "source": "gm",
        "source_id": "72dcb4b8-8ea4-4277-a5e7-eecc9d795a6f",
        "name": "Tiệm Giải Khát",
        "housenumber": "47A",
        "street": "Phạm Viết Chánh",
        "accuracy": "point",
        "country": "Việt Nam",
        "region": "Thành phố Hồ Chí Minh",
        "localadmin": "Phường Cầu Ông Lãnh",
        "plus_code": "7P28QM8M+C8",
        "region_code": "79",
        "localadmin_code": "26758",
        "locality_code": "26758",
        "address": "47A Phạm Viết Chánh, Phường Cầu Ông Lãnh, Thành phố Hồ Chí Minh, Việt Nam",
        "types": ["street_address"],
        "address_components": [
          {
            "longText": "47A",
            "shortText": "47A",
            "types": ["street_number"]
          },
          {
            "longText": "Phạm Viết Chánh",
            "shortText": "Phạm Viết Chánh",
            "types": ["route"]
          },
          {
            "longText": "Phường Cầu Ông Lãnh",
            "shortText": "Cầu Ông Lãnh",
            "adminCode": "26758",
            "adminLevel": "Phường",
            "types": ["administrative_area_level_2"]
          },
          {
            "longText": "Thành phố Hồ Chí Minh",
            "shortText": "Hồ Chí Minh",
            "adminCode": "79",
            "adminLevel": "Thành phố",
            "types": ["administrative_area_level_1"]
          },
          {
            "longText": "",
            "shortText": "",
            "types": ["postal_code"]
          },
          {
            "longText": "Việt Nam",
            "shortText": "vn",
            "types": ["country"]
          }
        ]
      }
    }
  ],
  "bbox": [106.683321, 10.766121, 106.683321, 10.766121],
  "licence": "© GTEL Maps"
}