Phiên bản: v1.1

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

Tham số

Thông số bắt buộc	Kiểu dữ liệu	Mô tả
`point.lat`	`number`	Giá trị thập phân của kinh độ từ tọa độ địa lý của vị trí đang được truy vấn.
`point.lon`	`number`	Giá 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ọn	Kiểu dữ liệu	Mô tả
`zoom`	`integer`	Mứ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.
`size`	`integer`	Số lượng kết quả trả về nếu không được cung cấp mặc định là `10`.
`region_code`	`integer`	Lọc kết quả theo mã tỉnh/thành phố. Xem danh sách mã tại đây.
`localadmin_code`	`integer`	Lọc kết quả theo mã xã/phường. Xem danh sách mã tại đây.

Headers

Header	Kiểu dữ liệu	Mô tả
`app-version`	`string`	Bắt buộc. Phiên bản API: `1.1`

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

Root `(response)`

Trường	Kiểu dữ liệu	Mô tả
`type`	`string`	Luôn là `"FeatureCollection"`.
`features`	`Feature[]`	Mảng kết quả. Rỗng `[]` nếu không tìm thấy kết quả tại tọa độ.
`bbox`	`number[]`	Bounding box bao quanh tất cả kết quả: `[min_lon, min_lat, max_lon, max_lat]`.
`meta.pagination.next_page_token`	`string`	Token phân trang cho trang tiếp theo.
`licence`	`string`	Giấy phép dữ liệu: `"© GTEL Maps"`.

Features `(response.features[])`

Trường	Kiểu dữ liệu	Mô tả
`type`	`string`	Luôn là `"Feature"`.
`properties`	`object`	Thông tin chi tiết của địa điểm.
`geometry`	`object`	Thông tin hình học của địa điểm.

Geometry `(response.features[].geometry)`

Trường	Kiểu dữ liệu	Mô tả
`type`	`string`	Luôn là `"Point"`.
`coordinates`	`number[]`	Tọa độ theo thứ tự `[longitude, latitude]`.

Properties `(response.features[].properties)`

Trường	Kiểu dữ liệu	Mô tả
`id`	`string`	ID nội bộ của địa điểm. Có thể rỗng `""` khi `zoom` thấp (cấp country/region).
`gid`	`string`	Mã định danh toàn cục. Dùng để truy vấn Place Detail. Có thể rỗng `""` khi `zoom` thấp.
`layer`	`string`	Lớp dữ liệu được xác định bởi tham số zoom. Xem đầy đủ lớp dữ liệu.
`source`	`string`	Nguồn dữ liệu. Luôn là `"gm"`.
`name`	`string`	Tê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`).
`housenumber`	`string`	Số nhà (chỉ có khi `zoom >= 14` và lớp `address`).
`street`	`string`	Tên đường (chỉ có khi `zoom >= 14` và lớp `address`).
`confidence`	`number`	Độ tin cậy của kết quả, từ `0` đến `1`.
`distance`	`number`	Khoả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.
`accuracy`	`string`	Độ chính xác tọa độ: `point` (chính xác), `centroid` (trung tâm vùng).
`country`	`string`	Tên quốc gia.
`region`	`string`	Tên tỉnh/thành phố.
`localadmin`	`string`	Tên phường/xã. Có thể rỗng `""` khi `zoom` thấp.
`plus_code`	`string`	Mã Plus Code toàn cầu. Ví dụ: `7P28QM8M+C8`.
`region_code`	`string`	Mã tỉnh/thành phố.
`localadmin_code`	`string`	Mã phường/xã.
`locality_code`	`string`	Mã địa phương.
`address`	`string`	Địa chỉ đầy đủ đã định dạng.
`types`	`string[]`	Phân loại kết quả. Ví dụ: `["street_address"]`, `["hospital"]`. Xem loại địa điểm.
`address_components`	`object[]`	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.

`zoom`	`layer`	Thành phần có trong `address_components`
`<= 4`	`country`	`country`
`5–10`	`region`	`country`, `administrative_area_level_1`
`11–13`	`localadmin`	`country`, `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

Xử lý lỗi

Mã HTTP	Tình huống	Nguyên nhân
`401 Unauthorized`	Thiếu `apikey`	Không truyền tham số `apikey` hoặc giá trị không hợp lệ.
`400 Bad Request`	Thiếu tọa độ	Không truyền `point.lat` hoặc `point.lon`.

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

Loading API request...

{
  "geocoding": {
    "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"
}

Dịch vụ Reverse Geocoding​

Tham số​

Headers​

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

Root (response)​

Features (response.features[])​

Geometry (response.features[].geometry)​

Properties (response.features[].properties)​

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

Xử lý lỗi​

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