TỔNG QUAN

Geocode Street API của Goong cho phép truy xuất tên đường từ tọa độ lat/lng (vĩ độ, kinh độ), đồng thời trả về các thông tin địa lý liên quan đến tuyến đường đó. Khi truyền vào một cặp tọa độ, API sẽ xác định tên đường tại vị trí tương ứng, sau đó truy xuất về các dữ liệu như vị trí trung tâm của đường, mã vùng, đơn vị hành chính cấp xã và tỉnh/thành phố của đường tị vị trí đó.

API này hỗ trợ hiệu quả cho các tác vụ như ánh xạ tuyến đường vào khu vực hành chính, phân loại điểm giao nhận, phân tích dữ liệu vận hành theo địa bàn hoặc đồng bộ hóa dữ liệu bản đồ. Việc sử dụng Geocode Street giúp hệ thống xác định rõ một vị trí cụ thể thuộc tuyến đường nào và nằm trong phạm vi quản lý của địa phương nào – điều đặc biệt quan trọng trong bối cảnh thay đổi địa giới hành chính hiện nay, khi thông tin địa lý cần được cập nhật kịp thời và chính xác tuyệt đối.

CÁCH SỬ DỤNG GEOCODE STREET

Đầ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/geocode/street

Phương thức: GET

Định nghĩa

Geocode street là quá trình chuyển đổi từ tọa độ (vĩ độ và kinh độ) thành địa chỉ đường cụ thể

Thông số bắt buộc

• latlng: Tọa độ điểm cần lấy thông tin.

Tham số trong request truyền vào:

https://rsapi.goong.io/v2/geocode/street?api_key={YOUR_API_KEY}&latlng=21.030145,105.811122&has_deprecated_administrative_unit=true

 

Tham số	Mô tả	Ví dụ
latlng	Tọa độ địa điểm cần truy vấn, gồm lat,long	21.120678,106.397301
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ũ..	True
api_key	Mã khóa API của bạn để xác thực với hệ thống	API key của bạn

Tham số trong response trả về:

{

  "results": [

    {

      "address_components": [

        {

          "long_name": "Kim Mã",

          "short_name": "Kim Mã"

        },

        {

          "long_name": "Giảng Võ",

          "short_name": "Giảng Võ"

        },

        {

          "long_name": "Hà Nội",

          "short_name": "Hà Nội"

        }

      ],

      "formatted_address": "Kim Mã, Giảng Võ, Hà Nội",

      "geometry": {

        "location": {

          "lat": 21.030145,

          "lng": 105.811122

        },

        "boundary": "anj_CenydSx@tH"

      },

      "place_id": "gqXMe8N2ZLdLtl-brGZ7twebS0PDeopXeJ2tRqxmoi57i9lNP-naGtlKmUCqBTJXVZMBAQ7Vknf5SwSsD",

      "reference": "gqXMe8N2ZLdLtl-brGZ7twebS0PDeopXeJ2tRqxmoi57i9lNP-naGtlKmUCqBTJXVZMBAQ7Vknf5SwSsD",

      "plus_code": null,

      "compound": {

        "commune": "Giảng Võ",

        "province": "Hà Nội"

      },

      "types": [],

      "name": "Kim Mã",

      "address": "Giảng Võ, Hà Nội",

      "deprecated_description": "Kim Mã, Ngọc Khánh, Ba Đình, Hà Nội",

      "deprecated_compound": {

        "district": "Ba Đình",

        "commune": "Ngọc Khánh",

        "province": "Hà Nội"

      }

    }

  ],

  "status": "OK"

}

 

Tên tham số	Mô tả chi tiết	Ví dụ
results	Mảng chứa các kết quả địa điểm phù hợp với tọa độ hoặc truy vấn đầu vào. Mỗi phần tử trong mảng là thông tin chi tiết của một địa điểm.	{ “address_components”: [ { “long_name”: “Duy Xuyên”, “short_name”: “Duy Xuyên” }, { “long_name”: “Đà Nẵng”, “short_name”: “Đà Nẵng” }
address_components	Danh sách các thành phần tạo nên địa chỉ, từ chi tiết nhỏ nhất (số nhà, đường) đến cấp hành chính lớn hơn (phường, quận, tỉnh).	“long_name”: “Duy Xuyên”,
formatted_address	Địa chỉ đầy đủ, đã được định dạng rõ ràng và sắp xếp theo thứ tự từ nhỏ đến lớn. Thường dùng để hiển thị cho người dùng cuối.	“Duy Xuyên, Đà Nẵng”,
location.lat	Vĩ độ (latitude) của địa điểm – tọa độ theo hướng Bắc – Nam.	15.765075
location.lng	Kinh độ (longitude) của địa điểm – tọa độ theo hướng Đông – Tây.	108.204474
boundary	Đa giác (polygon) biểu diễn ranh giới hành chính hoặc khu vực địa lý của địa điểm. Nếu không có, sẽ là null.	“io`_Bee_sS}[wAmM_AgLy@uGMuGNaJfBeH~DkCdBy@null
place_id	Mã định danh duy nhất cho địa điểm. Dùng để tham chiếu hoặc tìm kiếm lại địa điểm trong các API khác.	drtqhLmKubt1uUEJoVZFi3Wrd5ijaE10ar…
reference	Trường tham chiếu địa điểm, thường trùng với place_id. Giữ lại để tương thích với phiên bản cũ.	drtqhLmKubt1uUEJoVZFi3Wrd5ijaE10ar
compound_code	Mã định vị địa phương dạng Plus Code (mã mở), cho phép xác định vị trí chính xác trong khu vực hành chính.
global_code	Mã định vị toàn cầu dạng Plus Code. Dùng trong các hệ thống không cần địa chỉ hành chính.	“MXUP+BMKDMI”
province	Tên tỉnh/thành phố nơi địa điểm tọa lạc. Dữ liệu này đã được cập nhật theo đơn vị hành chính mới nhất.	Đà Nẵng
district	Tên quận/huyện hoặc thành phố cấp huyệnĐà Nẵng	Duy Xuyên
commune	Tên phường/xã/thị trấn.	Duy Sơn
types	Danh sách loại địa điểm theo phân loại hệ thống (nếu có), ví dụ: route, house_number, locality,… Có thể rỗng nếu không xác định.	[]
name	Tên chính của địa điểm hoặc phần mô tả ngắn gọn, ví dụ: tên cửa hàng, số nhà, địa danh.	Duy Xuyên
address	Địa chỉ hành chính không bao gồm tên cụ thể hay số nhà, thường là cụm “xã/phường, huyện/quận, tỉnh/thành”.	Đà Nẵng
status	Trạng thái phản hồi của API. “OK” nghĩa là thành công, “INVALID_REQUEST” là sai định dạng truy vấn…	“OK”
deprecated_description	Chuỗi mô tả đầy đủ địa chỉ với thông tin cũ.	Duy Sơn, Duy Xuyên, Quảng Nam
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”: “Duy Sơn”, “district”: “Duy Xuyên”, “province”: “Quảng Nam”}