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

Reverse Geocoding

API Reverse Geocoding GTEL MAPS cho phép tra cứu một cặp tọa độ và trả về các thông tin địa lý tại vị trí đó, bao gồm địa chỉ hoặc địa điểm được chuẩn hóa cùng với ngữ cảnh địa lý đầy đủ.

Dịch vụ Reverse 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ố​

Thông số bắt buộcKiểu dữ liệuMô tả
point.latnumberGiá trị thập phân của kinh độ từ tọa độ địa lý của vị trí đang được truy vấn.
point.lonnumberGiá trị thập phân của vĩ độ từ tọa độ địa lý của vị trí đang được truy vấn.
Thông 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
zoomintegerMức độ chi tiết của kết quả trả về. Giá trị tối thiểu là 0, mặc định là 14. Xem tham số zoom.
sizeintegerSố lượng kết quả trả về nếu không được cung cấp mặc định là 10.
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.

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. null khi toạ độ rơi vào vùng khai riêng.
featuresFeature[]Mảng kết quả. Rỗng [] nếu không tìm thấy kết quả tại tọa độ.
bboxnumber[]Bounding box bao quanh tất cả kết quả: [min_lon, min_lat, max_lon, max_lat].
meta.pagination.next_page_tokenstringToken phân trang cho trang tiếp theo.
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. Có thể rỗng "" khi zoom thấp (cấp country/region).
gidstringMã toàn cục. Dùng để truy vấn Place Detail. Có thể rỗng "" khi zoom thấp.
layerstringLớp dữ liệu được xác định bởi tham số zoom. 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 đơn vị hành chính (ví dụ: "Thành phố Hồ Chí Minh" khi zoom < 14).
housenumberstringSố nhà (chỉ có khi zoom >= 14 và lớp address).
streetstringTên đường (chỉ có khi zoom >= 14 và lớp address).
confidencenumberĐộ tin cậy của kết quả, từ 0 đến 1.
distancenumberKhoảng cách (km) từ tọa độ truy vấn đến kết quả. 0 nếu trùng khớp chính xá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ã. Có thể rỗng "" khi zoom thấp.
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. Tham số zoom quyết định các thành phần trả về.

Mức độ chi tiết theo tham số zoom​

Giá trị zoom quyết định lớp dữ liệu (layer) được trả về và mức độ chi tiết của address_components.

zoomlayerThành phần có trong address_components
<= 4countrycountry
5–10regioncountry, administrative_area_level_1
11–13localadmincountry, administrative_area_level_1, administrative_area_level_2
>= 14 (mặc định)address / poiĐầy đủ thành phần địa chỉ có trong trường address_components

Cột thứ ba áp cho dữ liệu sau sáp nhập. Ở phiên bản legacy, address_components rỗng với mọi zoom từ 13 trở xuống — chỉ từ zoom 14 mới có thành phần địa chỉ. Tên administrative_area_level_* cũng ứng với cấp hành chính khác nhau giữa hai phiên bản, xem 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 tọa độKhông truyền point.lat hoặc point.lon.
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": {
      "layers": ["address", "venue", "country", "region", "localadmin"],
      "sources": ["gm"],
      "size": 1,
      "private": false,
      "point.lat": 10.766121,
      "point.lon": 106.68332,
      "boundary.circle.lat": 10.766121,
      "boundary.circle.lon": 106.68332,
      "lang": {
        "name": "Vietnamese",
        "iso6391": "vi",
        "iso6393": "vie",
        "via": "querystring",
        "defaulted": false
      },
      "querySize": 2
    }
  },
  "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",
        "confidence": 1,
        "distance": 0,
        "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],
  "meta": {
    "pagination": {
      "next_page_token": "WzAsMC4wOTMyNjQzNjM2MzU3NDMxMV0="
    }
  },
  "licence": "© GTEL Maps"
}