Chuyển tới nội dung chính
Phiên bản: v1.1

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...

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ả
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ả
app-versionstringBắt buộc. Phiên bản API: 1.1

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

Root (response)​

TrườngKiểu dữ liệuMô tả
typestringLuôn là "FeatureCollection".
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ã định danh 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.
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 RequestThiếu header app-versionKhô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",
      "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"
}