GEOCODE – LẤY THÔNG TIN ĐỊA CHỈ

TỔNG QUAN

Geocode là API chuyển đổi địa chỉ (địa chỉ nhà, cửa hàng…) thành  tọa độ địa lý (kinh độ, vĩ độ ) và place_id hoặc ngược lại. API này cho phép bạn chuyển đổi địa chỉ hoặc tọa độ địa lý thành thông tin địa lý khác nhau như vị trí, mã vùng, quận, và thậm chí là địa điểm kinh doanh.

Goong Geocode API có 3 hình thức chính:

• Reverse geocode: Chuyển đổi từ tọa độ địa lý (kinh độ, vĩ độ)  sang địa chỉ
• Forward geocode: Chuyển đổi từ địa chỉ ra tọa độ
• Nhận thông tin chi tiết về địa điểm theo place_id

Lý do sử dụng Geocode

Geocode được sử dụng cho trang web hoặc ứng dụng di động khi bạn cần chuyển đổi địa chỉ thành tọa độ để hiển thị trên bản đồ, hoặc ngược lại chuyển đổi tọa độ thành địa chỉ, nhằm giúp hiển thị nội dung ứng dụng trên các bản đồ thuộc nền tảng Goong.

Bạn có thể sử dụng Geocode API khi đã có địa chỉ đầy đủ, ví dụ như “226 Vạn Phúc, Liễu Giai, Ba Đình, Hà Nội”.

Geocode hoạt động như thế nào?

• Forward geocode: Chuyển đổi các địa chỉ như “226 Vạn Phúc, Liễu Giai, Ba Đình, Hà Nội” thành toạ độ vĩ độ và kinh độ. Bạn có thể sử dụng những tọa độ này để đặt điểm đánh dấu trên bản đồ hoặc căn giữa hay định vị lại bản đồ trong khung xem.
• Reverse geocode: Chuyển đổi vĩ độ/kinh độ hoặc place_id thành địa chỉ có thể đọc được. Bạn có thể sử dụng địa chỉ cho nhiều trường hợp, bao gồm cả giao hàng hoặc đến lấy hàng.

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: /geocode

Phương thức: GET

CHUYỂN ĐỔI TỪ TỌA ĐỘ SANG ĐỊA CHỈ 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…

Ví dụ:

Đầu vào: 91 Trung Kính, Trung Hòa, Cầu Giấy, Hà Nội

Kết quả đầu ra: 21.0137443130001,105.798346108

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

Ví dụ về request:

curl 'https://rsapi.goong.io/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}'

Ví dụ về response:

application/json

{
  "plus_code": {},
  "results": [
    {
      "address_components": [
        {
          "long_name": "Sảnh đón/trả khách",
          "short_name": "Sảnh đón/trả khách"
        },
        {
          "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": "Trung Hòa",
          "short_name": "Trung Hòa"
        },
        {
          "long_name": "Cầu Giấy",
          "short_name": "Cầu Giấy"
        },
        {
          "long_name": "Hà Nội",
          "short_name": "Hà Nội"
        }
      ],
      "formatted_address": "Sảnh đón/trả khách, Tòa nhà Bluesea, 91 Trung Kính, Trung Hòa, Cầu Giấy, Hà Nội",
      "geometry": {
        "location": {
          "lat": 21.0137210140001,
          "lng": 105.798261367
        }
      },
      "place_id": "ycg/XqGmIbYRNpFn61oPzIloTKrtDcs/jGfpESyuqFaYonQl1TEh63TyXS0HXUeN2zAqvsElmxtFcuPT6Ca4/A==.bm9ybWFs",
      "reference": "C0x/fNfYy5guordl7DF4fTotMNqwqC82TT0EKXo1olSmGFMYBQ2fOG60iRY_G8r3TTnv1RM0LdHVFW3R1B/uNw==.bm9ybWFs",
      "plus_code": {
        "compound_code": "+J4VO Trung Hòa, Cầu Giấy, Hà Nội",
        "global_code": "LOC1+J4VO"
      },
      "types": []
    },
    {
      "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": "Trung Hòa",
          "short_name": "Trung Hòa"
        },
        {
          "long_name": "Cầu Giấy",
          "short_name": "Cầu Giấy"
        },
        {
          "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, Trung Hòa, Cầu Giấy, Hà Nội",
      "geometry": {
        "location": {
          "lat": 21.013693996,
          "lng": 105.79826308
        }
      },
      "place_id": "lurFHQGTOE3WAR1zyIeXmSYmz/KufpERlwXh6PY8XFdCeu1a47r2pTRDo2/wEoAv7Z5lbZA20CRMqOtNMoTfYw==.bm9ybWFs",
      "reference": "pg7nOP5oMqoWSUJ9lF1baRaEw8Zw7O1GYsLuYIH/z2c6xNZpmKasJ1zmNjfwRF5w/foeeffqrVZ1wi8arP3FEQ==.bm9ybWFs",
      "plus_code": {
        "compound_code": "+2AHY Trung Hòa, Cầu Giấy, Hà Nội",
        "global_code": "LOC1+2AHY"
      },
      "types": []
    },
    {
      "address_components": [
        {
          "long_name": "Công ty CP Công nghệ bản đồ số Imap",
          "short_name": "Công ty CP Công nghệ bản đồ số Imap"
        },
        {
          "long_name": "Tầng 5",
          "short_name": "Tầng 5"
        },
        {
          "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": "Trung Hòa",
          "short_name": "Trung Hòa"
        },
        {
          "long_name": "Cầu Giấy",
          "short_name": "Cầu Giấy"
        },
        {
          "long_name": "Hà Nội",
          "short_name": "Hà Nội"
        }
      ],
      "formatted_address": "Công ty CP Công nghệ bản đồ số Imap, Tầng 5, Tòa nhà Bluesea, 91 Trung Kính, Trung Hòa, Cầu Giấy, Hà Nội",
      "geometry": {
        "location": {
          "lat": 21.0136939070001,
          "lng": 105.798255672
        }
      },
      "place_id": "7RjkxCbg/ilVed0U8BDQvPbBepxqvUw5Eu_ESr_S_kC/PNKRxe5CA6UFaagaro5NBc5TLLA_V21uDgIgfB0Byw==.bm9ybWFs",
      "reference": "",
      "plus_code": {
        "compound_code": "+J4VP Trung Hòa, Cầu Giấy, Hà Nội",
        "global_code": "LOC1+J4VP"
      },
      "types": []
    },
    {
      "address_components": [
        {
          "long_name": "91 Trung Kính",
          "short_name": "91 Trung Kính"
        },
        {
          "long_name": "Trung Hòa",
          "short_name": "Trung Hòa"
        },
        {
          "long_name": "Cầu Giấy",
          "short_name": "Cầu Giấy"
        },
        {
          "long_name": "Hà Nội",
          "short_name": "Hà Nội"
        }
      ],
      "formatted_address": "91 Trung Kính, Trung Hòa, Cầu Giấy, Hà Nội",
      "geometry": {
        "location": {
          "lat": 21.0137625240001,
          "lng": 105.798267363
        }
      },
      "place_id": "Hobn8WqBW6rsKtKq2PDrVKp4BJNRtiILxTQbB__muXgRB3v8GRDTfkp_6lc4cbLw/5PUgWrMDrSI/xlqDBt5XA==.bm9ybWFs",
      "reference": "o/QzXNc_eBKsOWX6kdbOcABtO4zUQz0lzdK1jpi0R__J2vFKeRAM2VSYo38AfaShP/7qpUhrwc0l/t/AIYwRnQ==.bm9ybWFs",
      "plus_code": {
        "compound_code": "+6DW1G Trung Hòa, Cầu Giấy, Hà Nội",
        "global_code": "LOC1+6DW1G"
      },
      "types": []
    },
    {
      "address_components": [
        {
          "long_name": "Phở Lý Quốc Sư",
          "short_name": "Phở Lý Quốc Sư"
        },
        {
          "long_name": "89 Trung Kính",
          "short_name": "89 Trung Kính"
        },
        {
          "long_name": "Trung Hòa",
          "short_name": "Trung Hòa"
        },
        {
          "long_name": "Cầu Giấy",
          "short_name": "Cầu Giấy"
        },
        {
          "long_name": "Hà Nội",
          "short_name": "Hà Nội"
        }
      ],
      "formatted_address": "Phở Lý Quốc Sư, 89 Trung Kính, Trung Hòa, Cầu Giấy, Hà Nội",
      "geometry": {
        "location": {
          "lat": 21.0137443130001,
          "lng": 105.798346108
        }
      },
      "place_id": "CRdosr1ubzGqZwEhsJV2xKkCmeNrXbNmYY_3IMQoaBxeuLQhZqYnZDX92dmu1_EUr7SNa9oZcEdGn0w6Ln5J1A==.bm9ybWFs",
      "reference": "hvQsDQGiINkZG7D82VhHBzyFnHdPRTtU3Gg6Xek6b_LPmrVmPWd6XSZgVEHZtrTX/lV8FICmrhROonRV5FHT4yE==.bm9ybWFs",
      "plus_code": {
        "compound_code": "+4V0P Trung Hòa, Cầu Giấy, Hà Nội",
        "global_code": "LOC1+4V0P"
      },
      "types": []
    }
  ],
  "status": "OK"
}

Khi Geocode trả về kết quả sẽ đặt các kết quả đó vào một mảng Results (JSON). Ngay cả khi Geocode không trả về kết quả nào (chẳng hạn như khi địa chỉ không tồn tại), Geocode vẫn trả về một Results (JSON) với lỗi tương ứng. 

CHUYỂN ĐỔI TỪ ĐỊA CHỈ SANG TỌA ĐỘ  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.

Ví dụ về request:

curl 'https://rsapi.goong.io/geocode?latlng=20.981971%2C105.864323&api_key={YOUR_API_KEY}'

Ví dụ về response:

{
  "plus_code": {},
  "results": [
    {
      "address_components": [
        {
          "long_name": "91 Trung Kính",
          "short_name": "91 Trung Kính"
        },
        {
          "long_name": "Trung Hòa",
          "short_name": "Trung Hòa"
        },
        {
          "long_name": "Cầu Giấy",
          "short_name": "Cầu Giấy"
        },
        {
          "long_name": "Hà Nội",
          "short_name": "Hà Nội"
        }
      ],
      "formatted_address": "91 Trung Kính, Trung Hòa, Cầu Giấy, Hà Nội",
      "geometry": {
        "location": {
          "lat": 21.0137625240001,
          "lng": 105.798267363
        }
      },
      "place_id": "Hobn8WqBW6rsKtKq2PDrVKp4BJNRtiILxTQbB__muXgRB3v8GRDTfkp_6lc4cbLw/5PUgWrMDrSI/xlqDBt5XA==",
      "reference": "o/QzXNc_eBKsOWX6kdbOcABtO4zUQz0lzdK1jpi0R__J2vFKeRAM2VSYo38AfaShP/7qpUhrwc0l/t/AIYwRnQ==",
      "plus_code": {
        "compound_code": "+6DW1G Trung Hòa, Cầu Giấy, Hà Nội",
        "global_code": "LOC1+6DW1G"
      },
      "types": []
    },
    {
      "address_components": [
        {
          "long_name": "91 Ngõ 43 Trung Kính",
          "short_name": "91 Ngõ 43 Trung Kính"
        },
        {
          "long_name": "Trung Hòa",
          "short_name": "Trung Hòa"
        },
        {
          "long_name": "Cầu Giấy",
          "short_name": "Cầu Giấy"
        },
        {
          "long_name": "Hà Nội",
          "short_name": "Hà Nội"
        }
      ],
      "formatted_address": "91 Ngõ 43 Trung Kính, Trung Hòa, Cầu Giấy, Hà Nội",
      "geometry": {
        "location": {
          "lat": 21.01178451,
          "lng": 105.796537474
        }
      },
      "place_id": "ytdKslLHBd1_mSnLu_bQHGu1yZyLeBt9haGgyFDN1EIOy7I9uEQyTmRkyNZL3BRpT_Knj31YK/Irv3KkEIIZqw==",
      "reference": "nP7fBjweFzWzkU8gq/ki_xEAF3fpVoZ3aQcfXx4ZRHX7QaQPNBPpNToMKx1KZw09gWUhpnSdXJSLowB4qFlCMg==",
      "plus_code": {
        "compound_code": "+63G73 Trung Hòa, Cầu Giấy, Hà Nội",
        "global_code": "LOC1+63G73"
      },
      "types": []
    },
    {
      "address_components": [
        {
          "long_name": "Trung Kính",
          "short_name": "Trung Kính"
        },
        {
          "long_name": "Trung Hòa",
          "short_name": "Trung Hòa"
        },
        {
          "long_name": "Cầu Giấy",
          "short_name": "Cầu Giấy"
        },
        {
          "long_name": "Hà Nội",
          "short_name": "Hà Nội"
        }
      ],
      "formatted_address": "Trung Kính, Trung Hòa, Cầu Giấy, Hà Nội",
      "geometry": {
        "location": {
          "lat": 21.01200742,
          "lng": 105.798556266
        }
      },
      "place_id": "4PhN5GTxC3Txq1qu_KZ_Wb0/fTn7CqblD5melLEhPCrWDoxqkBxTsLTWmYCJnM8gAREUdOKZVNHyHTYAelWOZw==",
      "reference": "Ltd3mU697w2W10zYKNvWxB6aK8CT45xU8y2B7hzpgt8M0an4e4G3tz7WFP27QH56DCOVFFR1IAT0McC5hJtSmA==",
      "plus_code": {
        "compound_code": "+ALSA Trung Hòa, Cầu Giấy, Hà Nội",
        "global_code": "LOC1+ALSA"
      },
      "types": []
    },
    {
      "address_components": [
        {
          "long_name": "95 Trung Kính",
          "short_name": "95 Trung Kính"
        },
        {
          "long_name": "Trung Hòa",
          "short_name": "Trung Hòa"
        },
        {
          "long_name": "Cầu Giấy",
          "short_name": "Cầu Giấy"
        },
        {
          "long_name": "Hà Nội",
          "short_name": "Hà Nội"
        }
      ],
      "formatted_address": "95 Trung Kính, Trung Hòa, Cầu Giấy, Hà Nội",
      "geometry": {
        "location": {
          "lat": 21.0138168300001,
          "lng": 105.79788971
        }
      },
      "place_id": "mUuwMwTPf5/1WFznDr94rtLvQffNhj1NzWQqDJqgsdUfCqTZdUcHTTav64BxPOC6dSdgZ9WUmwARwQlhmYonvA==",
      "reference": "lPHbKnLx64d2Ikp35RrFcdRphjayJn2rjapjNhjPuBmPxB9GzirgM6NT0OH65gG2Mf4qGswZXQ8d6U4XBfltjQ==",
      "plus_code": {
        "compound_code": "+6DW1M Trung Hòa, Cầu Giấy, Hà Nội",
        "global_code": "LOC1+6DW1M"
      },
      "types": []
    },
    {
      "address_components": [
        {
          "long_name": "93 Trung Kính",
          "short_name": "93 Trung Kính"
        },
        {
          "long_name": "Trung Hòa",
          "short_name": "Trung Hòa"
        },
        {
          "long_name": "Cầu Giấy",
          "short_name": "Cầu Giấy"
        },
        {
          "long_name": "Hà Nội",
          "short_name": "Hà Nội"
        }
      ],
      "formatted_address": "93 Trung Kính, Trung Hòa, Cầu Giấy, Hà Nội",
      "geometry": {
        "location": {
          "lat": 21.0138434450029,
          "lng": 105.798052001
        }
      },
      "place_id": "xFchTd18UNmq7/rWipBrI6LtqEcDdReZ8cGV3mxeK4yxmmL7hZat/i8cLBdGhdaeNYFQLk4H5AuP2ntIHfS7EQ==",
      "reference": "dMG3Lmo6Rux8NsEd9lwoDGUOH22aZbMdzDiMy1RhS73mM/uA0rZsX2M0y0Wm990nx4PGw1jd54YkUeqLzySwaQ==",
      "plus_code": {
        "compound_code": "+6DW1I Trung Hòa, Cầu Giấy, Hà Nội",
        "global_code": "LOC1+6DW1I"
      },
      "types": []
    }
  ],
  "status": "OK"
}