Hướng dẫn sử dụng Goong REST API

Trong blog hôm nay, các bạn sẽ được hướng dẫn cách sử dụng các REST API của Goong, bao gồm:

  • Geocode (trả về chi tiết địa điểm với input là tọa độ)
  • Direction (trả về tuyến đường với input là tọa độ điểm đi và điểm đến)
  • Autocomplete (trả về danh sách địa điểm được đề xuất với input là từ khóa tìm kiếm)
  • PlaceDetail (trả về chi tiết địa điểm với input là ID của địa điểm đó)
  • Distance Matrix (trả về tuyến đường cho tất cả những cặp tọa độ điểm đi/đến trong input)
  • Static Map (trả về png image hiển thị bản đồ và tuyến đường giữa 2 tọa độ đi/đến trong input)

Để dùng được SDK và API, các bạn cần keys/token. Hãy truy cập vào account.goong.io để tạo tài khoản, rồi tạo keys tại https://account.goong.io/keys. Xin lưu ý là bạn cần key cho API cho các dịch vụ REST API trên.

Cách sử dụng Geocode (lưu ý điền API key đã tạo ở bước trên tại <add your API key here>):

https://rsapi.goong.io/Geocode?latlng=20.9819927215576,105.864227294922&api_key=<add your API key here>

Expected Response:

{
   "plus_code":{

   },
   "results":[
      {
         "address_components":[
            {
               "long_name":"477A Tam Trinh",
               "short_name":"477A Tam Trinh"
            },
            {
               "long_name":"Tam Trinh",
               "short_name":"Tam Trinh"
            },
            {
               "long_name":"Phường Hoàng Văn Thụ",
               "short_name":"Phường Hoàng Văn Thụ"
            },
            {
               "long_name":"Quận Hoàng Mai",
               "short_name":"Quận Hoàng Mai"
            },
            {
               "long_name":"Thành phố Hà Nội",
               "short_name":"Thành phố Hà Nội"
            }
         ],
         "name":"477A Tam Trinh",
         "formatted_address":"Hoàng Văn Thụ, Hoàng Mai, Hà Nội",
         "geometry":{
            "location":{
               "lat":20.9819927215576,
               "lng":105.864227294922
            }
         },
         "place_id":"XJe60zNLPn2m9JLdqe3K5MA3bBDW7dwo",
         "plus_code":{

         },
         "types":[

         ]
      }
   ],
   "status":"OK"
}

Các bạn có thể thêm tham số limit=x để API trả về 1 list với x kết quả, như sau:

https://rsapi.goong.io/Geocode?latlng=20.9819927215576,105.864227294922&api_key=<add your API key here>&limit=2

Expected Results:

{
   "plus_code":{

   },
   "results":[
      {
         "address_components":[
            {
               "long_name":"477A Tam Trinh",
               "short_name":"477A Tam Trinh"
            },
            {
               "long_name":"Tam Trinh",
               "short_name":"Tam Trinh"
            },
            {
               "long_name":"Phường Hoàng Văn Thụ",
               "short_name":"Phường Hoàng Văn Thụ"
            },
            {
               "long_name":"Quận Hoàng Mai",
               "short_name":"Quận Hoàng Mai"
            },
            {
               "long_name":"Thành phố Hà Nội",
               "short_name":"Thành phố Hà Nội"
            }
         ],
         "name":"477A Tam Trinh",
         "formatted_address":"Hoàng Văn Thụ, Hoàng Mai, Hà Nội",
         "geometry":{
            "location":{
               "lat":20.9819927215576,
               "lng":105.864227294922
            }
         },
         "place_id":"XJe60zNLPn2m9JLdqe3K5MA3bBDW7dwo",
         "plus_code":{

         },
         "types":[

         ]
      },
      {
         "address_components":[
            {
               "long_name":"477 Tam Trinh",
               "short_name":"477 Tam Trinh"
            },
            {
               "long_name":"Tam Trinh",
               "short_name":"Tam Trinh"
            },
            {
               "long_name":"Phường Hoàng Văn Thụ",
               "short_name":"Phường Hoàng Văn Thụ"
            },
            {
               "long_name":"Quận Hoàng Mai",
               "short_name":"Quận Hoàng Mai"
            },
            {
               "long_name":"Thành phố Hà Nội",
               "short_name":"Thành phố Hà Nội"
            }
         ],
         "name":"477 Tam Trinh",
         "formatted_address":"Hoàng Văn Thụ, Hoàng Mai, Hà Nội",
         "geometry":{
            "location":{
               "lat":20.9820232391357,
               "lng":105.864219665527
            }
         },
         "place_id":"bYa6ewBEPyrMk2ydPwq9Dz38lnmp5OV0",
         "plus_code":{

         },
         "types":[

         ]
      }
   ],
   "status":"OK"
}

Cách sử dụng Direction (lưu ý điền API key đã tạo ở bước trên tại <add your API key here>):

https://rsapi.goong.io/Direction?origin=21.027719,105.785911&destination=21.025846,105.788325&api_key=<add your API key here>

Expected Response:

{
   "geocoded_waypoints":[

   ],
   "routes":[
      {
         "bounds":{

         },
         "legs":[
            {
               "distance":{
                  "text":"351 m",
                  "value":351
               },
               "duration":{
                  "text":"32 giây",
                  "value":32
               }
            }
         ],
         "overview_polyline":{
            "points":"k~i_C_itdS`@wDZm@NQDEDEDEDGBG@G@GZe@LOhDeBt@a@"
         },
         "warnings":[

         ],
         "waypoint_order":[

         ]
      }
   ]
}

Các bạn có thể thêm các tham số alternative:(boolean) (trả thêm các tuyến đường khác) hoặc vehicle:(string)//'car'|'bike'|'taxi'(trả về tuyến đường cho các loại phương tiện giao thông khác nhau), ví dụ:

https://rsapi.goong.io/Direction?origin=21.027719,105.785911&destination=21.029862,105.802219&api_key=<add your API key here>&alternatives=true&vehicle=taxi

Expected Results:

{
   "geocoded_waypoints":[

   ],
   "routes":[
      {
         "bounds":{

         },
         "legs":[
            {
               "distance":{
                  "text":"5 km",
                  "value":4522
               },
               "duration":{
                  "text":"8 phút",
                  "value":461
               }
            }
         ],
         "overview_polyline":{
            "points":"k~i_C_itdS`@wDZm@NQDEDEDEDGBG@G@GZe@LOhDeBrH{DnCwAv@c@bAk@XOfAo@jFsCx@c@hFoCjBaAb@Ub@Uf@UMWc@}@cAsBvBqCbAwAr@qAb@}@`@sBp@gDViAXkAj@mCiCw@{@a@aAm@{@eAq@eAoBeE?M?IISSe@IOUe@KWEECEGEICM[c@PcBx@sAp@u@`@g@\\s@l@mAnA}@fAa@f@OP{AhBsA~AKJYRULYJe@Hc@BOA[Ce@Gq@Mk@O{@[kAg@gAm@_Ak@gAy@IO{@aAu@o@uG_GB}Cd@oArDwJTu@B]CWGSIYIGEGg@[Mn@Ot@UhAQn@oDxIO^U\\"
         },
         "warnings":[

         ],
         "waypoint_order":[

         ]
      },
      {
         "bounds":{

         },
         "legs":[
            {
               "distance":{
                  "text":"5 km",
                  "value":4990
               },
               "duration":{
                  "text":"8 phút",
                  "value":491
               }
            }
         ],
         "overview_polyline":{
            "points":"k~i_C_itdS`@wDZm@NQDEDEDEDGBG@G@G?I?GAIAECGCEEEEEGEGCICIAG?I?IBG@IDi@H[FK?eEo@uDg@q@KeAQkF{@yGaA}F_AyAUkDk@o@SGCMGMMa@_@eA_@[IwDu@_C_@oGKYg@dAyAv@eAh@u@~@qArDeFr@_APSTSNIJOFQBO@KAOGQEKKEKEa@q@Wa@QOIGKCaBeBqAyAOWKg@IoBDYA]C_AAe@E}ACsA@[B[D[HYDMNa@r@eAfIaL~B_DrEeGnAiBFIXa@TYDEzGrDhBdAh@`@dAx@dGjFf@f@f@d@d@^DBZGn@e@d@}@Rg@d@oArDwJTu@B]CWGSIYIGEGg@[Mn@Ot@UhAQn@oDxIO^U\\"
         },
         "warnings":[

         ],
         "waypoint_order":[

         ]
      }
   ]
}

Cách sử dụng Autocomplete (lưu ý điền API key đã tạo ở bước trên tại <add your API key here>), input:

https://rsapi.goong.io/Place/AutoComplete?input=20 Hoàng Quốc Việt&api_key=<add your API key here>

Expected Results:

{
   "predictions":[
      {
         "description":"20 Hoàng Quốc Việt, Nghĩa Đô, Cầu Giấy, Hà Nội",
         "matched_substrings":[

         ],
         "place_id":"xElXN1DBLJb7kz6vzyVkRrjW3Oz80Y5n",
         "structured_formatting":{
            "main_text":"20 Hoàng Quốc Việt",
            "secondary_text":"Nghĩa Đô, Cầu Giấy, Hà Nội"
         },
         "terms":[

         ],
         "types":[
            ""
         ],
         "has_children":false
      }
   ],
   "status":"OK"
}

API này cũng có các tham số phụ khác, như location: (string)//ví dụ:20.981971,105.864323(tọa độ tìm kiếm trung tâm), limit:(int)(limit số kết quả đề xuất), radius:(int)(bán kính tìm kiếm quanh tọa độ location bằng kilomet, mặc định là 50 km). Ví dụ:

https://rsapi.goong.io/Place/AutoComplete?input=20 Hoàng Quốc Việt&api_key=<add your API key here>&location=21.044662,105.800412&radius=5&limit=5

Expected Results:

{
   "predictions":[
      {
         "description":"20 Ngõ 234 Hoàng Quốc Việt, Phường Cổ Nhuế 1, Bắc Từ Liêm, Hà Nội",
         "matched_substrings":[

         ],
         "place_id":"4LmgDZJaO3vB9g0j3wmkE0AelbW26zqw",
         "structured_formatting":{
            "main_text":"20 Ngõ 234 Hoàng Quốc Việt",
            "secondary_text":"Phường Cổ Nhuế 1, Bắc Từ Liêm, Hà Nội"
         },
         "terms":[

         ],
         "types":[
            ""
         ],
         "has_children":false
      },
      {
         "description":"20 Hoàng Quốc Việt, Nghĩa Đô, Cầu Giấy, Hà Nội",
         "matched_substrings":[

         ],
         "place_id":"xElXN1DBLJb7kz6vzyVkRrjW3Oz80Y5n",
         "structured_formatting":{
            "main_text":"20 Hoàng Quốc Việt",
            "secondary_text":"Nghĩa Đô, Cầu Giấy, Hà Nội"
         },
         "terms":[

         ],
         "types":[
            ""
         ],
         "has_children":false
      }
   ],
   "status":"OK"
}

Cách sử dụng PlaceDetail với placeID xElXN1DBLJb7kz6vzyVkRrjW3Oz80Y5n mà chúng ta đã có được từ response Autocomplete trên (lưu ý điền API key đã tạo ở bước trên tại <add your API key here>):

https://rsapi.goong.io/Place/Detail?placeid=xElXN1DBLJb7kz6vzyVkRrjW3Oz80Y5n&api_key=<add your API key here>

Expected Results:

{
   "result":{
      "formatted_address":"Nghĩa Đô, Cầu Giấy, Hà Nội",
      "geometry":{
         "location":{
            "lat":21.0463771820068,
            "lng":105.799339294434
         }
      },
      "name":"20 Hoàng Quốc Việt"
   },
   "status":"OK"
}

Cách sử dụng DistanceMatrix với 1 điểm đi và 3 điểm đến (lưu ý điền API key đã tạo ở bước trên tại <add your API key here>):

https://rsapi.goong.io/DistanceMatrix?origins=20.981971,105.864323&destinations=21.031011,105.783206|21.022328,105.790480|21.016665,105.788774&api_key=<add your API key here>

Expected Results:

{
   "rows":[
      {
         "elements":[
            {
               "status":"OK",
               "duration":{
                  "text":"18 phút",
                  "value":1061
               },
               "distance":{
                  "text":"16 km",
                  "value":15955
               }
            },
            {
               "status":"OK",
               "duration":{
                  "text":"17 phút",
                  "value":1014
               },
               "distance":{
                  "text":"15 km",
                  "value":14620
               }
            },
            {
               "status":"OK",
               "duration":{
                  "text":"15 phút",
                  "value":928
               },
               "distance":{
                  "text":"14 km",
                  "value":13549
               }
            }
         ]
      }
   ]
}

Cũng như với Direction, các bạn có thể thêm các tham số phụ như vehicletype:(string)//'fastest'|'shortest'.

Cách sử dụng StaticMap (lưu ý điền API key đã tạo ở bước trên tại <add your API key here>):

https://rsapi.goong.io/staticmap/route?origin=10,105&destination=21,105&api_key=<add your API key here>

Expected Result:

Cảm ơn các bạn đã theo dõi đến đây, now start coding!!