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
Loading...
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ả |
|---|---|---|
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ả |
|---|---|---|
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ả 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ã định danh 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. |
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 | 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 tham số text | text không được truyền hoặc là chuỗi rỗng. |
400 Bad Request | Thiếu header app-version | Không gửi header app-version: 1.1. API fallback về schema cũ và từ chối danh sách layers mặc định. |
Yêu cầu và phản hồi mẫu
Loading API request...
{
"geocoding": {
"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"
}