Place Detail

API Place Detail GTEL MAPS cho phép tìm kiếm chính xác một địa điểm, 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ụ Place Detail

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ả
`ids`	`string`	Mọi kết quả trả về từ Geocoding Service đều có một mã toàn cục gọi là `gid`. Truyền nhiều `gid` thì ngăn cách bằng dấu phẩy.

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

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ả
`data`	`object`	Thông tin chi tiết của địa điểm.
`meta.data_version`	`string`	Phiên bản dữ liệu đã trả lời request này. Có cả khi kết quả là `404`.
`licence`	`string`	Giấy phép dữ liệu: `"© GTEL Maps"`.

Data `(response.data)`

Trường	Kiểu dữ liệu	Mô tả
`id`	`string`	Mã toàn cục `(gid)`. Ví dụ: `gm:address:72dcb4b8-...`.
`types`	`string[]`	Phân loại địa điểm. Ví dụ: `["street_address"]`, `["hospital"]`. Xem loại địa điểm.
`formattedAddress`	`string`	Địa chỉ đầy đủ đã định dạng.
`addressComponents`	`object[]`	Thành phần địa chỉ phân tách. Xem định nghĩa đầy đủ tại trường address_components.
`plusCode.globalCode`	`string`	Mã Plus Code toàn cầu. Ví dụ: `7P28QM8M+C8`.
`plusCode.compoundCode`	`string`	Mã Plus Code kèm ngữ cảnh địa lý.
`location.latitude`	`number`	Vĩ độ.
`location.longitude`	`number`	Kinh độ.
`viewport.low.latitude`	`number`	Vĩ độ của điểm thấp nhất viewport.
`viewport.low.longitude`	`number`	Kinh độ của điểm thấp nhất viewport.
`viewport.high.latitude`	`number`	Vĩ độ của điểm cao nhất viewport.
`viewport.high.longitude`	`number`	Kinh độ của điểm cao nhất viewport.
`displayName.text`	`string`	Tên hiển thị của địa điểm.
`displayName.languageCode`	`string`	Mã ngôn ngữ của tên hiển thị. Ví dụ: `"vi"`.
`nationalPhoneNumber`	`string`	Số điện thoại nội địa (rỗng `""` nếu không có).
`internationalPhoneNumber`	`string`	Số điện thoại quốc tế (rỗng `""` nếu không có).
`websiteUri`	`string`	Website (rỗng `""` nếu không có).
`email`	`string`	Email (rỗng `""` nếu không có).
`timeZone.id`	`string`	Múi giờ. Ví dụ: `"Asia/Ho_Chi_Minh"`.
`extras`	`object`	Thông tin bổ sung (thường là `{}`).

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ệ.
`404 Not Found`	Không tìm thấy địa điểm	`ids` không được truyền, hoặc `gid` không tồn tại trong phiên bản dữ liệu đang dùng.
`400 Bad Request`	`data_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...

{
  "data": {
    "id": "gm:address:72dcb4b8-8ea4-4277-a5e7-eecc9d795a6f",
    "types": ["street_address"],
    "nationalPhoneNumber": "",
    "internationalPhoneNumber": "",
    "formattedAddress": "47A Phạm Viết Chánh, Phường Cầu Ông Lãnh, Thành phố Hồ Chí Minh, Việt Nam",
    "addressComponents": [
      {
        "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"]
      }
    ],
    "plusCode": {
      "globalCode": "7P28QM8M+C8",
      "compoundCode": "QM8M+C8, Phường Cầu Ông Lãnh, Thành phố Hồ Chí Minh, Việt Nam"
    },
    "location": {
      "latitude": 10.766121,
      "longitude": 106.683321
    },
    "viewport": {
      "low": {
        "latitude": 10.764324377650018,
        "longitude": 106.68149218665364
      },
      "high": {
        "latitude": 10.767917622349982,
        "longitude": 106.68514981334637
      }
    },
    "websiteUri": "",
    "email": "",
    "adrFormatAddress": "",
    "displayName": {
      "text": "Tiệm Giải Khát",
      "languageCode": "vi"
    },
    "timeZone": {
      "id": "Asia/Ho_Chi_Minh"
    },
    "extras": {}
  },
  "meta": {
    "data_version": "2025-07.r2"
  },
  "licence": "© GTEL Maps"
}

Dịch vụ Place Detail​

Tham số​

Headers​

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

Root (response)​

Data (response.data)​

Xử lý lỗi​

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