TỔNG QUAN

Geocode là API chuyển đổi địa chỉ (ví dụ: địa chỉ nhà, cửa hàng…) thành tọa độ địa lý (kinh độ, vĩ độ)  và ngược lại. API này cho phép người dùng lấy được thông tin địa lý chi tiết như vị trí, mã vùng, quận/huyện, và thậm chí là các địa điểm kinh doanh.

Geocode API có 3 chức năng chính:

• Forward geocode: Chuyển đổi từ địa chỉ sang tọa độ

• Reverse geocode: Chuyển đổi từ tọa độ địa lý (kinh độ, vĩ độ) sang địa chỉ

• Tra cứu theo place_id: Nhận thông tin chi tiết về địa điểm qua mã place_id

Điểm nổi bật của V2 là khả năng cập nhật chính xác tên địa phương mới theo các quyết định sáp nhập, điều chỉnh địa giới hành chính. Ví dụ, các địa chỉ thuộc huyện cũ sẽ tự động được gán đúng vào đơn vị hành chính mới (đã sáp nhập), giúp đảm bảo kết quả luôn khớp với thực tế hiện hành.

CÁCH SỬ DỤNG GEOCODE

Đầ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

Phương thức: GET

Chuyển đổi từ địa chỉ sang tọa độ Forward Geocode

Định nghĩa

Forward Geocode là quá trình chuyển đổi một địa chỉ cụ thể thành tọa độ địa lý (vĩ độ và kinh độ). Khi bạn nhập một địa chỉ vào hệ thống, dịch vụ Geocode sẽ tìm kiếm và trả về các tọa độ tương ứng với địa chỉ đó.

Cách thức hoạt động của Forward geocode 

Khi bạn nhập một địa chỉ, hệ thống sẽ thực hiện quá trình chuyển đổi thông tin văn bản đó thành các tọa độ địa lý (vĩ độ, kinh độ) trên bản đồ. Quá trình này bao gồm:

• Chuẩn hóa dữ liệu: Hệ thống sẽ làm sạch dữ liệu đầu vào, loại bỏ các từ thừa và sắp xếp thông tin địa chỉ theo một cấu trúc nhất định.
• Tìm kiếm trong cơ sở dữ liệu: Hệ thống sẽ so sánh địa chỉ đã chuẩn hóa với các thông tin địa lý có sẵn trong cơ sở dữ liệu của mình.
• Trả về kết quả: Khi tìm thấy kết quả phù hợp, hệ thống sẽ trả về các tọa độ địa lý tương ứng cùng với các thông tin bổ sung như tên đường, quận, huyện…

Cách thức tạo một yêu cầu Forward geocode

Thông số bắt buộc

• address – Địa chỉ muốn lấy tọa độ.

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

https://rsapi.goong.io/v2/geocode?address=91%20Trung%20K%C3%ADnh%2C%20Trung%20H%C3%B2a%2C%20C%E1%BA%A7u%20Gi%E1%BA%A5y%2C%20H%C3%A0%20N%E1%BB%99i&api_key={YOUR_API_KEY}

Tham số trong response trả về:

{
  "results": [
    {
      "address_components": [
        {
          "long_name": "91 Trung Kính",
          "short_name": "91 Trung Kính"
        },
        {
          "long_name": "Yên Hòa",
          "short_name": "Yên Hòa"
        },
        {
          "long_name": "Hà Nội",
          "short_name": "Hà Nội"
        }
      ],
      "formatted_address": "91 Trung Kính, Yên Hòa, Hà Nội",
      "geometry": {
        "location": {
          "lat": 21.013672808000024,
          "lng": 105.79825090900005
        },
        "boundary": null
      },
      "place_id": "mSyZlrHISyhtoltUuEyJ-EG9ZhCvc6P6R4tiF7tjdOidiX40u1pvcG-iPyAolJEHcK1EmS1zXJR41bDJl3CN93WnRFWhXeTLvdZdHU5Fhkfh0i1S9pweBkXYHXKORBurR",
      "reference": "mSyZlrHISyhtoltUuEyJ-EG9ZhCvc6P6R4tiF7tjdOidiX40u1pvcG-iPyAolJEHcK1EmS1zXJR41bDJl3CN93WnRFWhXeTLvdZdHU5Fhkfh0i1S9pweBkXYHXKORBurR",
      "plus_code": {
        "compound_code": "+6DW1G Trung Hòa, Cầu Giấy, Hà Nội",
        "global_code": "LOC1+6DW1G"
      },
      "compound": {
        "commune": "Yên Hòa",
        "province": "Hà Nội"
      },
      "types": [
        "house_number"
      ],
      "name": "91 Trung Kính",
      "address": "Yên Hòa, Hà Nội",
      "deprecated_description": "91 Trung Kính, Trung Hòa, Cầu Giấy, Hà Nội",
      "deprecated_compound": {
        "district": "Cầu Giấy",
        "commune": "Trung Hòa",
        "province": "Hà Nội"
      }
    },
    {
      "address_components": [
        {
          "long_name": "Bluesea",
          "short_name": "Bluesea"
        },
        {
          "long_name": "91 Trung Kính",
          "short_name": "91 Trung Kính"
        },
        {
          "long_name": "Yên Hòa",
          "short_name": "Yên Hòa"
        },
        {
          "long_name": "Hà Nội",
          "short_name": "Hà Nội"
        }
      ],
      "formatted_address": "Bluesea, 91 Trung Kính, Yên Hòa, Hà Nội",
      "geometry": {
        "location": {
          "lat": 21.013672808000024,
          "lng": 105.79825090900005
        },
        "boundary": "ofg_CuvvdSjBLCf@kBMBg@"
      },
      "place_id": "SjvkG73jqUpihXomJx3ys9GeATVutC5OdeLNKP7Z-l_5-25deqAqcVna-2bO0bqW-fjhWr5lVwOxPr0oAoX_kfmKjbAS25eBte79JXZ9vn_Z6hVoJqQlSn3itjyKfCFLf",
      "reference": "SjvkG73jqUpihXomJx3ys9GeATVutC5OdeLNKP7Z-l_5-25deqAqcVna-2bO0bqW-fjhWr5lVwOxPr0oAoX_kfmKjbAS25eBte79JXZ9vn_Z6hVoJqQlSn3itjyKfCFLf",
      "plus_code": {
        "compound_code": "+J4VN Trung Hòa, Cầu Giấy, Hà Nội",
        "global_code": "LOC1+J4VN"
      },
      "compound": {
        "commune": "Yên Hòa",
        "province": "Hà Nội"
      },
      "types": [
        "building"
      ],
      "name": "Bluesea",
      "address": "91 Trung Kính, Yên Hòa, Hà Nội",
      "deprecated_description": "Tòa nhà Bluesea, 91 Trung Kính, Trung Hòa, Cầu Giấy, Hà Nội",
      "deprecated_compound": {
        "district": "Cầu Giấy",
        "commune": "Trung Hòa",
        "province": "Hà Nội"
      }
    },
    {
      "address_components": [
        {
          "long_name": "Công ty Cổ phần Công nghệ và Truyền thông Biển Xanh",
          "short_name": "Công ty Cổ phần Công nghệ và Truyền thông Biển Xanh"
        },
        {
          "long_name": "Tầng 6",
          "short_name": "Tầng 6"
        },
        {
          "long_name": "Tòa nhà BlueSea",
          "short_name": "Tòa nhà BlueSea"
        },
        {
          "long_name": "91 Trung Kính",
          "short_name": "91 Trung Kính"
        },
        {
          "long_name": "Yên Hòa",
          "short_name": "Yên Hòa"
        },
        {
          "long_name": "Hà Nội",
          "short_name": "Hà Nội"
        }
      ],
      "formatted_address": "Công ty Cổ phần Công nghệ và Truyền thông Biển Xanh, Tầng 6, Tòa nhà BlueSea, 91 Trung Kính, Yên Hòa, Hà Nội",
      "geometry": {
        "location": {
          "lat": 21.01369399600003,
          "lng": 105.79826308000008
        },
        "boundary": null
      },
      "place_id": "EmOMgxKlzGVlilFHPXY8R_3m2d4NFSZxkZqh3Bq3bhPZknFJCgRP7xqh5Kwu1dabEp8F0BLJniIZtp2MktGuU-nnBWQe2EffdYKRSskZhhO10nkGEsmGUhGO2STmEE__E",
      "reference": "EmOMgxKlzGVlilFHPXY8R_3m2d4NFSZxkZqh3Bq3bhPZknFJCgRP7xqh5Kwu1dabEp8F0BLJniIZtp2MktGuU-nnBWQe2EffdYKRSskZhhO10nkGEsmGUhGO2STmEE__E",
      "plus_code": {
        "compound_code": "+2AHY Trung Hòa, Cầu Giấy, Hà Nội",
        "global_code": "LOC1+2AHY"
      },
      "compound": {
        "commune": "Yên Hòa",
        "province": "Hà Nội"
      },
      "types": [
        "company"
      ],
      "name": "Công ty Cổ phần Công nghệ và Truyền thông Biển Xanh",
      "address": "Tầng 6, Tòa nhà BlueSea, 91 Trung Kính, Yên Hòa, Hà Nội",
      "deprecated_description": "Công ty Cổ phần Công nghệ và Truyền thông Biển Xanh, Tầng 6, Tòa nhà BlueSea, 91 Trung Kính, Trung Hòa, Cầu Giấy, Hà Nội",
      "deprecated_compound": {
        "district": "Cầu Giấy",
        "commune": "Trung Hòa",
        "province": "Hà Nội"
      }
    },
    {
      "address_components": [
        {
          "long_name": "43/91 Trung Kính",
          "short_name": "43/91 Trung Kính"
        },
        {
          "long_name": "Yên Hòa",
          "short_name": "Yên Hòa"
        },
        {
          "long_name": "Hà Nội",
          "short_name": "Hà Nội"
        }
      ],
      "formatted_address": "43/91 Trung Kính, Yên Hòa, Hà Nội",
      "geometry": {
        "location": {
          "lat": 21.01178451000004,
          "lng": 105.79653747400005
        },
        "boundary": null
      },
      "place_id": "EE6Xj5zYnp-zfmwqrn2fxrOub1q0JfpydTtkxJ6lwl8JOhWh6tm_gqRp-Y2LtgCaoeAlGuaEJMZhIkUYlrFKfvn6RQgO2CuCce79JXZ9vn_Z6hVoJUgmPqXitUiKfCOTf",
      "reference": "EE6Xj5zYnp-zfmwqrn2fxrOub1q0JfpydTtkxJ6lwl8JOhWh6tm_gqRp-Y2LtgCaoeAlGuaEJMZhIkUYlrFKfvn6RQgO2CuCce79JXZ9vn_Z6hVoJUgmPqXitUiKfCOTf",
      "plus_code": {
        "compound_code": "+63G73 Trung Hòa, Cầu Giấy, Hà Nội",
        "global_code": "LOC1+63G73"
      },
      "compound": {
        "commune": "Yên Hòa",
        "province": "Hà Nội"
      },
      "types": [
        "house_number"
      ],
      "name": "43/91 Trung Kính",
      "address": "Yên Hòa, Hà Nội",
      "deprecated_description": "91 Ngõ 43 Trung Kính, Trung Hòa, Cầu Giấy, Hà Nội",
      "deprecated_compound": {
        "district": "Cầu Giấy",
        "commune": "Trung Hòa",
        "province": "Hà Nội"
      }
    },
    {
      "address_components": [
        {
          "long_name": "Cửa hàng 91",
          "short_name": "Cửa hàng 91"
        },
        {
          "long_name": "91 Ngõ 43 Trung Kính",
          "short_name": "91 Ngõ 43 Trung Kính"
        },
        {
          "long_name": "Yên Hòa",
          "short_name": "Yên Hòa"
        },
        {
          "long_name": "Hà Nội",
          "short_name": "Hà Nội"
        }
      ],
      "formatted_address": "Cửa hàng 91, 91 Ngõ 43 Trung Kính, Yên Hòa, Hà Nội",
      "geometry": {
        "location": {
          "lat": 21.011780584000064,
          "lng": 105.79652819400008
        },
        "boundary": null
      },
      "place_id": "kb8rgRCehm5Ih0ioXX6G5HuHcZ-fbLKdYydDU6tTe8HtEYYwr2F4Inn6BRxyvboLieYZuHphhlddJkGUxqG6S9k-uSyF_lr-oer5IXH_Vnvd7hFsIqAiOnnmsUyOeCeXe",
      "reference": "kb8rgRCehm5Ih0ioXX6G5HuHcZ-fbLKdYydDU6tTe8HtEYYwr2F4Inn6BRxyvboLieYZuHphhlddJkGUxqG6S9k-uSyF_lr-oer5IXH_Vnvd7hFsIqAiOnnmsUyOeCeXe",
      "plus_code": {
        "compound_code": "+40BD Trung Hòa, Cầu Giấy, Hà Nội",
        "global_code": "LOC1+40BD"
      },
      "compound": {
        "commune": "Yên Hòa",
        "province": "Hà Nội"
      },
      "types": [
        "grocery_store"
      ],
      "name": "Cửa hàng 91",
      "address": "91 Ngõ 43 Trung Kính, Yên Hòa, Hà Nội",
      "deprecated_description": "Cửa hàng 91, 91 Ngõ 43 Trung Kính, Trung Hòa, Cầu Giấy, Hà Nội",
      "deprecated_compound": {
        "district": "Cầu Giấy",
        "commune": "Trung Hòa",
        "province": "Hà Nội"
      }
    }
  ],
  "status": "OK"
}

{
"compound_code": "+63G73 Trung Hòa, Cầu Giấy, Hà Nội",
"global_code": "LOC1+63G73"
},

"poiuyTREWqazx09876MNB==.bm9ybWFs"

 {
"long_name": "Thời trang Bim",
"short_name": "Thời trang Bim"
},
{
"long_name": "91 Ngõ 43 Trung Kính",
"short_name": "91 Ngõ 43 Trung Kính"
},
{
"long_name": "Yên Hòa",
"short_name": "Yên Hòa"
},
{
"long_name": "Hà Nội",
"short_name": "Hà Nội"
}

"CRdosr1ubzGqZwEhsJV2xKkCmeNrXbNmYY_3IMQoaBxeuLQhZq
YnZDX92dmu1_EUr.."

"location": {
"lat": 21.01178451000004,
"lng": 105.79653747400005
},

Chuyển đổi từ tọa độ sang địa chỉ Reverse Geocode

Định nghĩa

Reverse Geocode là quá trình chuyển đổi từ tọa độ (vĩ độ và kinh độ) thành địa chỉ cụ thể hoặc các thông tin mô tả vị trí như tên đường, thành phố, quốc gia. Dịch vụ này thường được sử dụng trong nhiều trường hợp khi có tọa độ của một vị trí nhất định, nhưng cần tìm hiểu địa chỉ hoặc thông tin cụ thể về địa điểm đó.

Cách thức hoạt động của Reverse geocode

Khác với Forward geocode, Reverse geocode thực hiện quá trình chuyển đổi ngược lại: từ một cặp tọa độ địa lý (vĩ độ, kinh độ) thành một địa chỉ cụ thể. Khi bạn cung cấp một vị trí (kinh độ, vĩ độ), hệ thống sẽ tìm kiếm trong cơ sở dữ liệu địa lý để xác định địa chỉ gần nhất với vị trí đó. Kết quả trả về có thể bao gồm số nhà, tên đường, thành phố và các thông tin chi tiết khác.

Cách thức tạo yêu cầu Reverse geocode

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?latlng=15.765075, 108.204474&limit=5&api_key={YOUR_API_KEY}&has_deprecated_administrative_unit=true

Tham số trong response trả về:

{
    "results": [
        {
            "address_components": [
                {
                    "long_name": "Duy Xuyên",
                    "short_name": "Duy Xuyên"
                },
                {
                    "long_name": "Đà Nẵng",
                    "short_name": "Đà Nẵng"
                }
            ],
            "formatted_address": "Duy Xuyên, Đà Nẵng",
            "geometry": {
                "location": {
                    "lat": 15.765075,
                    "lng": 108.204474
                },
                "boundary": "io`_Bee_sS}[wAmM_AgLy@uGMuGNaJfBeH~DkCdBy@b@g@[y@mG_AcDyBuCyCuC_C}AkBOsFf@eCfAmBjBkBdBiHrFaHlBcHTaRiBeEQ}B`@_JpE}CrA}BGoD_DgFaG_CsBwBw@{GS_EgBaIsLoFaF}EmAkIiAeEj@{Fr@cGk@}IgEwDsBgAoA?ApKoFpKgFlCuAPQGmAg@y@}AoBeA}Ae@}D[_Jg@sK@aLg@}KS}Dw@oEqCsEcOaQcRuNoHkJsGiLaHgNeJmOyCyHkBwI{CkMgEiTeDqLuAoKgAqDwE_FgG}HaE}F_DwIwI}YcGeNeD_I}AeBcDcDqCsCeCaEkBaIe@yFaAkDqAoByDyCsC_DiBoEgA{GyAeGcCiJkAaDqCaCwEyBgFcAeH_@{BGm@uCe@u@gAc@yCgAiDsAu@{@U}@@cANw@nAwBlDcG~@qB\\wA\\}CP{EJaJC{LDyICe\\CsFrJ[`@MN_A?iFhDY`@Vz@zBx@n@tEj@`FtA~BpBvCx@~RfBtKvBvF\\jDGvDgBhHeF`EkCdBg@|AHxBdAhCnBrCtDfBtBfHlBhMrBtNnB|JJnJHhIXdHxAvGtCfFrBbEnAzCZxGm@hE]tEHrIVlGA~B\\zBlC~DtDbCl@lFX`Fd@dA|@t@dDb@xDn@jAzEvChFfEdEpFpBdFlCbJvCvP`C`HrDxMvEdH~FzPhDvFxAvGhAlH`AvFx@f@jFFjSY~Eo@~G_A|B_@~@P`BhBpDxJvC`RhCdLxAzDdE`CpNtDz@`ExB`GnDdFnBvA`G|@vFGbJ?tDp@zElB`DvBdIhHtH~FrBfCr@lD\\zCDpCGbCm@hCiBfE}AjE]|CJfCp@`BrEjHfEpE~PhOtGjEdHfFpFpBhBPpGNhFU|DVdCz@fGlG~A`BrCdA`Db@|PzBfEt@Od@wAxEiC`HwCpI{CjHiA`Da@bCG`Di@hEoAxCaEvFyBbF}CrFsBrDo@~B_@lBEpC]lCcA|CaB~BoBbAyCl@oEjDeEnFaCtEkBdGaDtI{AdDcAtA_BfAgAJaG^mEp@yB~AsCxDcBzAcBn@cC\\gCXqBt@gAfB}@fFIvDRfB"
            },
            "place_id": "drtqhLmKubt1uUEJoVZFi3Wrd5ijaE10ar7wgBaLNkGh3hUVBk3i4j3-oXCT0QpuIXs5OTdtqk_BczyUN",
            "reference": "drtqhLmKubt1uUEJoVZFi3Wrd5ijaE10ar7wgBaLNkGh3hUVBk3i4j3-oXCT0QpuIXs5OTdtqk_BczyUN",
            "plus_code": null,
            "compound": {
                "commune": "Duy Xuyên",
                "province": "Đà Nẵng"
            },
            "types": [],
            "name": "Duy Xuyên",
            "address": "Đà Nẵng",
            "deprecated_description": "Duy Sơn, Duy Xuyên, Quảng Nam",
            "deprecated_compound": {
                "district": "Duy Xuyên",
                "commune": "Duy Sơn",
                "province": "Quảng Nam"
            }
        }
    ],
    "status": "OK"
}

{
"address_components": [
{
"long_name": "Duy Xuyên",
"short_name": "Duy Xuyên"
},
{
"long_name": "Đà Nẵng",
"short_name": "Đà Nẵng"
}

drtqhLmKubt1uUEJoVZFi3Wrd5ijaE10ar...