地址定位與查詢週邊資訊
API使用範例：地址定位與查詢週邊資訊
情境假設：
這個範例結合了地址定位以及環域查詢兩項不同的服務，讓使用者藉由地址定
位功能先取得一個位置點，再以這個位置點作為環域中心來針對特定主題地圖進行查
詢。正常使用環域查詢時，使用者必須輸入一個中心點坐標來進行後續的查詢動作，
不過一般的使用者往往無法得知欲查詢的精確坐標點位，這個時候就可以藉由地址定
位的方式來設定環域的中心點。
此範例示範查詢的主題地圖為「避難收容處所」，使用者利用一個自行輸入的地址及自訂環域範圍後，即可查到該地址一定範圍內的所有消防單位位置及其相關資訊。
TGOS 3D API建置方式：
1. 建立地址定位服務
建立基本地圖之後，此範例的第一個步驟便是建立一個地址定位服務，首先於事先建立好的
文字輸入框中取得網站使用者自行輸入的地址字串，該輸入框的ID為「Address」。
var Add = document.getElementById('Address').value; //取得文字輸入框內的地址
接著宣告一個定位服務物件「TELocateService」。
var LService = newTGOS.TELocateService(); //宣告一個新的定位服務
在TGOS 3D API中，「TELocateService」定位服務可以用來執行地址定位、地標定位、
道路定位等各種不同的定位方法，為了滿足不同定位方式的需求，我們可以藉由設定執行時所輸
入的不同參數，來呼叫各種不同的定位方式。以地址定位來說，在執行定位時所輸入的參數
「request」內，就必須加入一個「address」參數來進行地址定位。另外在範例中執行定位的方
法為「locateTWD97()」，代表定位完成後所得到的定位點坐標為台灣97二度分帶坐標系統格式。
定位完成後的結果及定位狀態分別透過回傳函式的第一個參數（result）和第二個參數（status）
進行傳遞，開發者分別取出這兩個參數後即可進行後續的開發動作。
var request = { //設定定位所需的參數, 使用address進行地址定位
address: Add
};
LService.locateTWD97(request,function(result, status){
//進行定位查詢, 並指定回傳資訊為TWD97坐標系統
進行定位後，所有後續的工作（取得定位坐標、環域查詢......）全部都建立在回傳函式的區段
內開發。
2. 環域查詢：
2.1 判斷地址定位狀態：
如上一個段落所述，進行地址定位動作後的回傳函式內包含了定位的狀態參數「status」，
由於我們無法預期網頁使用者是否會輸入正確的地址來進行定位，為了避免後續的程式由於錯誤
的輸入地址而無法往下執行，在這個部份我們會先針對定位的狀態來進行判斷，當伺服器回傳定
位成功的狀態之後，才繼續進行後續的程式。
if (status != 'OK') { //確認該查詢地址是否可以查詢成功
alert(status); //若該地址無法進行查詢則顯示錯誤狀態碼
return;
}
2.2 進行環域查詢：
確定定位動作正確執行後，首先我們先宣告一個變數「loc」，再透過定位結果「result」來
取得定位的坐標。該坐標為一個「TEPoint」物件。
var loc = result[0].geometry.location; //利用geometry.location取得地址點位(TEPoint)
接著於事先建立於網頁上的另一個輸入框（ID為「BufferDist」）中取得使用者自訂的環域
半徑。
var radius = parseFloat(document.getElementById("BufferDist").value);
之後將地址點位（loc）以及環域半徑（radius）設定為環域查詢的參數。
var queryRequst = { //設定點環域查詢條件, 包含圓心(loc)及半徑(radius)
position: loc,
distance: radius
};
之後就可以直接進行環域查詢了，範例中已經事先於函式外建立好了一個查詢服務物件
「TEPointBuffer()」，只要使用查詢服務的「identify」方法即可進行環域查詢。該方法內的第
一、第二個參數分別為服務代碼以及圖層代碼，範例中使用圖層「全國消防局」進行查詢，因此
服務代碼和圖層代碼分別為「TGOS.TEMapServiceId.FIREDEPARTMENT」以及
「TGOS.TEMapId.FIREDEPARTMENT」。
方法「identify」內的第三個參數為輸入的參數，在此填入先前宣告的查詢條件
「queryRequest」即可；第四個參數為坐標系統設定；第五個參數為回傳函式，和定位服務一
樣，環域查詢的回傳函式同樣包含了查詢結果陣列「result」及查詢狀態「status」。完整的環域
查詢方法如下---
Query.identify(TGOS.TEMapServiceId.FIREDEPARTMENT, TGOS.TEMapId.
FIREDEPARTMENT, queryRequst, function(result, status){
2.3 繪出查詢結果：
環域查詢的結果「result」中，可分別使用其屬性「fieldAttr」和「position」來取出查詢
結果的文字屬性和位置，兩者皆為陣列結構，可存入多筆查詢結果。
var attris = result.fieldAttr; //取得圖徵屬性
var pts = result.position; //取得圖徵點位
取出點位後建立一個迴圈，以查詢結果數量作為迴圈的大小進行標記點繪製（使用TEMarker
物件），並取出每筆查詢結果的第二筆屬性（消防隊名稱）作為標記點的標題。最後將所有標記
點存入另一個陣列內，便於日後的管理工作。
for (var i = 0; i < pts.length; i++) {
var txt = attris[i][1];
//建立迴圈後, 以字串方式組合屬性結果, attris[0]為查詢到的第一個圖徵, attris[0][0]為
第一個圖徵的第一個屬性, 依此類推
var marker = newTGOS.TEMarker(pMap, pts[i], txt, img); //在迴圈內建立
TEMarker物件, 將查詢到的所有主題圖徵繪出
markers.push(marker); //將標記點加入到markers陣列
}
2.4 繪製環域示意範圍：
查詢完畢後，為了讓使用者更清楚地瞭解環域的範圍及中心點位置，範例中另外將這兩項資
訊以圖形的方式繪出。其中環域的中心點位即為步驟一的地址定位結果，因此只需要建立一個新
的「TEMarker」物件將該定位結果繪出即可。其中的參數「loc」為定位結果的坐標點；「Add」
為使用者輸入的地址字串。
LocMarker = newTGOS.TEMarker(pMap, loc, Add);
再來使用該中心點位以及環域的半徑進行環域圖形的繪製。在範例中首先先建立一個圓形資
料結構「TECircle」，再將圓形資料結構轉換為繪圖物件「TEFill」，最後取出該圖形的邊界進
行地圖縮放，來達到類似定位的效果。
var circle = new TGOS.TECircle(); //建立一個圓形物件(TECircle)
circle.setCenter(loc); //以滑鼠點擊位置為圓心
circle.setRadius(radius); //設定半徑
var pgnOption = { //設定圖形樣式
fillColor: "#ffff00",
fillOpacity : 0.3,
strokeWeight : 3,
strokeColor : "#ee0000"
};
BufferArea = newTGOS.TEFill(pMap, circle, pgnOption);
//使用TEFill物件將圓形繪製出來
pMap.fitBounds(BufferArea.getBounds());
//取得環域圖形的邊界後, 調整地圖顯示的範圍
