Autocomplete Posts

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!!

Hướng dẫn sử dụng Goong SDK trên JavaScript

Trong bài viết hôm nay, các bạn sẽ được hướng dẫn cách tích hợp MapView cơ bản của Goong vào 1 trang web bằng JavaScript. Đến cuối tutorial, các bạn đã có thể hoàn thành một trang web với các chức năng map view, tìm kiếm với đề xuất kết quả và ghim pin trên bản đồ.

Để 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à cần 1 key cho API và 1 key cho Map Tiles.

Bước 1 – Tạo MapView: ( https://docs.goong.io/js/guide )
Include các file JavaScript và CSS cần thiết:

<script src='https://cdn.jsdelivr.net/npm/@goongmaps/goong-js@1.0.2/dist/goong-js.js'></script>
<link href="https://cdn.jsdelivr.net/npm/@goongmaps/goong-js@1.0.2/dist/goong-js.css" rel="stylesheet" />

Tạo một HTML element có chứa MapView với đoạn code dưới, thay <your access token here> bằng key Map Tiles đã tạo ở bước trên. Các bạn có thể tùy chỉnh kích thước với 2 tham số widthheightvà thay đổi tọa độ trung tâm (long, lat), mức zoom khởi đầu tại center:zoom: :

<div id='map' ></div>
<script>
goongjs.accessToken = '<your access token here>';
var map = new goongjs.Map({
    container: 'map',
    style: 'https://tiles.goong.io/assets/goong_map_web.json'
    center: [105.7938073,21.0244247],
    zoom: 15 
});
</script>

Add thêm button để thể hiện map full màn hình với method addControl:

<div id='map' ></div>
<script>
goongjs.accessToken = '<your access token here>';
var map = new goongjs.Map({
    container: 'map',
    style: 'https://tiles.goong.io/assets/goong_map_web.json'
    center: [105.7938073,21.0244247],
    zoom: 15 
});
map.addControl(new goongjs.FullscreenControl());
</script>

Add thêm button để hiển thị tọa độ người dùng (trình duyệt sẽ yêu cầu truy cập quyền location):

<div id='map' ></div>
<script>
goongjs.accessToken = '<your access token here>';
var map = new goongjs.Map({
    container: 'map',
    style: 'https://tiles.goong.io/assets/goong_map_web.json'
    center: [105.7938073,21.0244247],
    zoom: 15 
});
map.addControl(
        new goongjs.GeolocateControl({
            positionOptions: {
                enableHighAccuracy: true
            },
            trackUserLocation: true
        })
);
</script>

Add Navigation Control cho MapView:

<div id='map' ></div>
<script>
goongjs.accessToken = '<your access token here>';
var map = new goongjs.Map({
    container: 'map',
    style: 'https://tiles.goong.io/assets/goong_map_web.json'
    center: [105.7938073,21.0244247],
    zoom: 15 
});
map.addControl(new goongjs.NavigationControl());
</script>

Dùng control element goong-geocoder để search các địa điểm qua Goong Autocomplete API.

Include file JavaScript cần thiết:

<script src='https://cdn.jsdelivr.net/npm/@goongmaps/goong-geocoder@1.0.2/dist/goong-geocoder.min.js'></script>
<link href="https://cdn.jsdelivr.net/npm/@goongmaps/goong-geocoder@1.0.2/dist/goong-geocoder.css" rel="stylesheet" type="text/css"/>

<!-- Promise polyfill script required to use Goong Geocoder in IE 11 -->
<script src="https://cdn.jsdelivr.net/npm/es6-promise@4/dist/es6-promise.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/es6-promise@4/dist/es6-promise.auto.min.js"></script>

Dùng control element goong-geocoder để search các địa điểm qua Goong Autocomplete API. Điền API key các bạn đã tạo tại <add your API key here>.

<div id="map"></div>
<script>
  goongjs.accessToken = "<add your Maptiles key here>";
    var map = new goongjs.Map({
        container: 'map', // container id
        style: 'https://tiles.goong.io/assets/goong_map_web.json', // stylesheet location
        center: [105, 21], // starting position [lng, lat]
        zoom: 9 // starting zoom
    });
map.addControl(
new GoongGeocoder({
accessToken: "<add your API key here>",
goongjs: goongjs
})
);
</script>

Nếu muốn tùy chỉnh kích cỡ của control goong-geocoder, các bạn có thể dùng cách sau:

<style>
.geocoder {
position: absolute;
z-index: 1;
width: 50%;
left: 50%;
margin-left: -25%;
top: 20px;
}
.goongjs-ctrl-geocoder {
min-width: 100%;
}
</style>
<div id="map"></div>
<div id="geocoder" class="geocoder"></div>
 
<script>
	goongjs.accessToken = "<add your Maptiles key here>";
    var map = new goongjs.Map({
        container: 'map', // container id
        style: 'https://tiles.goong.io/assets/goong_map_web.json', // stylesheet location
        center: [105, 21], // starting position [lng, lat]
        zoom: 9 // starting zoom
});
 
var geocoder = new GoongGeocoder({
accessToken: "<add your API key here>",
goongjs: goongjs
});
 
document.getElementById('geocoder').appendChild(geocoder.onAdd(map));
</script>