Forward Geocoding

API Forward Geocoding GTEL MAPS cho phép tìm kiếm một địa điểm bằng chuỗi văn bản và trả về địa chỉ được chuẩn hóa, ngữ cảnh địa lý và tọa độ của địa điểm đó.

Dịch vụ Forward Geocoding

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ộc	Kiểu dữ liệu	Mô tả
`text`	`string`	Địa chỉ muốn tra cứu có thể là đường, thành phố, v.v.

Tham số tuỳ chọn	Kiểu dữ liệu	Mô tả
`data_version`	`string`	Mã 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
`layers`	`string`	Lọ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.
`types`	`string`	Lọ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.
`next_page_token`	`string`	Token phân trang cho lần gửi yêu cầu tiếp theo. Token cho trang tiếp theo được trả về tại `meta.pagination.next_page_token`.
`size`	`integer`	Số lượng kết quả trả về, 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.
`focus.point.lat`	`number`	Vĩ độ của điểm cần tập trung cần tìm kiếm.
`focus.point.lon`	`number`	Kinh độ của điểm cần tập trung cần tìm kiếm.

Headers

Header	Kiểu dữ liệu	Mô tả
`X-Data-Version`	`string`	Cá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ường	Kiểu dữ liệu	Mô tả
`type`	`string`	Luôn là `"FeatureCollection"`.
`geocoding.data_version`	`string`	Phiên bản dữ liệu đã trả lời request này.
`features`	`Feature[]`	Mảng kết quả tìm kiếm. Rỗng `[]` nếu không tìm thấy kết quả.
`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. Truyền vào tham số `next_page_token` để lấy 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.
`gid`	`string`	Mã toàn cục. Dùng để truy vấn Place Detail. Ví dụ: `gm:address:72dcb4b8-...`.
`layer`	`string`	Lớp dữ liệu. 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 hiển thị.
`housenumber`	`string`	Số nhà (nếu có).
`street`	`string`	Tên đường (nếu có).
`confidence`	`number`	Độ tin cậy của kết quả, từ `0` đến `1`.
`match_type`	`string`	Loại khớp: `exact` (chính xác), `fallback` (dự phòng), `interpolated` (nội suy).
`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ã.
`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.
`county`	`string`	Tên quận/huyện. Chỉ có ở phiên bản `legacy`.
`county_code`	`string`	Mã quận/huyện. Chỉ có ở phiên bản `legacy`.
`locality`	`string`	Tên phường/xã, trùng giá trị với `localadmin`. Chỉ có ở phiên bản `legacy`.
`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.

Xử lý lỗi

Mã HTTP	Tình huống
`401 Unauthorized`	Thiếu hoặc sai `apikey`
`400 Bad Request`	Tham số không hợp lệ — thiếu `text`, hoặc `data_version` sai mã/định dạng

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",
      "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,
      "parser": "pelias",
      "parsed_text": {
        "subject": "47A Phạm Viết Chánh"
      }
    }
  },
  "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,
        "match_type": "exact",
        "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": "WzYxLjk0MywiNzJkY2I0YjgtOGVhNC00Mjc3LWE1ZTctZWVjYzlkNzk1YTZmIl0="
    }
  },
  "licence": "© GTEL Maps"
}

Dịch vụ Forward 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)​

Xử lý lỗi​

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