CHILDREN ID (V2)

TỔNG QUAN

Child ID là một tính năng dùng để biểu thị mối quan hệ cha – con giữa các địa điểm, cho phép hệ thống phân tách và truy xuất thông tin chi tiết hơn trong phạm vi một địa điểm lớn.

Trong nhiều tình huống thực tế, một địa điểm tổng thể có thể bao gồm nhiều khu vực con — ví dụ như cổng ra vào của sân bay, sảnh chờ từng tầng, khu vực bán lẻ trong trung tâm thương mại, hay bãi đón – trả khách trong bến xe liên tỉnh. Việc định danh riêng cho từng khu vực này giúp tăng độ chính xác khi chỉ dẫn, gợi ý tìm kiếm hoặc điều phối di chuyển.

Ở phiên bản V2, hệ thống đã được cập nhật hoàn toàn theo địa giới hành chính mới, phản ánh đúng các thay đổi sau quá trình sáp nhập đơn vị hành chính cấp xã, huyện ở nhiều tỉnh thành. Cùng với đó, Child ID tiếp tục được duy trì như một lớp định danh con, liên kết trực tiếp với place_id của địa điểm cha, cho phép truy xuất linh hoạt theo cả cấu trúc hành chính và cấu trúc không gian thực tế.

Với định dạng phản hồi JSON quen thuộc, API V2 vừa đảm bảo tính tương thích khi tích hợp vào hệ thống hiện tại, vừa đáp ứng yêu cầu dữ liệu địa lý chính xác trong bối cảnh hành chính mới.

CÁCH THỨC TẠO MỘT YÊU CẦU CHILD ID

Đầu tiên, bạn phải đăng ký tài khoản và tạo API key của Goong theo hướng dẫn chi tiết tại đây.

URL: https://rsapi.goong.io/v2/place/children

Phương thức: GET

Ví dụ về request truyền vào:

https://rsapi.goong.io/v2/place/children?parent_id=mkSTeXlgiYFUzS5Mu1-nwXuWbga8aInzZs8jS7hgq-FopXItor-FwbqqMFx3brv-aqoyT6Nja5MyBqEQIoF54wUWQRwS6bajPeaVfS4ls9uAfqUwfv26ZiR67RDSJbPLJ&api_key={YOUR_API_KEY}&has_deprecated_administrative_unit=false
Tham số Mô tả Ví dụ
parent_id Mã định danh của địa điểm cha. Thường là các khu vực lớn như sân bay, trung tâm thương mại, tòa nhà lớn,… ZIHxuGZP4kxPgHlamHaB436AaxeYRLWa
api_key API Key dùng để xác thực truy cập dịch vụ Goong API. API key của bạn
has_deprecated_administrative_unit

Là tham số boolean dùng trong API V2, để hiển thị thêm thông tin địa giới hành chính trước khi sáp nhập.

 True: Kết quả vẫn theo địa giới mới, nhưng có thêm trường deprecated_description và deprecated_compound chứa tên địa phương cũ.

 False hoặc mặc định: Chỉ trả về địa giới mới, không kèm thông tin cũ.

 Dữ liệu chính không thay đổi, param này chỉ để tham chiếu địa danh cũ nếu cần.

  false

Response trả về:

{
    "predictions": [
        {
            "description": "Cổng đón/trả khách, Trường THPT Nguyễn Bỉnh Khiêm, 78 Hoàng Hoa Thám, Tam Long, Hồ Chí Minh",
            "matched_substrings": null,
            "place_id": "oXe3tlO8AXFyj1sxpFqs6HPSalW6d53fcr9xFHNbls6l0V8vQXmk33e1nlSnZI55aNKTJ79bitZ0tlugFmbtz38vZdG8AJbfcqVAVJZmQlv9zjFMAoACGlnGkWyuWAe3W",
            "reference": "oXe3tlO8AXFyj1sxpFqs6HPSalW6d53fcr9xFHNbls6l0V8vQXmk33e1nlSnZI55aNKTJ79bitZ0tlugFmbtz38vZdG8AJbfcqVAVJZmQlv9zjFMAoACGlnGkWyuWAe3W",
            "structured_formatting": {
                "main_text": "Cổng đón/trả khách",
                "main_text_matched_substrings": null,
                "secondary_text": "Trường THPT Nguyễn Bỉnh Khiêm, 78 Hoàng Hoa Thám, Tam Long, Hồ Chí Minh",
                "secondary_text_matched_substrings": null
            },
            "has_children": false,
            "plus_code": {
                "compound_code": "+JKB1 Long Tâm, Bà Rịa, Bà Rịa-Vũng Tàu",
                "global_code": "49ON8+JKB1"
            },
            "compound": {
                "commune": "Tam Long",
                "province": "Hồ Chí Minh"
            },
            "terms": [
                {
                    "offset": 0,
                    "value": "Cổng đón/trả khách"
                },
                {
                    "offset": 26,
                    "value": "Trường THPT Nguyễn Bỉnh Khiêm"
                },
                {
                    "offset": 65,
                    "value": "78 Hoàng Hoa Thám"
                },
                {
                    "offset": 86,
                    "value": "Tam Long"
                },
                {
                    "offset": 96,
                    "value": "Hồ Chí Minh"
                }
            ],
            "types": [
                "site"
            ],
            "distance_meters": null
        }
    ],
    "execution_time": "143.612µs",
    "status": "OK"
}
Tham số Mô tả Ví dụ
description Địa chỉ hiển thị đầy đủ cho người dùng “Cổng đón/trả khách, Trường THPT Nguyễn Bỉnh Khiêm, 78 Hoàng Hoa Thám, Tam Long, Hồ Chí Minh”
place_id Mã định danh duy nhất cho địa điểm – dùng cho Place Detail API “oXe3tlO8AXFyj1sxpFqs6HPSalW6d53f…”
reference Mã tham chiếu nội bộ – giống place_id “oXe3tlO8AXFyj1sxpFqs6HPSalW6d53f…”
main_text Tên chính của địa điểm, phần nổi bật “Cổng đón/trả khách”
secondary_text Phần thông tin bổ sung (tên trường, đường, phường, tỉnh…) “Trường THPT Nguyễn Bỉnh Khiêm, 78 Hoàng Hoa Thám, Tam Long, Hồ Chí Minh”
has_children Địa điểm có cấp con không? (true/false) FALSE
plus_code.compound_code Mã địa phương hóa địa điểm (Open Location Code) “+JKB1 Long Tâm, Bà Rịa, Bà Rịa-Vũng Tàu”
plus_code.global_code Mã toàn cầu cho địa điểm “49ON8+JKB1”
compound.commune Xã/phường theo đơn vị hành chính mới “Tam Long”
compound.province Tỉnh/thành theo đơn vị hành chính mới “Hồ Chí Minh”
terms Danh sách các thành phần địa chỉ và vị trí bắt đầu trong chuỗi [{ “offset”: 0, “value”: “Cổng đón/trả khách” }, …]
types Loại địa điểm (site, building, street_address…) [“site”]
distance_meters Khoảng cách từ location đầu vào đến địa điểm này (nếu có truyền) null
execution_time Thời gian xử lý truy vấn (micro giây) “143.612µs”
status Trạng thái phản hồi “OK”
deprecated_description Chuỗi mô tả đầy đủ địa chỉ với thông tin cũ. Long Tâm, Bà Rịa, Bà Rịa-Vũng Tàu
deprecated_compound Thông tin địa giới hành chính xã/phường, quận/huyện và tỉnh/thành phố. {“commune”: “Long Tâm”, “district”: “Bà Rịa”, “province”: “Bà Rịa-Vũng Tàu”}