台灣圖霸 | Map8 Platform
歡迎使用 台灣圖霸 | Map8 Platform 地圖平台
- 歡迎試用我們的 台灣圖霸 (Map8 Platform) 地圖平台 API!! 請點此申請試用~
- 然後也歡迎您到我們的 官方 API Explorer 試用看看~
有任何技術疑難,或其他疑問,都歡迎您 跟我們聯絡 喔!!!
Authentication (認證與授權)
要能取用 Map8 平台的 API,請於 URL query string 中以
key
參數帶入您的API key
:
https://api.map8.zone/place/geocode?address=台北市內湖區新湖三路189號&key=<您的 key>
請務必將上例
<您的 key>
替換成您的API key
喔!!!
台灣圖霸平台 | Map8 Platform 的 API 透過 API key
來讓您使用平台的 API。您可以 點此申請試用。
台灣圖霸平台 | Map8 Platform 的 API 預期來自 client 端的所有 API 請求於 URL 的 query string 中夾帶 API key 以認證並取得使用,例如 :
https://api.map8.zone/v2/place/geocode?address=台北市內湖區新湖三路189號&key=<您的 key>
Notation
- 左右鍵符號 (大於、小於符號, 也就是
<
>
) 所描述的是一個變數 (variable) 的 formal parameter 形式。本文件底下若提及參數部分,使用到此表示法時,請讀者將之代換成實際的內容 (也就是代換為 actual parameter,並且,不留下<
>
符號)。例如,https://api.map8.zone/find?keyword=<關鍵詞>
若實際關鍵詞為 taiwan,則實際呼叫時,應代換為https://api.map8.zone/find?keyword=taiwan
。 - 位於 API 欄位內格式的
<參數>
,為標準的 URL 之 query string 格式編碼 (i.e.,name=value
以 URL%
編碼, 並以&
連接) - 除非另有指定,否則,地理經緯度座標 (lat 或 latitude 均指經度,lng 或 longitude 均指緯度) 以 WGS84 / EPSG:4326 為地理座標系統
Version
- v3.0.15_2020-10-13 (the present document)
- Nearby Search API 單次回應筆數提高至最多可為 100 筆。
- v3.0_2020-01-06
- Roads 新增 Snap to Roads API。
- Routes 新增 Distance Matrix API。
- Routes 新增 Trip API。
- v2.1_2019-07-29
- v2.0_2019-06-26
- 請注意 : 本次更版,下列 API 版號有所進版,因而 URL 路徑也有變更。請您使用新版本,以取得最新性能。
- Places API 全部,包括 :
- Find Place API 由 https://api.map8.zone/place/findplacefromtext 進版為 https://api.map8.zone/
v2
/place/findplacefromtext。 - Nearby Search API 由 https://api.map8.zone/place/nearbysearch 進版為 https://api.map8.zone/
v2
/place/nearbysearch。 - Place Autocomplete API 由 https://api.map8.zone/place/autocomplete 進版為 https://api.map8.zone/
v2
/place/autocomplete。
- Find Place API 由 https://api.map8.zone/place/findplacefromtext 進版為 https://api.map8.zone/
- Places API 全部,包括 :
- 新增 Place Details API。
- 新增
postcode
與formatted_address_embed_postcode
參數,以提供您地址之郵遞區號。 - 請注意 : 本版本起,Place Autocomplete API 用法有所改變 -- 如同 Google 用法,Place Autocomplete API 不提供座標。請於使用者選定 autocomplete 所提供之候選清單之一的時候,透過 Place Details API 取得地點的詳細資訊。
- Nearby Search API 與 Text Search API 新增
cat
參數,支援指定欲搜尋的 地點類型。 - Map8 平台維護了最具權威性的門牌地址資料庫,並隨時與台灣戶政司門牌地址資料保持更新。Geocoding API 新增提供
level
(定位結果的層級,譬如,為定位到縣市、或是道路,或是精確到門牌)。或者門牌並不存在,因而透過內插 (interpolation),或是改經由模糊搜尋並給予可能性指數likelihood
。並透過authoritative
欄位告訴您定位結果是否出自於 Map8 平台最具權威的門牌地址資料庫。
- 請注意 : 本次更版,下列 API 版號有所進版,因而 URL 路徑也有變更。請您使用新版本,以取得最新性能。
- 舊版
- (不再支援) v1.1_2019-05-26
API Index
- Maps
- Maps Embed API
- 在網站或其他素材中嵌入靜態地圖
- Maps Static API
- 不需要任何程式碼,用最簡單的方式嵌入動態的互動式電子地圖
- Maps Javascript API
- 為您的網站添加互動式電子地圖
- Maps Embed API
- Places
- Places API
- 地點搜尋 (Place Search)
- Find Place API
- 給定關鍵詞,搜尋地點
- Place Details API
- 取得地點詳細資訊 (主要用於 Autocomplete API)
- Nearby Search API
- 給定座標,搜尋周遭
- Text Search API
- 以任意的關鍵詞組合進行搜尋
- Find Place API
- Place Autocomplete API
- 讓使用者邊輸入,便邊回應出推測的可能清單
- 地點搜尋 (Place Search)
- Geocoding API
- 地址定位與反地址定位
- Places API
- Routes
- Directions API
- 依所給定之起訖點 (與數個中途點) 順序,進行多點路徑規劃
- Distance Matrix API
- (排班) 運算多對多起訖點之交通時間距離矩陣
- Trip API
- (排行程) 給定多途經點,排出次序並規劃路徑 (旅行業務員 / TSP 最短路徑問題)
- Directions API
- Roads
- Nearest Roads API
- 取得道路屬性(譬如道路速限、高架、橋樑、限高)
- Snap to Roads API
- 對地圖黏岀最可能路徑 (黏路)
- Nearest Roads API
[Places] 地點搜尋
功能 : 搜尋台灣圖霸地圖內的地點
搜尋地點 API (Find Place API)
Syntax
https://api.map8.zone/v2/place/findplacefromtext/json?key=<您的 key>
&input=<搜尋關鍵詞>
&locationbias=<緯度>,<經度>
提醒您 :
URL 所有以 query string 形式帶入的參數,應當都要視情況,適當地經過 URL encode 編碼後再傳入。
以免發生錯誤而收到 HTTP 400 Bad Request。
Example
HTTP GET "https://api.map8.zone/v2/place/findplacefromtext/json?key=<您的 key>&input=研鼎智能&locationbias=25.06102,121.58790"
{
"html_attribution": [
"台灣圖霸",
"研鼎智能",
"PAPAGO!"
],
"result": {
"formatted_address": "台北市內湖區新湖三路189號",
"geometry": {
"location": {
"lat": 25.065089,
"lng": 121.580056
}
},
"id": "NzYqAQYARhkCVltTRRxiJBIYMDIIZgVSLyMdf25eBDIIPQ1VHWEwEg==",
"place_id": "NzYqAQYARhkCVltTRRxiJBIYMDIIZgVSLyMdf25eBDIIPQ1VHWEwEg==",
"name": "研鼎智能股份有限公司",
"tel": "02-87921567",
"city": "台北市",
"town": "內湖區",
"type": "地點",
"chain": "",
"branch": "",
"cat": "公司行號",
"distance": 0.91
},
"status": "OK"
}
Example : 搜尋地點,並要求若搜尋結果有地址則附帶三碼郵遞區號
HTTP GET "https://api.map8.zone/v2/place/findplacefromtext/json?key=<您的 key>&input=研鼎智能&locationbias=25.06102,121.58790&postcode"
{
"html_attribution": [
"台灣圖霸",
"研鼎智能",
"PAPAGO!"
],
"result": {
"formatted_address": "台北市內湖區新湖三路189號",
"geometry": {
"location": {
"lat": 25.065089,
"lng": 121.580056
}
},
"id": "NzYqAQYARhkCVltTRRxiJBIYMDIIZgVSLyMdf25eBDIIPQ1VHWEwEg==",
"place_id": "NzYqAQYARhkCVltTRRxiJBIYMDIIZgVSLyMdf25eBDIIPQ1VHWEwEg==",
"name": "研鼎智能股份有限公司",
"tel": "02-87921567",
"city": "台北市",
"town": "內湖區",
"type": "地點",
"chain": "",
"branch": "",
"cat": "公司行號",
"distance": 0.91,
"postcode": "114"
},
"status": "OK"
}
Example : 搜尋地點,並要求若搜尋結果有地址則附帶三碼郵遞區號內嵌於
formatted_address
欄位
HTTP GET "https://api.map8.zone/v2/place/findplacefromtext/json?key=<您的 key>&input=研鼎智能&locationbias=25.06102,121.58790&postcode&formatted_address_embed_postcode"
{
"html_attribution": [
"台灣圖霸",
"研鼎智能",
"PAPAGO!"
],
"result": {
"formatted_address": "114 台北市內湖區新湖三路189號",
"geometry": {
"location": {
"lat": 25.065089,
"lng": 121.580056
}
},
"id": "NzYqAQYARhkCVltTRRxiJBIYMDIIZgVSLyMdf25eBDIIPQ1VHWEwEg==",
"place_id": "NzYqAQYARhkCVltTRRxiJBIYMDIIZgVSLyMdf25eBDIIPQ1VHWEwEg==",
"name": "研鼎智能股份有限公司",
"tel": "02-87921567",
"city": "台北市",
"town": "內湖區",
"type": "地點",
"chain": "",
"branch": "",
"cat": "公司行號",
"distance": 0.91
},
"status": "OK"
}
給定關鍵詞,搜尋地點
- API :
https://api.map8.zone/v2/place/findplacefromtext/<輸出格式>?<參數>
- HTTP Method :
- GET
- Synopsis
- <輸出格式>
- 選擇性參數,本版本不理會此參數,response 一律以 JSON 格式回應。
- <參數>
- key
- 必要參數,請帶進您的 key。
- input
- 必要參數,欲搜尋的地點的關鍵詞 (無任何空白分隔)。可以是地址、地名、商店名稱、或電話。
- inputtype
- 選擇性參數,應為
textquery
或phonenumber
兩者之一。若未給,則由台灣圖霸系統自動智慧判斷。
- 選擇性參數,應為
- locationbias
- 選擇性參數,可為 :
ipbias
: 要求系統依照您發出此 request 的 IP address 來決定本 API 進行搜尋時的中心點。<緯度>,<經度>
: 要求系統依據給定的地理經緯度座標為搜尋中心點。
- 此參數若未給,則系統預設採用
ipbias
。 - (注意) 採用
ipbias
方式將增加額外的系統動作,可能因網路而造成搜尋速度相當幅度的延遲。因此,建議您盡可能不要採用ipbias
。強烈建議您一律採locationbias=<緯度>,<經度>
參數
- 選擇性參數,可為 :
- postcode
- 選擇性參數 : 是否需要回傳三碼郵遞區號 (
true
/false
; 預設為false
; 請注意true
/false
值以 如字面 (string literal) 帶入,而非以 1 / 0 或其它字元帶入)。
- 選擇性參數 : 是否需要回傳三碼郵遞區號 (
- formatted_address_embed_postcode
- 若上述
postcode
參數有被指定,則指定此參數以將三碼郵遞區號直接內嵌於 response 之formatted_address
欄位內 (否則,三碼郵遞區號將另以postcode
欄位回傳)。
- 若上述
- key
- (Migration 指南) 與 Google Maps 的 Find Place API 相容性
- 台灣圖霸一次就把全部欄位回應給您,因此,Google Maps Find Place API 的 fields 參數 台灣圖霸見到會直接 ignore -- 因此,如果您本來有使用此參數,那您可以選擇放著不改 (如果您認為這樣能降低您改動的 effort 的話)。
language
,locationbias.circular
,locationbias.rectangular
也均 ignore (因此,同樣地,您可自行決定要刪除或留著)。
- <輸出格式>
Response
Status code : 200 OK
- 表示成功完成您的 request
Response Message Body
- Content-type: application/json
{ "html_attributions" : [ // 您必須向使用者表彰之本 API 所屬的圖資版權資訊 "台灣圖霸", "研鼎智能", "PAPAGO!" ], "candidates" : [ // `搜尋結果` 陣列 { "formatted_address" : <String>, // 地址 (經整理、格式化過的) "geometry" : { "location" : { "lat" : <Number>, // 緯度 "lng" : <Number> // 經度 }, }, "id" : <String>, // 此地點於台灣圖霸系統內的地點 ID "place_id" : <String>, // 此地點於台灣圖霸系統內的地點 ID "name" : <String>, // 本筆資料的名稱 (地名、道路名、地點名) (例如 "研鼎智能股份有限公司") "tel" : <String>, // 本筆資料的電話號碼 (例如 "02-87921567") "city" : <String>, // 本筆資料所屬的城市 (例如 "台北市") "town" : <String>, // 本筆資料所屬的行政區 (例如 "內湖區") "type" : <String>, // 本筆資料的類型,可為 : "地點", "地址", 或 "道路" "chain" : <String>, // 本筆資料若屬於某連鎖機構, 則此欄位為該機構名稱 (例如 "研勤集團") "branch" : <String>, // 本筆資料若屬於某連鎖機構, 則此欄位為該分店名稱 (例如 "台中辦公室") "cat" : <String>, // 本筆資料於台灣圖霸系統內所歸屬的地點類型 (例如 "公司行號") "distance" : <Number>, // 本筆資料與輸入的中心點座標間的直線距離, 單位為 km } ], "status" : <String> // Status Code }
Status code : 400 Bad Request
- 表示您的 request 系統偵測到有錯誤而無法完成您的要求。通常是給入的參數多了或少了,或是格式有錯誤,或必要參數卻沒給,等等
Response Message Body
- type: application/json
{ "status" : <String> // Status Code }
參見 HTTP Status Code 一節說明本 API 回傳值之一般通則
參見 "status" 欄位 一節說明 "status" 欄位的一般性意義
地點詳細資訊 API (Place Details API)
Syntax
https://api.map8.zone/v2/place/details/json?key=<您的 key>
&placeid=<地點 id>
&postcode=true
&formatted_address_embed_postcode=true
提醒您 :
URL 所有以 query string 形式帶入的參數,應當都要視情況,適當地經過 URL encode 編碼後再傳入。
以免發生錯誤而收到 HTTP 400 Bad Request。
Example : 給定地點 ID 以取得地點詳細資訊 (同時,若該地點有地址,也取回三碼郵遞區號)
HTTP GET "https://api.map8.zone/v2/place/details/json?key=<您的 key>&placeid=NzYqAQYARhkCVltTRRxiJBIYMDIIZgVSLyMdf25eBDIIPQ1VHWEwEg==&postcode=true"
{
"html_attribution": [
"台灣圖霸",
"研鼎智能",
"PAPAGO!"
],
"result": {
"formatted_address": "台北市內湖區新湖三路189號",
"geometry": {
"location": {
"lat": 25.065089,
"lng": 121.580056
}
},
"id": "NzYqAQYARhkCVltTRRxiJBIYMDIIZgVSLyMdf25eBDIIPQ1VHWEwEg==",
"place_id": "NzYqAQYARhkCVltTRRxiJBIYMDIIZgVSLyMdf25eBDIIPQ1VHWEwEg==",
"name": "研鼎智能股份有限公司",
"tel": "02-87921567",
"city": "台北市",
"town": "內湖區",
"type": "地點",
"chain": "",
"branch": "",
"cat": "公司行號",
"distance": 0,
"postcode": "114"
},
"status": "OK"
}
取得地點詳細資訊 (主要用於Autocomplete API -- 當使用者選擇了候選清單中的一項的時候,透過 place_id
呼叫本 API 以取得座標、電話等等詳細資料)。
- API :
https://api.map8.zone/v2/place/details/<輸出格式>?<參數>
- HTTP Method :
- GET
Synopsis
- <輸出格式>
- 選擇性參數,本版本不理會此參數,response 一律以 JSON 格式回應。
<參數>
- key
- 必要參數,請帶進您的 key。
placeid
- 必要參數,欲取得的地點之 ID (由之前呼叫之 Map8 台灣圖霸其他 API 所回傳;例如 Autocomplete API)。
postcode
- 選擇性參數 : 是否需要回傳三碼郵遞區號 (
true
/false
; 預設為false
; 請注意true
/false
值以 如字面 (string literal) 帶入,而非以 1 / 0 或其它字元帶入)。
- 選擇性參數 : 是否需要回傳三碼郵遞區號 (
formatted_address_embed_postcode
- 若上述
postcode
參數有被指定,則指定此參數以將三碼郵遞區號直接內嵌於 response 之formatted_address
欄位內 (否則,三碼郵遞區號將另以postcode
欄位回傳)。
- 若上述
- key
- <輸出格式>
Response
Status code : 200 OK
- 表示成功完成您的 request
Response Message Body
- Content-type: application/json
{ "html_attributions" : [ // 您必須向使用者表彰之本 API 所屬的圖資版權資訊 "台灣圖霸", "研鼎智能", "PAPAGO!" ], "result" : { "formatted_address" : <String>, // 地址 (經整理、格式化過的) "geometry" : { "location" : { "lat" : <Number>, // 緯度 "lng" : <Number> // 經度 }, }, "id" : <String>, // 此地點於台灣圖霸系統內的地點 ID "place_id" : <String>, // 此地點於台灣圖霸系統內的地點 ID "name" : <String>, // 此地點的名稱 (地名、道路名、地點名) (例如 "研鼎智能股份有限公司") "tel" : <String>, // 此地點的電話號碼 (例如 "02-87921567") "city" : <String>, // 此地點所屬的城市 (例如 "台北市") "town" : <String>, // 此地點所屬的行政區 (例如 "內湖區") "type" : <String>, // 此地點的類型,可為 : "地點", "地址", 或 "道路" "chain" : <String>, // 此地點若屬於某連鎖機構, 則此欄位為該機構名稱 (例如 "研勤集團") "branch" : <String>, // 此地點若屬於某連鎖機構, 則此欄位為該分店名稱 (例如 "台中辦公室") "cat" : <String>, // 此地點於台灣圖霸系統內所歸屬的地點類型 (例如 "公司行號") "distance" : <Number>, // 本筆資料與輸入的中心點座標間的直線距離, 單位為 km }, "status" : <String> // Status Code }
- 上述
result
內的各欄位, 若無值, 仍一律回傳, 但帶空值
Status code : 400 Bad Request
- 表示您的 request 系統偵測到有錯誤而無法完成您的要求。通常是給入的參數多了或少了,或是格式有錯誤,或必要參數卻沒給,等等
Response Message Body
- type: application/json
{ "status" : <String> // Status Code }
參見 HTTP Status Code 一節說明本 API 回傳值之一般通則
參見 "status" 欄位 一節說明 "status" 欄位的一般性意義
搜尋周遭 API (Nearby Search API)
Syntax
https://api.map8.zone/v2/place/nearbysearch/json?key=<您的 key>
&location=<緯度>,<經度>
&radius=<範圍 (km)>
&cat=<以逗號分隔所列舉之地點類型>
提醒您 :
URL 所有以 query string 形式帶入的參數,應當都要視情況,適當地經過 URL encode 編碼後再傳入。
以免發生錯誤而收到 HTTP 400 Bad Request。
Example : 搜尋以地點為中心之周遭的便利商店與學校 (註 : 為減少篇幅,底下僅列出前五筆)
HTTP GET "https://api.map8.zone/v2/place/nearbysearch/json?key=<您的 key>&location=25.069117,121.58732&cat=便利商店,國小,國中,高中職校&postcode"
{
"html_attribution": [
"台灣圖霸",
"研鼎智能",
"PAPAGO!"
],
"results": [
{
"formatted_address": "台北市內湖區民權東路六段69號",
"geometry": {
"location": {
"lat": 25.069215,
"lng": 121.587593
}
},
"id": "NzYqAQYCRh4HXV5TFDl7K1AdFkRXBRN4BgsFWl1SXxgVAR10AkACEg==",
"place_id": "NzYqAQYCRh4HXV5TFDl7K1AdFkRXBRN4BgsFWl1SXxgVAR10AkACEg==",
"name": "萊爾富便利商店北市民東店",
"tel": "02-27931697",
"city": "台北市",
"town": "內湖區",
"type": "地點",
"chain": "萊爾富便利商店",
"branch": "北市民東店",
"cat": "便利商店",
"distance": 0.03,
"postcode": "114"
},
{
"formatted_address": "台北市內湖區民權東路六段45號",
"geometry": {
"location": {
"lat": 25.069168,
"lng": 121.586274
}
},
"id": "NzYqAQYCRh0FXV9TJwMACz5SGxF6AAkAPBtgaEJ3FiMfSyxqUQFNEg==",
"place_id": "NzYqAQYCRh0FXV9TJwMACz5SGxF6AAkAPBtgaEJ3FiMfSyxqUQFNEg==",
"name": "市立三民國中",
"tel": "02-27924772",
"city": "台北市",
"town": "內湖區",
"type": "地點",
"chain": "",
"branch": "",
"cat": "國中",
"distance": 0.106,
"postcode": "114"
},
{
"formatted_address": "台北市內湖區民權東路六段90巷1號",
"geometry": {
"location": {
"lat": 25.068799,
"lng": 121.586104
}
},
"id": "NzYqAQYCRh0LVllTNFl6TDUDTQAARg15Fg1OfU91HgMBTDJoRFs8Eg==",
"place_id": "NzYqAQYCRh0LVllTNFl6TDUDTQAARg15Fg1OfU91HgMBTDJoRFs8Eg==",
"name": "全家便利商店三民店",
"tel": "02-77230365",
"city": "台北市",
"town": "內湖區",
"type": "地點",
"chain": "全家便利商店",
"branch": "三民店",
"cat": "便利商店",
"distance": 0.127,
"postcode": "114"
},
{
"formatted_address": "台北市內湖區湖興里民權東路六段138號",
"geometry": {
"location": {
"lat": 25.068833,
"lng": 121.588721
}
},
"id": "NzYqAQYCRh0GVlpTACJMMR06HVxdAS1AORt1X24DTEwKTwAbZFdNEg==",
"place_id": "NzYqAQYCRh0GVlpTACJMMR06HVxdAS1AORt1X24DTEwKTwAbZFdNEg==",
"name": "市立新湖國小",
"tel": "02-27963721",
"city": "台北市",
"town": "內湖區",
"type": "地點",
"chain": "",
"branch": "",
"cat": "國小",
"distance": 0.145,
"postcode": "114"
},
{
"formatted_address": "台北市內湖區民權東路六段120巷7弄8號",
"geometry": {
"location": {
"lat": 25.067709,
"lng": 121.587595
}
},
"id": "NzYqAQYCRhwDX1lTIS5CHiIIKzYJQxp0JjB8fl4bE1ZUTQN7fWI8Eg==",
"place_id": "NzYqAQYCRhwDX1lTIS5CHiIIKzYJQxp0JjB8fl4bE1ZUTQN7fWI8Eg==",
"name": "7-ELEVEN欣福門市",
"tel": "02-27916033",
"city": "台北市",
"town": "內湖區",
"type": "地點",
"chain": "7-ELEVEN",
"branch": "欣福門市",
"cat": "便利商店",
"distance": 0.159,
"postcode": "114"
}
],
"status": "OK"
}
Example : 不指定
cat
(地點類型) 參數 (註 : 為減少篇幅,底下僅列出前五筆)
HTTP GET "https://api.map8.zone/v2/place/nearbysearch/json?key=<您的 key>&location=25.06102,121.58790"
{
"html_attribution": [
"台灣圖霸",
"研鼎智能",
"PAPAGO!"
],
"results": [
{
"formatted_address": "台北市內湖區新湖三路189號",
"geometry": {
"location": {
"lat": 25.065089,
"lng": 121.580056
}
},
"id": "NzYqAQYARhkCVltTRRxiJBIYMDIIZgVSLyMdf25eBDIIPQ1VHWEwEg==",
"place_id": "NzYqAQYARhkCVltTRRxiJBIYMDIIZgVSLyMdf25eBDIIPQ1VHWEwEg==",
"name": "研鼎智能股份有限公司",
"tel": "02-87921567",
"city": "台北市",
"town": "內湖區",
"type": "地點",
"chain": "",
"branch": "",
"cat": "公司行號",
"distance": 0,
"postcode": "114"
},
{
"formatted_address": "台北市內湖區新湖三路189號",
"geometry": {
"location": {
"lat": 25.065089,
"lng": 121.580056
}
},
"id": "IykqAAMHRBwCV1lTRl90F1RSSDB1fgl6LR1xCXF4Vhc3CxIJfEI0Eg==",
"place_id": "IykqAAMHRBwCV1lTRl90F1RSSDB1fgl6LR1xCXF4Vhc3CxIJfEI0Eg==",
"name": "新湖三路189號",
"tel": "",
"city": "台北市",
"town": "內湖區",
"type": "地址",
"chain": "",
"branch": "",
"cat": "",
"distance": 0,
"postcode": "114"
},
{
"formatted_address": "台北市內湖區新湖三路191號",
"geometry": {
"location": {
"lat": 25.065226,
"lng": 121.580315
}
},
"id": "NzYqAQYBQhkBWFJTHB5TFiIVQVxtfwd6EShAVk9DVRFTKSUBDnY4Eg==",
"place_id": "NzYqAQYBQhkBWFJTHB5TFiIVQVxtfwd6EShAVk9DVRFTKSUBDnY4Eg==",
"name": "品砌家居",
"tel": "02-27939213",
"city": "台北市",
"town": "內湖區",
"type": "地點",
"chain": "",
"branch": "",
"cat": "居家修繕",
"distance": 0.03,
"postcode": "114"
},
{
"formatted_address": "台北市內湖區新湖三路191號",
"geometry": {
"location": {
"lat": 25.065226,
"lng": 121.580315
}
},
"id": "IykqAAMHRBwCV15TIgNCDSEoFRRrBSdUAl8AdX9CMk4QNz9HckESEg==",
"place_id": "IykqAAMHRBwCV15TIgNCDSEoFRRrBSdUAl8AdX9CMk4QNz9HckESEg==",
"name": "新湖三路191號",
"tel": "",
"city": "台北市",
"town": "內湖區",
"type": "地址",
"chain": "",
"branch": "",
"cat": "",
"distance": 0.03,
"postcode": "114"
},
{
"formatted_address": "台北市內湖區行愛路159號",
"geometry": {
"location": {
"lat": 25.064817,
"lng": 121.579805
}
},
"id": "NzYqAQYHQxYAXV1TGwMdCiRSFUYBZC9xMhlZZ39RAk4sHkwJfwcWEg==",
"place_id": "NzYqAQYHQxYAXV1TGwMdCiRSFUYBZC9xMhlZZ39RAk4sHkwJfwcWEg==",
"name": "第一金證券新湖證券櫃檯",
"tel": "02-27903860",
"city": "台北市",
"town": "內湖區",
"type": "地點",
"chain": "第一金證券",
"branch": "新湖證券櫃檯",
"cat": "證券投資",
"distance": 0.039,
"postcode": "114"
}
],
"status": "OK"
}
給定座標,搜尋周遭
- API :
https://api.map8.zone/v2/place/nearbysearch/<輸出格式>?<參數>
- HTTP Method :
- GET
- Synopsis
- <輸出格式>
- 選擇性參數,本版本不理會此參數,response 一律以 JSON 格式回應。
- <參數>
- key
- 必要參數,請帶進您的 key。
- location
- 必要參數,要求系統依據給定的地理座標為搜尋中心點。格式為
<緯度>,<經度>
,分別為緯度與經度。
- 必要參數,要求系統依據給定的地理座標為搜尋中心點。格式為
- radius
- 選擇性參數,指定以上述
location
為中心,以本參數radius
指定方圓半徑之距離作為搜索範圍 (最大為 50.000 公里)。若未給,則由台灣圖霸系統自動智慧判斷。
- 選擇性參數,指定以上述
- limit
- 選擇性參數。指定取回的資料筆數。單次回應最多為 100 筆。
- cat
- 選擇性參數。指定欲搜尋周遭之地點類型。請參考所支援之 地點類型。
- 可多選 : 請直接列舉地點類型,透過逗號 (
,
) 加以分隔即可 (譬如cat=國小,國中,高中職校
)。
- postcode
- 選擇性參數 : 是否需要回傳三碼郵遞區號 (
true
/false
; 預設為false
; 請注意true
/false
值以 如字面 (string literal) 帶入,而非以 1 / 0 或其它字元帶入)。範例同 Find Place API 之範例。
- 選擇性參數 : 是否需要回傳三碼郵遞區號 (
- formatted_address_embed_postcode
- 若上述
postcode
參數有被指定,則指定此參數以將三碼郵遞區號直接內嵌於 response 之formatted_address
欄位內 (否則,三碼郵遞區號將另以postcode
欄位回傳)。範例同 Find Place API 之範例。
- 若上述
- key
- (Migration 指南) 與 Google Maps 的 Nearby Search API 相容性
- 除以上 參數 章節所描述的參數外,其他 Google Maps Nearby Search API 的參數 包括
rankby
,keyword
,language
,minprice
,name
,opennow
,type
,pagetoken
也均 ignore (因此,同樣地,您可自行決定要刪除或留著)。
- 除以上 參數 章節所描述的參數外,其他 Google Maps Nearby Search API 的參數 包括
- <輸出格式>
Response
Status code : 200 OK
- 表示成功完成您的 request
Response Message Body
- type: application/json
{ "html_attributions" : [ // 您必須向使用者表彰之本 API 所屬的圖資版權資訊 "台灣圖霸", "研鼎智能", "PAPAGO!" ], "results" : [ // `搜尋結果` 陣列 { "formatted_address" : <String>, // 地址 (經整理、格式化過的) "geometry" : { "location" : { "lat" : <Number>, // 緯度 "lng" : <Number> // 經度 }, }, "id" : <String>, // 此地點於台灣圖霸系統內的地點 ID "place_id" : <String>, // 此地點於台灣圖霸系統內的地點 ID "name" : <String>, // 本筆資料的名稱 (地名、道路名、地點名) (例如 "研鼎智能股份有限公司") "tel" : <String>, // 本筆資料的電話號碼 (例如 "02-87921567") "city" : <String>, // 本筆資料所屬的城市 (例如 "台北市") "town" : <String>, // 本筆資料所屬的行政區 (例如 "內湖區") "type" : <String>, // 本筆資料的類型,可為 : "地點", "地址", 或 "道路" "chain" : <String>, // 本筆資料若屬於某連鎖機構, 則此欄位為該機構名稱 (例如 "研勤集團") "branch" : <String>, // 本筆資料若屬於某連鎖機構, 則此欄位為該分店名稱 (例如 "台中辦公室") "cat" : <String>, // 本筆資料於台灣圖霸系統內所歸屬的地點類型 (例如 "公司行號") "distance" : <Number>, // 本筆資料與輸入的中心點座標間的直線距離, 單位為 km }, ... (more results) ... ], "status" : <String> // Status Code }
- 上述每一筆搜尋結果內的各欄位, 若無值, 仍一律回傳, 但帶空值
- results 陣列帶回本次搜尋的查詢結果。本 API 的查詢,最多一次回應 100 筆資料
- (Migration 指南) 與 Google Maps 的 Find Place API 相容性
Status code : 400 Bad Request
- 表示您的 request 系統偵測到有錯誤而無法完成您的要求。通常是給入的參數多了或少了,或是格式有錯誤,或必要參數卻沒給,等等
Response Message Body
- Content-type: application/json
{ "status" : <String> // Status Code }
參見 HTTP Status Code 一節說明本 API 回傳值之一般通則
參見 "status" 欄位 一節說明 "status" 欄位的一般性意義
任意關鍵詞搜尋 API (Text Search API)
Syntax
https://api.map8.zone/v2/place/textsearch/json?key=<您的 key>
&query=<關鍵詞 (可空白分隔)>
&location=<緯度>,<經度>
&cat=<以逗號分隔所列舉之地點類型>
提醒您 :
URL 所有以 query string 形式帶入的參數,應當都要視情況,適當地經過 URL encode 編碼後再傳入。
以免發生錯誤而收到 HTTP 400 Bad Request。
Example : 以
內湖 台北
為關鍵字搜尋 地點類型 為加油站
者 (註 : 為減少篇幅,底下僅列出前五筆)
HTTP GET "https://api.map8.zone/v2/place/textsearch/json?key=<您的 key>&query=內湖 台北&cat=加油站&location=25.06102,121.58790"
{
"html_attribution": [
"台灣圖霸",
"研鼎智能",
"PAPAGO!"
],
"results": [
{
"formatted_address": "台北市內湖區新明路92號",
"geometry": {
"location": {
"lat": 25.059615,
"lng": 121.589523
}
},
"id": "NzYqAQYCRh0BXVNTPQV9CxcoDzIMcwtXHzkGU3dYEQ8TDRF8WhlBEg==",
"place_id": "NzYqAQYCRh0BXVNTPQV9CxcoDzIMcwtXHzkGU3dYEQ8TDRF8WhlBEg==",
"name": "統一速邁樂加油站內湖一站",
"tel": "02-27929031",
"city": "台北市",
"town": "內湖區",
"type": "地點",
"chain": "統一速邁樂加油站",
"branch": "內湖一站",
"cat": "加油站",
"distance": 0.226
},
{
"formatted_address": "台北市內湖區民權東路六段50號",
"geometry": {
"location": {
"lat": 25.068355,
"lng": 121.583351
}
},
"id": "NzYqAQYHTR4BWVxTQydkJC4fTAF6ZlgDNAR4QVkfADQyFUJ3U0RNEg==",
"place_id": "NzYqAQYHTR4BWVxTQydkJC4fTAF6ZlgDNAR4QVkfADQyFUJ3U0RNEg==",
"name": "台灣宅配通-中油加油站內湖站-代收店",
"tel": "02-27920678",
"city": "台北市",
"town": "內湖區",
"type": "地點",
"chain": "台灣宅配通",
"branch": "中油加油站內湖站-代收店",
"cat": "貨運站",
"distance": 0.936
},
{
"formatted_address": "台北市內湖區民權東路六段50號",
"geometry": {
"location": {
"lat": 25.068355,
"lng": 121.583351
}
},
"id": "NzYqAQYCRh0BXV9TMSMOEx0+STRRfQ9oWFNcawFEMSALDyMGdFkWEg==",
"place_id": "NzYqAQYCRh0BXV9TMSMOEx0+STRRfQ9oWFNcawFEMSALDyMGdFkWEg==",
"name": "中油加油站內湖站",
"tel": "02-27920678",
"city": "台北市",
"town": "內湖區",
"type": "地點",
"chain": "中油加油站",
"branch": "內湖站",
"cat": "加油站",
"distance": 0.936
},
{
"formatted_address": "台北市內湖區內湖路一段362號",
"geometry": {
"location": {
"lat": 25.081308,
"lng": 121.571103
}
},
"id": "NzYqAQYHTR8CXlxTWD0AFQUUUiFuTD8FTw1vYk98KQM2ABR8QxkaEg==",
"place_id": "NzYqAQYHTR8CXlxTWD0AFQUUUiFuTD8FTw1vYk98KQM2ABR8QxkaEg==",
"name": "台灣宅配通-中油加油站內湖麗山街站-代收店",
"tel": "02-26577339",
"city": "台北市",
"town": "內湖區",
"type": "地點",
"chain": "台灣宅配通",
"branch": "中油加油站內湖麗山街站-代收店",
"cat": "貨運站",
"distance": 2.82
},
{
"formatted_address": "台北市內湖區內湖路一段362號",
"geometry": {
"location": {
"lat": 25.081308,
"lng": 121.571103
}
},
"id": "NzYqAQYCRh0AXlpTMCJSJTE/OFhQc1xVBQB/dnYMLj4IMgBfAFkgEg==",
"place_id": "NzYqAQYCRh0AXlpTMCJSJTE/OFhQc1xVBQB/dnYMLj4IMgBfAFkgEg==",
"name": "中油加油站內湖麗山街站",
"tel": "02-26577339",
"city": "台北市",
"town": "內湖區",
"type": "地點",
"chain": "中油加油站",
"branch": "內湖麗山街站",
"cat": "加油站",
"distance": 2.82
}
],
"status": "OK"
}
以任意的關鍵詞組合進行搜尋
- API :
https://api.map8.zone/v2/place/textsearch/<輸出格式>?<參數>
- HTTP Method :
- GET
- Synopsis
- <輸出格式>
- 選擇性參數,本版本不理會此參數,response 一律以 JSON 格式回應。
- <參數>
- key
- 必要參數,請帶進您的 key。
- query
- 必要參數,給定任意的關鍵詞組合 (請把這個當作搜尋引擎) 關鍵詞以空白分隔, 例如 "加油站 台中" 這樣即可得到滿意的結果。
- cat
- 選擇性參數。指定欲搜尋周遭之地點類型。請參考所支援之 地點類型。
- 可多選 : 請直接列舉地點類型,透過逗號 (
,
) 加以分隔即可 (譬如cat=國小,國中,高中職校
)。
- location
- 選擇性參數,要求系統依據給定的地理座標為搜尋中心點。格式為
<緯度>,<經度>
,分別為緯度與經度。 - 此參數若未給,則系統預設依照您發出此 request 的 IP address 來決定本 API 進行搜尋時的中心點。但請注意 : 此方式將增加額外的系統動作,可能因網路而造成搜尋速度相當幅度的延遲。因此,強烈建議您一律給
location=<緯度>,<經度>
參數
- 選擇性參數,要求系統依據給定的地理座標為搜尋中心點。格式為
- radius
- 選擇性參數,指定以上述
location
為中心,以本參數radius
指定方圓半徑之距離作為搜索範圍 (最大為 50.000 公里)。若未給,則由台灣圖霸系統自動智慧判斷。
- 選擇性參數,指定以上述
- postcode
- 選擇性參數 : 是否需要回傳三碼郵遞區號 (
true
/false
; 預設為false
; 請注意true
/false
值以 如字面 (string literal) 帶入,而非以 1 / 0 或其它字元帶入)。範例同 Find Place API 之範例。
- 選擇性參數 : 是否需要回傳三碼郵遞區號 (
- formatted_address_embed_postcode
- 若上述
postcode
參數有被指定,則指定此參數以將三碼郵遞區號直接內嵌於 response 之formatted_address
欄位內 (否則,三碼郵遞區號將另以postcode
欄位回傳)。範例同 Find Place API 之範例。
- 若上述
- key
- (Migration 指南) 與 Google Maps 的 Text Search API 相容性
- 除以上 參數 章節所描述的參數外,其他 Google Maps Text Search API 的參數 包括
region
,language
,minprice
,opennow
,type
,pagetoken
也均 ignore (因此,同樣地,您可自行決定要刪除或留著)。
- 除以上 參數 章節所描述的參數外,其他 Google Maps Text Search API 的參數 包括
- <輸出格式>
- Response
- 同 Nearby Seach, 請參見 Nearby Search API 的 Response 章節。
- back to index
地點自動完成 API (Place Autocomplete API)
Syntax
https://api.map8.zone/v2/place/autocomplete/json?key=<您的 key>
&input=<關鍵詞 (可空白分隔)>
&location=<緯度>,<經度>
&radius=<範圍 (km)>
提醒您 :
URL 所有以 query string 形式帶入的參數,應當都要視情況,適當地經過 URL encode 編碼後再傳入。
以免發生錯誤而收到 HTTP 400 Bad Request。
Example
HTTP GET "https://api.map8.zone/v2/place/autocomplete/json?key=<您的 key>&input=明美&location=25.06102,121.58790"
{
"html_attribution": [
"台灣圖霸",
"研鼎智能",
"PAPAGO!"
],
"status": "OK",
"predictions": [
{
"id": "NzYqAQYGQhoHWlpTOi0OLlIbDkdAZR0DAA5+UAtYCxwgNhxdRVggEg==",
"place_id": "NzYqAQYGQhoHWlpTOi0OLlIbDkdAZR0DAA5+UAtYCxwgNhxdRVggEg==",
"name": "明美",
"city": "台北市",
"town": "松山區",
"type": "地點",
"cat": "購物商場",
"distance": 2.212
},
{
"id": "NzYqAQYEQR8LWVtTQDwZFgkVPTZVekVeMy5VQUkfXiggTCRbDngkEg==",
"place_id": "NzYqAQYEQR8LWVtTQDwZFgkVPTZVekVeMy5VQUkfXiggTCRbDngkEg==",
"name": "明美公園",
"city": "台北市",
"town": "內湖區",
"type": "地點",
"cat": "公園",
"distance": 0.076
},
{
"id": "NzYqAQYCRxsDWl5TDSlXFgABEEJ+dThAMBsPcFkGSCgSFjJKc14kEg==",
"place_id": "NzYqAQYCRxsDWl5TDSlXFgABEEJ+dThAMBsPcFkGSCgSFjJKc14kEg==",
"name": "明美藥局",
"city": "台北市",
"town": "中山區",
"type": "地點",
"cat": "藥局",
"distance": 6.211
},
{
"id": "NzYqAQYBRh4KXFtTQS9dNFVSTSdqeQsBQgdAX15OJDglHhtWAgM8Eg==",
"place_id": "NzYqAQYBRh4KXFtTQS9dNFVSTSdqeQsBQgdAX15OJDglHhtWAgM8Eg==",
"name": "明美精品",
"city": "台南市",
"town": "中西區",
"type": "地點",
"cat": "購物商場",
"distance": 269.393
},
{
"id": "NzYqAQYBTR4EXV5TAw5SPT88DxxbAAJ8Py99V2BNEk4kPCVpfwRNEg==",
"place_id": "NzYqAQYBTR4EXV5TAw5SPT88DxxbAAJ8Py99V2BNEk4kPCVpfwRNEg==",
"name": "明美藥局",
"city": "屏東縣",
"town": "屏東市",
"type": "地點",
"cat": "藥局",
"distance": 289.058
},
{
"id": "NzYqAQYHRRwAXlhTDlt1LlcrDR10DzhiBzlDdw17VU8uTgFIeQAWEg==",
"place_id": "NzYqAQYHRRwAXlhTDlt1LlcrDR10DzhiBzlDdw17VU8uTgFIeQAWEg==",
"name": "三明美食",
"city": "新北市",
"town": "萬里區",
"type": "地點",
"cat": "中式美食",
"distance": 18.022
},
{
"id": "NzYqAQYGQhcKW1xTAhoFVzYxICVdRglGBh5ye2BmSAAvODBjQlgwEg==",
"place_id": "NzYqAQYGQhcKW1xTAhoFVzYxICVdRglGBh5ye2BmSAAvODBjQlgwEg==",
"name": "明美寢具行",
"city": "台北市",
"town": "中山區",
"type": "地點",
"cat": "居家修繕",
"distance": 5.743
},
{
"id": "NzYqAQYGQRgDVlNTMF4BAFEdOi1tDjtWJ15BBH1nFgsQPDt2Y3Q4Eg==",
"place_id": "NzYqAQYGQRgDVlNTMF4BAFEdOi1tDjtWJ15BBH1nFgsQPDt2Y3Q4Eg==",
"name": "明美服裝行",
"city": "台北市",
"town": "萬華區",
"type": "地點",
"cat": "購物商場",
"distance": 8.251
},
{
"id": "NzYqAQYGQRgDV1pTAC1xCjATMRJ6cy1RNRt/eWFBF00PCQ9VQlU0Eg==",
"place_id": "NzYqAQYGQRgDV1pTAC1xCjATMRJ6cy1RNRt/eWFBF00PCQ9VQlU0Eg==",
"name": "明美時裝社",
"city": "台北市",
"town": "萬華區",
"type": "地點",
"cat": "購物商場",
"distance": 8.945
},
{
"id": "NzYqAQYBTRoFVlpTFFx9TApAUkVyZx17OlMORgoMLRARLx1CelU4Eg==",
"place_id": "NzYqAQYBTRoFVlpTFFx9TApAUkVyZx17OlMORgoMLRARLx1CelU4Eg==",
"name": "明美傢俱行",
"city": "新北市",
"town": "三峽區",
"type": "地點",
"cat": "居家修繕",
"distance": 25.959
}
]
}
讓使用者邊輸入,便邊回應出推測的可能清單 -- 運用在逐字逼近搜尋目標物的場景上。
- API :
https://api.map8.zone/v2/place/autocomplete/<輸出格式>?<參數>
- HTTP Method :
- GET
- Synopsis
- <輸出格式>
- 選擇性參數,本版本不理會此參數,response 一律以 JSON 格式回應。
- <參數>
- key
- 必要參數,請帶進您的 key。
- input
- 必要參數,欲搜尋的關鍵詞 (無任何空白分隔) -- 通常是輸入欄當下的使用者輸入。例如
捷運大坪
。可以是地址、地名、商店名稱、或電話。
- 必要參數,欲搜尋的關鍵詞 (無任何空白分隔) -- 通常是輸入欄當下的使用者輸入。例如
- location
- 選擇性參數,要求系統依據給定的地理座標為搜尋中心點。格式為
<緯度>,<經度>
,分別為緯度與經度。 - 此參數若未給,則系統預設依照您發出此 request 的 IP address 來決定本 API 進行搜尋時的中心點。但請注意 : 此方式將增加額外的系統動作,可能因網路而造成搜尋速度相當幅度的延遲。因此,強烈建議您一律給
location=<緯度>,<經度>
參數
- 選擇性參數,要求系統依據給定的地理座標為搜尋中心點。格式為
- radius
- 選擇性參數,指定以上述
location
為中心,以本參數radius
指定方圓半徑之距離作為搜索範圍 (最大為 50.000 公里)。若未給,則由台灣圖霸系統自動智慧判斷。
- 選擇性參數,指定以上述
- strictbounds
- 選擇性參數 : 是否要求強制遵循上述
radius
參數之指定範圍 (true
/false
; 預設為false
; 請注意true
/false
值以 如字面 (string literal) 帶入,而非以 1 / 0 或其它字元帶入)。
- 選擇性參數 : 是否要求強制遵循上述
- key
- (Migration 指南) 與 Google Maps 的 Place Autocomplete API 相容性
- 除以上 參數 章節所描述的參數外,其他 Google Maps Place Autocomplete API 的參數 包括
sessiontoken
,offset
,language
,types
,components
,strictbounds
也均 ignore (因此,同樣地,您可自行決定要刪除或留著)。
- 除以上 參數 章節所描述的參數外,其他 Google Maps Place Autocomplete API 的參數 包括
- <輸出格式>
- Request Message Body: None.
Response
Status code : 200 OK
- 表示成功完成您的 request
Response Message Body
- Content-type: application/json
{ "html_attributions" : [ // 您必須向使用者表彰之本 API 所屬的圖資版權資訊 "台灣圖霸", "研鼎智能", "PAPAGO!" ], "predictions" : [ // `搜尋結果` 陣列 { "id" : <String>, // 此地點於台灣圖霸系統內的地點 ID "place_id" : <String>, // 此地點於台灣圖霸系統內的地點 ID "name" : <String>, // 本筆資料的名稱 (地名、道路名、地點名) (例如 "研鼎智能股份有限公司") "city" : <String>, // 本筆資料所屬的城市 (例如 "台北市") "town" : <String>, // 本筆資料所屬的行政區 (例如 "內湖區") "type" : <String>, // 本筆資料的類型,可為 : "地點", "地址", 或 "道路" "cat" : <String>, // 本筆資料於台灣圖霸系統內所歸屬的地點類型 (例如 "公司行號") "distance" : <Number>, // 本筆資料與輸入的中心點座標間的直線距離, 單位為 km }, ... (more results) ... ], "status" : <String> // Status Code }
- 上述每一筆搜尋結果內的各欄位, 若無值, 仍一律回傳, 但帶空值
- predictions 陣列帶回本次的預測結果。本 API 的查詢,最多將一次回應多達 10 筆資料
- 請注意 : 如同 Google,本
Autocomplete API
不會帶回詳細資料 (座標、電話等等)。請您以取得的place_id
呼叫 地點詳細資料 API 做為 Autocomplete API 的結尾,並獲取您所選擇之地點的詳細資料 - (Migration 指南) 與 Google Maps 的 Find Place API 相容性
Status code : 400 Bad Request
- 表示您的 request 系統偵測到有錯誤而無法完成您的要求。通常是給入的參數多了或少了,或是格式有錯誤,或必要參數卻沒給,等等
Response Message Body
- Content-type: application/json
{ "status" : <String> // Status Code }
參見 HTTP Status Code 一節說明本 API 回傳值之一般通則
參見 "status" 欄位 一節說明 "status" 欄位的一般性意義
[Places] 地址定位與反定位
功能 :
- 地址定位 (geocoding, 也就是將
地址 / 門牌
轉為地理座標經緯度
) - 與
- 反地址定位 (reverse geocoding, 反過來將地理座標
經緯度
轉為地址 / 門牌
)
Geocoding API
Syntax
https://api.map8.zone/v2/place/geocode/json?key=<您的 key>
&address=<地址>
&latlng=<緯度>,<經度>
提醒您 :
URL 所有以 query string 形式帶入的參數,應當都要視情況,適當地經過 URL encode 編碼後再傳入。
以免發生錯誤而收到 HTTP 400 Bad Request。
Example :
地址定位
(帶入address
參數)
HTTP GET "https://api.map8.zone/v2/place/geocode/json?key=<您的 key>&address=台北市內湖區新湖三路189號"
{
"html_attribution": [
"台灣圖霸",
"研鼎智能",
"PAPAGO!"
],
"results": [
{
"formatted_address": "台北市內湖區新湖三路189號",
"geometry": {
"location": {
"lat": 25.0650892053,
"lng": 121.580056243
}
},
"id": "IykqAAMHRBwCV1lTRl90F1RSSDB1fgl6LR1xCXF4Vhc3CxIJfEI0Eg==",
"place_id": "IykqAAMHRBwCV1lTRl90F1RSSDB1fgl6LR1xCXF4Vhc3CxIJfEI0Eg==",
"name": "新湖三路189號",
"city": "台北市",
"town": "內湖區",
"type": "地址",
"postcode": "114",
"level": "1",
"likelihood": -1,
"authoritative": "true"
}
],
"status": "OK"
}
Example :
反地址定位
(帶入latlng
參數)
HTTP GET "https://api.map8.zone/v2/place/geocode/json?key=<您的 key>&latlng=25.065089,121.580056"
{
"html_attributions" : [
"台灣圖霸",
"研鼎智能",
"PAPAGO!"
],
"results" : [
{
"formatted_address" : "台北市內湖區新湖三路189號6樓",
"geometry" : {
"location" : {
"lat" : 25.065089,
"lng" : 121.580056
},
},
"id" : "R625AYXZ38324999QP10236181",
"place_id" : "R625AYXZ38324999QP10236181",
"name" : "新湖三路189號",
"city" : "台北市",
"town" : "內湖區",
"type" : "地址",
}
],
"status" : "OK"
}
Example :
反地址定位
(帶入latlng
參數,並要求三碼郵遞區號)
HTTP GET "https://api.map8.zone/v2/place/geocode/json?key=<您的 key>&latlng=25.065089,121.580056&postcode"
{
"html_attribution": [
"台灣圖霸",
"研鼎智能",
"PAPAGO!"
],
"results": [
{
"formatted_address": "台北市內湖區新湖三路189號",
"name": "新湖三路189號",
"city": "台北市",
"town": "內湖區",
"postcode": "114"
}
],
"status": "OK"
}
Example :
反地址定位
(帶入latlng
參數,並要求三碼郵遞區號直接內嵌於formatted_address
欄位)
HTTP GET "https://api.map8.zone/v2/place/geocode/json?key=<您的 key>&latlng=25.065089,121.580056&postcode&formatted_address_embed_postcode"
{
"html_attributions" : [
"台灣圖霸",
"研鼎智能",
"PAPAGO!"
],
"results" : [
{
"formatted_address" : "114 台北市內湖區新湖三路189號6樓",
"geometry" : {
"location" : {
"lat" : 25.065089,
"lng" : 121.580056
},
},
"id" : "R625AYXZ38324999QP10236181",
"place_id" : "R625AYXZ38324999QP10236181",
"name" : "新湖三路189號",
"city" : "台北市",
"town" : "內湖區",
"type" : "地址",
}
],
"status" : "OK"
}
以下例為搜尋
address=台北市內湖區新湖三路189號
來說 :{ "html_attribution": [ "台灣圖霸", "研鼎智能", "PAPAGO!" ], "results": [ { "formatted_address": "台北市內湖區新湖三路189號", "geometry": { "location": { "lat": 25.0650892053, "lng": 121.580056243 } }, "id": "IykqAAMHRBwCV1lTRl90F1RSSDB1fgl6LR1xCXF4Vhc3CxIJfEI0Eg==", "place_id": "IykqAAMHRBwCV1lTRl90F1RSSDB1fgl6LR1xCXF4Vhc3CxIJfEI0Eg==", "name": "新湖三路189號", "city": "台北市", "town": "內湖區", "type": "地址", "postcode": "114", "level": "1", "likelihood": -1, "authoritative": "true" } ], "status": "OK" }
- 可以看到
"level": "1"
表示定位結果精確到門牌 (號
) - 此時,因為並非是模糊搜尋而得,因此
"likelihood": -1
- 而由於精確的定位結果到門牌,乃出自於 Map8 平台最具權威的門牌地址資料庫,因此,
authoritative
顯示為true
- 可以看到
然而,若搜尋的搜尋地址為
address=太平村下坑6號
:{ "html_attribution": [ "台灣圖霸", "研鼎智能", "PAPAGO!" ], "results": [ { "formatted_address": "嘉義縣梅山鄉太平村下坑6號", "geometry": { "location": { "lat": 23.562837, "lng": 120.596439 } }, "id": "NzYqAQYCTRcKV19TBgx6KTEbMSF/ARhXTysDdUxVX0AxIyR6Y1wCEg==", "place_id": "NzYqAQYCTRcKV19TBgx6KTEbMSF/ARhXTysDdUxVX0AxIyR6Y1wCEg==", "name": "雲海大飯店", "city": "嘉義縣", "town": "梅山鄉", "type": "地點", "postcode": "603", "level": "fuzzy", "likelihood": 82.38, "authoritative": "false" } ], "status": "OK" }
- 此地址實際上是個將錯就錯的例子 -- 台灣戶政司實際上查無此地址。此外,輸入的
address
參數非常破碎。 - 儘管如此,Map8 平台系統仍盡可能查詢到了有該地址的景點登錄資料。因此,可以看到
"level": "fuzzy"
表示定位結果為搜尋而得,且信心指數likelihood
超過 80% - 如上一點之說明,由於
嘉義縣梅山鄉太平村下坑6號
此一地址實際上並不存在,因此,authoritative
顯示為false
- 此地址實際上是個將錯就錯的例子 -- 台灣戶政司實際上查無此地址。此外,輸入的
又譬如搜尋地址為
address=新北市板橋區金門街215巷76之3號
:{ "html_attribution": [ "台灣圖霸", "研鼎智能", "PAPAGO!" ], "results": [ { "formatted_address": "新北市板橋區金門街215巷76-3號", "geometry": { "location": { "lat": 24.987083232098, "lng": 121.433119327778 } }, "id": "IykqAAUETR8CXV1TOjlSDiAISBBNVCFlRiF9AF9uJUAmLx5FXlACEg==", "place_id": "IykqAAUETR8CXV1TOjlSDiAISBBNVCFlRiF9AF9uJUAmLx5FXlACEg==", "name": "金門街215巷26之3號", "city": "新北市", "town": "板橋區", "type": "地址", "postcode": "220", "level": "-2", "likelihood": -1, "authoritative": "false" } ], "status": "OK" }
- 可以看到
"authoritative": "false"
,表示定位結果之"formatted_address": "新北市板橋區金門街215巷76-3號"
並不存在於 Map8 平台最具權威的門牌地址資料庫內 - 而
"level": "-2"
表示定位結果為同側雙號的內外插 (interpolation / extrapolation) 而得。也因為是透過內外插的定位結果,而非透過模糊搜尋,因此,"likelihood": -1
- 可以看到
- API :
https://api.map8.zone/v2/place/geocode/<輸出格式>?<參數>
- HTTP Method :
- GET
- Synopsis
- <輸出格式>
- 選擇性參數,本版本不理會此參數,response 一律以 JSON 格式回應。
- <參數>
- key
- 必要參數,請帶進您的 key。
- address
- 欲轉換為
經緯度
座標之地址
(若欲執行的是地址定位
,則此參數為必須)。
- 欲轉換為
- latlng
- 欲轉換為
地址
的經緯度
座標 (格式為<緯度>,<經度>
) (若欲執行的是反地址定位
,則此參數為必須)。
- 欲轉換為
- postcode
- 選擇性參數 : 是否需要回傳三碼郵遞區號 (
true
/false
; 預設為false
; 請注意true
/false
值以 如字面 (string literal) 帶入,而非以 1 / 0 或其它字元帶入)。
- 選擇性參數 : 是否需要回傳三碼郵遞區號 (
- formatted_address_embed_postcode
- 若上述
postcode
參數有被指定,則指定此參數以將三碼郵遞區號直接內嵌於 response 之formatted_address
欄位內 (否則,三碼郵遞區號將另以postcode
欄位回傳)。
- 若上述
- key
- (Migration 指南) 與 Google Maps 的 Geocoding API 相容性
- 除以上 參數 章節所描述的參數外,其他 Google Maps Geocoding API 的參數 包括
components
,bounds
,language
,region
均 ignore (因此,同樣地,您可自行決定要刪除或留著)。 - (Migration 指南) 與 Google Maps 的 Reverse Geocoding API 相容性
- 除以上 參數 章節所描述的參數外,其他 Google Maps Reverse Geocoding API 的參數 包括
language
,result_type
,location_type
均 ignore (因此,同樣地,您可自行決定要刪除或留著)。
- 除以上 參數 章節所描述的參數外,其他 Google Maps Reverse Geocoding API 的參數 包括
- 除以上 參數 章節所描述的參數外,其他 Google Maps Geocoding API 的參數 包括
- <輸出格式>
- Request Message Body: None.
Response
- Status code : 200 OK
- 表示成功完成您的 request
地址定位
Response Message Body
- Content-type: application/json
{ "html_attributions" : [ // 您必須向使用者表彰之本 API 所屬的圖資版權資訊 "台灣圖霸", "研鼎智能", "PAPAGO!" ], "results" : [ { "formatted_address" : <String>, // 地址 (經整理、格式化過的) "geometry" : { "location" : { "lat" : <Number>, // 緯度 "lng" : <Number> // 經度 }, }, "id" : <String>, // 此地點於台灣圖霸系統內的地點 ID "place_id" : <String>, // 此地點於台灣圖霸系統內的地點 ID "name" : <String>, // 本筆資料的名稱 (地名、道路名、地點名) (例如 "研鼎智能股份有限公司") "city" : <String>, // 本筆資料所屬的城市 (例如 "台北市") "town" : <String>, // 本筆資料所屬的行政區 (例如 "內湖區") "type" : <String>, // 本筆資料的類型,可為 : "地點"、"地址"、或 "道路" "postcode": <String>, // 本筆資料的三碼郵遞區號 "level": <String>, // 本筆資料定位結果之層級,請見底下說明 "likelihood": <Number>, // 本筆資料定位結果之信心指數,請見底下說明 "authoritative": <String> // 本筆資料定位結果是否出自於 Map8 最具正規權威性的地址門牌資料庫。若是,本欄位值為 `true`,否則為 `false` } ], "status" : <String> // Status Code }
- 上述每一筆搜尋結果內的各欄位, 若無值, 仍一律回傳, 但帶空值
- (Migration 指南) 與 Google Maps 的 Geocoding API 相容性
level : 定位結果的層級,可為 :
值 意義 6
縣市 5
鄉鎮市區 4
路、路段 3
巷 2
弄 1
號、之號 0
無法定位 -1
同號,"之號"內插,如10-3及10-8,內插出10-5的坐標 -2
同單雙號內插,如 4號及10號內插成8號,或3號、11號內插出7號 -3
不同單雙號內插,即4號、11號內插6號 -4
同號、不同之號的代表點,如以10-3的坐標當做10-5的坐標 -5
同單雙號的代表點,如以 4號的坐標當做10號的坐標 -6
不同單雙號的代表點,如以 4號的坐標當做7號的坐標 -7
同樣路名的其中一點,其他狀況,以同路名的第一門牌坐標為代表 fuzzy
地址定位結果乃透過模糊搜尋結果而得 likelihood : 定位結果之信心指數。為百分比,數值為介於 0 ~ 100 之間帶兩位小數。本欄位僅在於 level 為
fuzzy
時有效。否則值為-1
。authoritative : 定位結果是否出自於 Map8 最具正規 權威性 的 地址門牌資料庫。若是,本欄位值為
true
,否則為false
。
反地址定位
Response Message Body
- Content-type: application/json
{ "html_attributions" : [ // 您必須向使用者表彰之本 API 所屬的圖資版權資訊 "台灣圖霸", "研鼎智能", "PAPAGO!" ], "results" : [ // `搜尋結果` 陣列 { "formatted_address" : <String>, // 地址 (經整理、格式化過的) "name" : <String>, // 本筆資料的名稱 (地名、道路名、地點名) (例如 "研鼎智能股份有限公司") "city" : <String>, // 本筆資料所屬的城市 (例如 "台北市") "town" : <String>, // 本筆資料所屬的行政區 (例如 "內湖區") "postcode" : <String>, // 本筆地址之三碼郵遞區號 } ], "status" : <String> // Status Code }
Status code : 400 Bad Request
- 表示您的 request 系統偵測到有錯誤而無法完成您的要求。通常是給入的參數多了或少了,或是格式有錯誤,或必要參數卻沒給,等等
Response Message Body
- Content-type: application/json
{ "status" : <String> // Status Code }
參見 HTTP Status Code 一節說明本 API 回傳值之一般通則
參見 "status" 欄位 一節說明 "status" 欄位的一般性意義
- Status code : 200 OK
[Maps] 嵌入動態地圖
功能 : 在您的網站中嵌入互動地圖
Maps Embed API
Example (請於瀏覽器直接打開;或透過本文主說明示範之 iframe)
https://maps.map8.zone/?key=<您的 key>&title=研鼎智能&address=台北市內湖區新湖三路189號6樓&description=台灣圖霸,有口皆碑#15.6/25.065089/121.580056
Example : 加上 optional 的地圖視角 (請於瀏覽器直接打開;或透過本文主說明示範之 iframe)
https://maps.map8.zone/?key=<您的 key>&title=研鼎智能&address=台北市內湖區新湖三路189號6樓&description=台灣圖霸,有口皆碑#15.6/25.065089/121.580056/0/50
您也可以使用 iframe 方式來將台灣圖霸的地圖嵌入您的網站 -- 如下示範,只要將上述網址格式直接填入底下
<iframe>
標籤內的 src 欄位即可 :
<iframe src="https://maps.map8.zone/?key=<您的 key>&title=研鼎智能&address=台北市內湖區新湖三路189號6樓&description=台灣圖霸,有口皆碑#15.6/25.065089/121.580056/0/50" width="640" height="480">使用 <a href="https://www.map8.zone">台灣圖霸</a> 顯示 <a href="https://maps.map8.zone/?&title=研鼎智能&address=台北市內湖區新湖三路189號6樓&description=台灣圖霸,有口皆碑#15.6/25.065089/121.580056/0/50">地圖 (台灣圖霸地圖平台 Map8 Platform https://www.map8.zone)</a></iframe>
讓您在網站或其他任何素材中嵌入互動地圖
- API
https://maps.map8.zone/?<標記說明參數>#<座標視角參數>
- HTTP Method :
- GET
- Synopsis
- <標記說明參數> :
- 底下參數,用來讓您在地圖標記暨彈出視窗 (marker / popup) 上自訂您想要顯示的訊息。
- key
- 必要參數,請帶進您的 key。
- title
- 選擇性參數,欲顯示之標題 (格式為任意純文字)。
- address
- 選擇性參數,欲顯示之地址 (格式為任意純文字)。
- imgsrc
- 選擇性參數,欲顯示之圖片 (格式為圖片之 URL)。
- description
- 選擇性參數,欲顯示之附加說明 (格式為任意純文字)。
- <座標視角參數> :
- 底下這些井字符號
#
後綴的參數,用來讓您控制台灣圖霸地圖的顯示中心點、比例尺層級、視角等等。格式為#
後綴<縮放層級>/<緯度>/<經度>/<角度>/<視角>
。 - 這些井字符號
#
後綴的參數,無須代入參數名稱,直接給值 (因而是有順序性的,請務必依照順序,以使地圖能如您預期作動)。 - 縮放層級
- 必要參數,數值 1~20 (數值小為小比例尺,數值越大則比例尺越大;譬如 10 可以看到整個中台灣,而 19 則已經是特寫部分街廓)
- (您可以從我們線上地圖平台 https://maps.map8.zone 的網址列井字號
#
後面的第一個數字評估此數值)。
- (您可以從我們線上地圖平台 https://maps.map8.zone 的網址列井字號
- 必要參數,數值 1~20 (數值小為小比例尺,數值越大則比例尺越大;譬如 10 可以看到整個中台灣,而 19 則已經是特寫部分街廓)
- 緯度
- 必要參數,WGS84 / EPSG:4326 之緯度。
- 經度
- 必要參數,WGS84 / EPSG:4326 之經度。
- 角度
- 選擇性參數,數值-180~180,單位:度。為地圖的哪個方位朝上 (譬如, 0 表示地圖正北朝上)。
- 視角
- 選擇性參數,數值0~60,單位:度。為俯視地圖的角度 (譬如, 0 表示從正上方俯。瞰地圖,而 60 表示以與地平面夾 30 度角的方式俯瞰地圖)。
- 底下這些井字符號
- 直接利用智慧搜尋功能 :
- 若地理座標參數 緯度、經度 未給,而 title 或 address 有給,則台灣圖霸將以 title 與 address 直接進行智慧搜尋來顯示您的地標。
- <標記說明參數> :
- Request Message Body:
- N / A.
- Response
- N / A.
- Example
- https://maps.map8.zone/?key=<您的 key>&title=研鼎智能&address=台北市內湖區新湖三路189號6樓&description=台灣圖霸,有口皆碑#15.6/25.065089/121.580056
- 或是加上 optional 的地圖視角 : https://maps.map8.zone/?key=<您的 key>&title=研鼎智能&address=台北市內湖區新湖三路189號6樓&description=台灣圖霸,有口皆碑#15.6/25.065089/121.580056/0/50
- 您也可以使用 iframe 方式來將台灣圖霸的地圖嵌入您的網站 -- 如下示範,只要將上述網址格式直接填入底下
<iframe>
標籤內的 src 欄位即可 :<iframe src="https://maps.map8.zone/?key=<您的 key>&title=研鼎智能&address=台北市內湖區新湖三路189號6樓&description=台灣圖霸,有口皆碑#15.6/25.065089/121.580056/0/50" width="640" height="480">使用 <a href="https://www.map8.zone">台灣圖霸</a> 顯示 <a href="https://maps.map8.zone/?&title=研鼎智能&address=台北市內湖區新湖三路189號6樓&description=台灣圖霸,有口皆碑#15.6/25.065089/121.580056/0/50">地圖 (台灣圖霸地圖平台 Map8 Platform https://www.map8.zone)</iframe>
- 如下圖是 https://maps.map8.zone/?title=研鼎智能&address=台北市內湖區新湖三路189號6樓&description=台灣圖霸,有口皆碑&key=<您的 key>#15.6/25.065089/121.580056/0/50
- 或是更簡單點 : https://maps.map8.zone/?title=研鼎智能&address=台北市內湖區&key=<您的 key>,一樣可以獲得同上述的效果
- 如下圖是 https://maps.map8.zone/?title=在這裡集合&description=小7這裏&key=<您的_key>#16/25.043475/121.574023/-51.2/50
- back to index
[Maps] 地圖靜態圖片
功能 : 在您的網站中嵌入靜態地圖 (圖片)
Maps Static API
Example (請於瀏覽器直接打開)
https://api.map8.zone/maps/static?key=<您的 key>¢er=25.03745,121.547428&zoom=17&size=1024x768&format=jpg
製作顯示地圖的圖檔,讓您在網站或其他任何素材中嵌入靜態地圖
- API :
https://api.map8.zone/maps/staticmap?<參數>
- HTTP Method :
- GET
- Synopsis
- <參數>
- key
- 必要參數,請帶進您的 key。
- center
- 必要參數,欲製作成圖片的地圖中心點 (將與圖片四周等距離),格式為
<緯度>,<經度>
。
- 必要參數,欲製作成圖片的地圖中心點 (將與圖片四周等距離),格式為
- zoom
- 必要參數,整數,代表欲製作成圖片的地圖縮放層級 (比例尺) 。
- (數值小為小比例尺,數值越大則比例尺越大;譬如 10 可以看到整個中台灣,而 19 則已經是特寫部分街廓)。
- (您可以從我們線上地圖平台 https://maps.map8.zone 的網址列井字號
#
後面的第一個數字評估此數值)。
- size
- 必要參數,欲製作的圖片寬高。格式為
<寬>,<高>
(單位為 pixel)。
- 必要參數,欲製作的圖片寬高。格式為
- format
- 選擇性參數,欲製作的圖片格式。可為
png
或jpg
兩者之一。預設為png
。
- 選擇性參數,欲製作的圖片格式。可為
- key
- (Migration 指南) 與 Google Maps 的 Nearby Search API 相容性
- center 參數僅支援
<緯度>,<經度>
格式,不支援地址
。 - 其他 Google Maps Static API 的參數 包括
scale
,maptype
,language
,region
,markers
,path
,visible
,style
均 ignore (因此,同樣地,您可自行決定要刪除或留著)。
- center 參數僅支援
- <參數>
- Request Message Body:
- None.
- Response
- Status code : 200 OK
- 表示成功完成您的 request
- Response Message Body:
- 圖片本身
- 參見 HTTP Status Code 一節說明本 API 回傳值之一般通則
- Status code : 200 OK
- back to index
[Routes] 路徑規劃
功能 : 多點路徑規劃、多點旅行之距離時間矩陣
多點路徑規劃 API (Directions API)
Syntax
https://api.map8.zone/route/<交通工具>/<起訖點座標組>.json?key=<您的 key>
提醒您 :
URL 所有以 query string 形式帶入的參數,應當都要視情況,適當地經過 URL encode 編碼後再傳入。
以免發生錯誤而收到 HTTP 400 Bad Request。
Example : 此例以
car
(汽車) 作為交通工具 (請於瀏覽器直接打開)
HTTP GET "https://api.map8.zone/route/car/121.579839,25.065064;121.576499,25.068178;121.579343,25.068134.json?key=<您的 key>"
{{
"routes": [
{
"geometry": {
"coordinates": [
[
121.579839,
25.065064
],
[
121.579546,
25.064909
],
[
121.578805,
25.06596
],
[
121.578781,
25.06604
],
[
121.578521,
25.066659
],
[
121.578507,
25.066692
],
[
121.578494,
25.066722
],
[
121.578468,
25.066785
],
[
121.578467,
25.066786
],
[
121.578353,
25.067059
],
[
121.578264,
25.067271
],
[
121.578195,
25.067422
],
[
121.57813,
25.067532
],
[
121.576516,
25.067576
],
[
121.576499,
25.068178
],
[
121.576476,
25.069015
],
[
121.57716,
25.068802
],
[
121.578674,
25.068336
],
[
121.579343,
25.068134
]
],
"type": "LineString"
},
"legs": [
{
"steps": [],
"distance": 590.3,
"duration": 96,
"summary": "行愛路, 民權東路六段11巷"
},
{
"steps": [],
"distance": 398.1,
"duration": 65,
"summary": "瑞湖街, 民權東路六段15巷"
}
],
"distance": 988.4,
"duration": 161
}
],
"waypoints": [
{
"distance": 0,
"name": "新湖三路",
"location": [
121.579839,
25.065064
]
},
{
"distance": 0,
"name": "瑞湖街",
"location": [
121.576499,
25.068178
]
},
{
"distance": 0,
"name": "民權東路六段15巷",
"location": [
121.579343,
25.068134
]
}
]
}
(多點) 路徑規劃功能 : 依給定之起點、中途點 (零或多個)、與目的地之順序,以 Map8 的圖資與演算法來進行多點路徑規劃。
- API
https://api.map8.zone/route/<交通工具>/<起訖點座標組>.json?<參數>
- HTTP Method :
- GET
- Synopsis
- 交通工具
- 可為
car
(汽車)、bicycle
(自行車)、或foot
(步行)。
- 可為
- 起訖點座標組
- 格式為 :
<起點之經度>,<起點之緯度>;<中途點之經度>,<中途點之緯度>;...;<目的地之經度>,<目的地之緯度>.json
。亦即,乃以逗號分隔之<經度>,<緯度>
座標為一組,然後以分號分隔連接數組座標 (請注意,座標格式是<經度>,<緯度>
,而非<緯度>,<經度>
)。 第一組為起點,最後一組為目的地。而中間的數組則為要求路徑上必須經過的中途點 (waypoints)。
- 格式為 :
- <參數>
- key
- 必要參數,請帶進您的 key。
- alternatives
- 選擇性參數 : 是否多路徑規劃 (
true
/false
; 預設為false
; 請注意true
/false
值以 如字面 (string literal) 帶入,而非以 1 / 0 或其它字元帶入)。
- 選擇性參數 : 是否多路徑規劃 (
- steps
- 選擇性參數 : 是否需傳回所規劃路徑上的每一個詳細轉彎資訊 (
true
/false
; 預設為false
; 請注意true
/false
值以 如字面 (string literal) 帶入,而非以 1 / 0 或其它字元帶入)。 - 請注意: 此逐轉彎的詳細資訊,視所要求路徑規劃之情況,資料量可能相當龐大。
- 選擇性參數 : 是否需傳回所規劃路徑上的每一個詳細轉彎資訊 (
- overview
- 選擇性參數 : 是否需要傳回所規劃路徑的路線總覽 (可供您用於將路線繪製在 Map8 地圖上。請取用
geometry
欄位)。可為 :simplified
: 傳回精簡資料。false
: 不傳回。full
(預設值) : 傳回最詳細資料,以繪製出圖面上最為美觀的路徑幾何呈現,不會因為距離長短而有所解析度損失。
- (請注意以上之傳入值為 如字面 (string literal) 帶入,而非以 1 / 0 或其它字元帶入)。
- 選擇性參數 : 是否需要傳回所規劃路徑的路線總覽 (可供您用於將路線繪製在 Map8 地圖上。請取用
- geometries
- 選擇性參數,可為
polyline
,polyline6
, 或geojson
(預設為geojson
)。
- 選擇性參數,可為
- key
- 交通工具
- Request Message Body: None.
Response
- Status code : 200 OK
- 表示成功完成您的 request
回傳結構範例
Response Message Body:
- type: application/json
- 回傳的結構的各個欄位的資訊所代表之意義如后
{ "waypoints" : [ // 起點、中途點、或目的地之座標資訊 { "distance" : <Number>, // 自起點至此中途點的直線距離 (單位為公尺) "location" : [ // 為一帶有兩個元素之陣列,為 [<經度>, <緯度>] <Number>, <Number> ] "name" : <String>, // 此中途點所在的道路名稱 }, ... (more results)... ], "routes" : [ // 路徑規劃結果 { "legs" : [ // 路徑規劃的每一段 `路程` (兩中途點為一段 `路程`。亦即,若只有起訖點,則 `legs` 只會有一個元素。而若有一個中途點,則將有兩個元素。依此類推) { "steps" : [] "distance" : <Number> // 本段 `路程` 的距離 (單位為公尺) "summary" : <String> // 本段 `路程` 的摘要資訊 "duration" : <Number> // 本段 `路程` 的估計旅行時間 (單位為秒) } ], "geometry" : { "coordinates" : [Array], // 為一陣列,每個元素帶有兩個元素之陣列,分別為經度與緯度 (i.e., 此 `geometry` 陣列的每個元素為 [<經度>,<緯度>])。用以於地圖之圖面上繪製完整、美觀的路線圖 "type": "LineString" }, "distance" : <Number>, // 本路徑規劃的總距離 (單位為公尺) "duration" : <Number> // 本路徑規劃的總旅行時間 (單位為秒) }, ... (more results)... ] }
Status code : 400 Bad Request
- 表示您的 request 系統偵測到有錯誤而無法完成您的要求。通常是給入的參數多了或少了,或是格式有錯誤,或必要參數卻沒給,等等
Response Message Body:
- type: text/json
{ "status" : <String> // Status Code }
參見 HTTP Status Code 一節說明本 API 回傳值之一般通則
- Status code : 200 OK
(排班) 多點運算交通時間距離矩陣 API (Distance Matrix API)
Syntax
https://api.map8.zone/distancematrix/<交通工具>/<地點座標組>.json?key=<您的 key>&sourceIndices=<指定於地點座標組內之索引陣列以作為出發地>&destinationIndices=<指定於地點座標組內之索引陣列以作為目的地>&origins=<出發地之陣列>&destinations=<目的地之陣列>&annotations=<距離或時間>&language=<語系>
提醒您 :
URL 所有以 query string 形式帶入的參數,應當都要視情況,適當地經過 URL encode 編碼後再傳入。
以免發生錯誤而收到 HTTP 400 Bad Request。
範例 (1) : 此例以
car
(汽車) 作為交通工具,並採取(方式一) <地點座標組>
方式。透過sourceIndices
與destinationIndices
均不指定的方式,直接將全部的地點均作為出發地與目的地運算出矩陣。
HTTP GET "https://api.map8.zone/distancematrix/car/121.579839,25.065064;121.576499,25.068178;121.579343,25.068131.json?key=<您的 key>"
範例 (2) : 此例以
car
(汽車) 作為交通工具,採取(方式一) <地點座標組>
方式,並透過sourceIndices
與destinationIndices
指定出發地與目的地來運算出矩陣。
HTTP GET "https://api.map8.zone/distancematrix/car/121.579839,25.065064;121.576499,25.068178;121.579343,25.068131.json?key=<您的 key>&sourceIndices=0,1&destinationIndices=1,2"
範例 (3) : 此例以
car
(汽車) 作為交通工具,並採取(方式二) origins
/destinations
方式指定出發地與目的地。
HTTP GET "https://api.map8.zone/distancematrix/car/json?key=<您的 key>&origins=place_id:NzYqAQYCRh4EW19THlt1Uys9NR5eQQNTQg8EWHRZEUlfNQFyWURBEg==&destinations=研鼎智能|內湖區行政中心&language=zh_TW"
上開範例 (3) 的回應結果 :
{
"html_attribution": [
"台灣圖霸",
"研鼎智能",
"PAPAGO!"
],
"destinations": [
{
"routePoint": {
"location": [
121.580013,
25.065156
],
"name": "新湖三路",
"distance": 9
},
"place": {
"formatted_address": "台北市內湖區新湖三路189號",
"geometry": {
"location": {
"lat": 25.065089,
"lng": 121.580056
}
},
"id": "NzYqAQYARhkCVltTRRxiJBIYMDIIZgVSLyMdf25eBDIIPQ1VHWEwEg==",
"place_id": "NzYqAQYARhkCVltTRRxiJBIYMDIIZgVSLyMdf25eBDIIPQ1VHWEwEg==",
"name": "研鼎智能股份有限公司",
"city": "台北市",
"town": "內湖區",
"type": "地點",
"level": "fuzzy",
"likelihood": 75.59,
"authoritative": "false"
}
},
{
"routePoint": {
"location": [
121.588912,
25.06909
],
"name": "民權東路六段",
"distance": 15
},
"place": {
"formatted_address": "台北市內湖區民權東路六段99號",
"geometry": {
"location": {
"lat": 25.069226,
"lng": 121.588917
}
},
"id": "NzYqAQYHQxYAWFNTIytfLiYzKQRacCkDJSwPeQhsCyssSxNBZFQaEg==",
"place_id": "NzYqAQYHQxYAWFNTIytfLiYzKQRacCkDJSwPeQhsCyssSxNBZFQaEg==",
"name": "台北市內湖區行政中心",
"city": "台北市",
"town": "內湖區",
"type": "地點",
"level": "fuzzy",
"likelihood": 90.75,
"authoritative": "false"
}
}
],
"origins": [
{
"routePoint": {
"location": [
121.574564,
25.075867
],
"name": "港墘路",
"distance": 8
},
"place": {
"formatted_address": "台北市內湖區港墘路200號",
"geometry": {
"location": {
"lat": 25.075904,
"lng": 121.574494
}
},
"id": "NzYqAQYCRh4EW19THlt1Uys9NR5eQQNTQg8EWHRZEUlfNQFyWURBEg==",
"place_id": "NzYqAQYCRh4EW19THlt1Uys9NR5eQQNTQg8EWHRZEUlfNQFyWURBEg==",
"name": "研勤科技股份有限公司(PAPAGO)",
"city": "台北市",
"town": "內湖區",
"type": "地點",
"level": "1",
"likelihood": -1,
"authoritative": "false"
}
}
],
"rows": [
{
"elements": [
{
"duration": {
"value": 374,
"text": "6 分鐘"
},
"distance": {
"value": 1900,
"text": "1.9 公里"
},
"status": "OK"
},
{
"duration": {
"value": 565,
"text": "9 分鐘"
},
"distance": {
"value": 2803,
"text": "2.8 公里"
},
"status": "OK"
}
]
}
],
"status": "OK"
}
運算多對多起訖點之交通時間距離矩陣 (Distance Matrix)。
請注意,本 API 提供您兩個方式來指定出發地與目的地 :
(方式一)
<地點座標組>
: 先列出所有地點再指明哪些各為出發地與目的地- 此方式乃先以 GPS 座標方式列舉地點。
- 可再搭配以
sourceIndices
與destinationIndices
(兩者均為索引值陣列) 來指定 <地點座標組> 其中的哪些地點分別各為出發地、目的地。 - 若
sourceIndices
與destinationIndices
未給,則<地點座標組>
內的全部座標將均既作為出發地,也為目的地,來運算出矩陣。
(方式二)
origins / destinations
: 出發地與目的地各自獨立列舉- 此方式為不先將座標全數列出 (再指明出發地 / 目的地)。
- 反之,而是出發地與目的地,各自獨立列舉 (如同 Google Maps Platform 的 Distance Matrix API)。
- 此外,出發地與目的地的列舉方式 (均為陣列形式),除了座標,還可改以直接給地址。或是 Place API 所回應出的
place_id
。
- API
https://api.map8.zone/route/<交通工具>/<地點座標組>.json?<參數>
- HTTP Method :
- GET
- Synopsis
- 交通工具
- 可為
car
(汽車)、bicycle
(自行車)、或foot
(步行)。
- 可為
- 地點座標組
- 選擇性參數 : 此即上述 (方式一) 之以 GPS 座標方式指定地點 。後續可搭配以
sourceIndices
與destinationIndices
來指定 <地點座標組> 其中的哪些地點分別作為運算矩陣內所對應的出發地與目的地。 - 格式為 :
<地點之經度>,<地點之緯度>;<地點之經度>,<地點之緯度>;...;<地點之經度>,<地點之緯度>.json
。亦即,乃以逗號分隔之<經度>,<緯度>
座標為一組,然後以分號分隔連接數組座標 (請注意,座標格式是<經度>,<緯度>
,而非<緯度>,<經度>
)。 - 請注意 :
(方式一) <地點座標組>
與(方式二) origins / destinations
為二擇一。
- 選擇性參數 : 此即上述 (方式一) 之以 GPS 座標方式指定地點 。後續可搭配以
- <參數>
- key
- 必要參數,請帶進您的 key。
- sourceIndices
- 選擇性參數 : 若採取以
(方式一) <地點座標組>
方式指定地點,則應以此參數來指定出發地。 - 格式為 :
<index>, ..., <index>
(逗號分隔) -- i.e., 選擇出地點座標組
內的何者作為運算矩陣的出發地 (索引值以零起算)。 - 當採取
地點座標組
的方式來指定地點,若此參數未給,則預設將地點座標組
內的全部座標均作為出發地。 - 請注意 :
(方式一) <地點座標組>
與(方式二) origins / destinations
為二擇一。
- 選擇性參數 : 若採取以
- destinationIndices
- 選擇性參數。格式同上述
sourceIndices
。用以指定運算矩陣之目的地。(此外,同上述sourceIndices
,當採取地點座標組
的方式來指定地點,若此參數未給,則預設將地點座標組
內的全部座標均作為目的地。) - 請注意 :
(方式一) <地點座標組>
與(方式二) origins / destinations
為二擇一。
- 選擇性參數。格式同上述
- origins
- 選擇性參數 : 除了以
(方式一) <地點座標組>
的方式來指定,本方式即為上述(方式二) origins / destinations
: 讓您可以改以更為直覺的方式來指定數個出發地。透過本參數,您可以採用place_id
方式 (參見 Find Place API) 來指定出發地,甚或直接給予地址,讓台灣圖霸的 Geocoding API 自動為您進行搜尋定址。當然,您也可以在這個參數內直接給入座標。 - 格式為 :
<地址>|...|<地址>
-- i.e., 以豎線 (pipe character|
) 分隔之數個地點。其中,每個<地址>
有底下三種選擇 : - 請注意 :
(方式一) <地點座標組>
與(方式二) origins / destinations
為二擇一。
- 選擇性參數 : 除了以
- destinations
- 選擇性參數。格式同上述
origins
。用以指定運算矩陣之目的地。 - 請注意 :
(方式一) <地點座標組>
與(方式二) origins / destinations
為二擇一。
- 選擇性參數。格式同上述
- annotations
- 選擇性參數。可為
duration
或distance
或duration,distance
(逗號分隔)。
- 選擇性參數。可為
- language
- 選擇性參數。可為
en_US
或zh_TW
。預設為zh_TW
。用來顯示矩陣運算結果內的duration
/distance
之text
欄位 (將時間的秒、與距離的公尺數值,直接替您解譯成人類可以直接閱讀的字串。譬如 4096 會為您轉譯為 4.1 公里,而 7165 秒會為您轉譯為 1 hour 59 mins。是的,依據本參數所指定的語系來顯示)。
- 選擇性參數。可為
- key
- 交通工具
- Request Message Body: None.
Response
- Status code : 200 OK
- 表示成功完成您的 request
回傳結構範例
Response Message Body:
- type: application/json
- 回傳的結構的各個欄位的資訊所代表之意義如后
{ "status" : "Ok", // 處理完成 "destinations" : [ // 目的地之座標資訊 "routePoint": { // 實際用以計算路徑規劃的精確座標 (i.e., 輸入的座標經過黏到道路後的結果) "distance" : <Number>, // 實際用以計算路徑規劃的精確座標與所給之地點的距離 (單位為公尺) "location" : [ // 實際用以計算路徑規劃的精確座標。為一帶有兩個元素之陣列,為 [<經度>, <緯度>] <Number>, <Number> ] "name" : <String>, // 實際用以計算路徑規劃的精確座標所在的道路名稱 }, "place": { ... // 此即為 Geocoding API 的 [地址定位] 的回應結果 results[] 陣列中的物件。請詳見 [Geocoding API](https://www.map8.zone/map8-api-docs/#places-2) 的 [Response > 地址定位] 章節的內容 }, ... (more results)... ], "origins" : [ // 出發地之座標資訊 ... // 結構同上 `destinations` ], "rows": [ // 此為運算結果的矩陣。`rows` 的每一列,表示每個出發地。其中,`elements` 陣列,即為每個出發地到每個目的地的計算結果 { "elements": [ // 某出發地對每個目的地之運算結果陣列 { "duration": { "value": <Number> // 計算得的數值 "text": <String> // 上開數值,依據語系轉譯成文字。譬如,374 將轉譯為 "6 分鐘" (若 `language` 參數為 "zh_TW") }, "distance": { "value": <Number> // 計算得的數值 "text": <String> // 上開數值,依據語系轉譯成文字。譬如,1900 將轉譯為 "1.9 公里" (若 `language` 參數為 "zh_TW") }, "status": "OK" // 處理完成 }, ... (more results) ... ] } ], }
Status code : 400 Bad Request
- 表示您的 request 系統偵測到有錯誤而無法完成您的要求。通常是給入的參數多了或少了,或是格式有錯誤,或必要參數卻沒給,等等
Response Message Body:
- type: text/json
{ "status" : <String> // Status Code }
參見 HTTP Status Code 一節說明本 API 回傳值之一般通則
- Status code : 200 OK
(排行程) 多途經點排序路徑規劃 API (Trip API)
Syntax
https://api.map8.zone/trip/<交通工具>/<地點座標組>.json?key=<您的 key>&waypoints=<地點陣列>&source=<起點選項>&destination=<終點選項>&roundtrip=<是否返回出發地>&language=<語系>&overview=<路線總覽選項>&geometries=<路線繪製編碼選項>
提醒您 :
URL 所有以 query string 形式帶入的參數,應當都要視情況,適當地經過 URL encode 編碼後再傳入。
以免發生錯誤而收到 HTTP 400 Bad Request。
範例 (1) : 此例以
car
(汽車) 作為交通工具,並採取地點座標組
方式。不指定任何地點身為起點或終點,由系統預設返回起點的方式,進行路徑規劃並求出行程上每個地點都必須通過的最佳順序路徑 (語系指定為英文)。
HTTP GET "https://api.map8.zone/trip/car/121.580056,25.065089;121.574494,25.075904;121.585842,25.081139;121.575922,25.062935.json?key=<您的 key>&language=en_US"
範例 (2) : 此例以
car
(汽車) 作為交通工具,採取地點陣列
方式,指定起點並返回為條件,進行路徑規劃並求出行程上每個地點都必須通過的最佳順序路徑。
HTTP GET "https://api.map8.zone/trip/car/json?key=<您的 key>&waypoints=研鼎智能|研勤科技|碧湖公園&source=first&roundtrip=true"
上開範例 (2) 的回應結果,您可以見到,給定的地點依序為
研鼎智能 (編號 0)
、研勤科技 (編號 1)
、碧湖公園 (編號 2)
。由於回應結果之waypoints
陣列內物件依序即為運算求得的最佳順序,故依據waypoint_index
(依序為 0, 2, 1) 來解讀運算結果,可得系統規劃出之最佳順序為研鼎智能
⇒碧湖公園
⇒研勤科技
⇒研鼎智能
(終點是因為指定了roundtrip=true
要求返回起點)。如下 :
{
"html_attribution": [
"台灣圖霸",
"研鼎智能",
"PAPAGO!"
],
"trips": [
{
"waypoints": [
{
"routePoint": {
"waypoint_index": 0,
"location": [
121.580013,
25.065156
],
"name": "新湖三路",
"distance": 9
},
"place": {
"formatted_address": "台北市內湖區新湖三路189號",
"geometry": {
"location": {
"lat": 25.065089,
"lng": 121.580056
}
},
"id": "NzYqAQYARhkCVltTRRxiJBIYMDIIZgVSLyMdf25eBDIIPQ1VHWEwEg==",
"place_id": "NzYqAQYARhkCVltTRRxiJBIYMDIIZgVSLyMdf25eBDIIPQ1VHWEwEg==",
"name": "研鼎智能股份有限公司",
"city": "台北市",
"town": "內湖區",
"type": "地點",
"level": "fuzzy",
"likelihood": 75.59,
"authoritative": "false"
}
},
{
"routePoint": {
"waypoint_index": 2,
"location": [
121.574564,
25.075867
],
"name": "港墘路",
"distance": 8
},
"place": {
"formatted_address": "台北市內湖區港墘路200號",
"geometry": {
"location": {
"lat": 25.075904,
"lng": 121.574494
}
},
"id": "NzYqAQYCRh4EW19THlt1Uys9NR5eQQNTQg8EWHRZEUlfNQFyWURBEg==",
"place_id": "NzYqAQYCRh4EW19THlt1Uys9NR5eQQNTQg8EWHRZEUlfNQFyWURBEg==",
"name": "研勤科技股份有限公司(PAPAGO)",
"city": "台北市",
"town": "內湖區",
"type": "地點",
"level": "fuzzy",
"likelihood": 69.28,
"authoritative": "false"
}
},
{
"routePoint": {
"waypoint_index": 1,
"location": [
121.585888,
25.08098
],
"name": "內湖路二段",
"distance": 18
},
"place": {
"formatted_address": "台北市內湖區",
"geometry": {
"location": {
"lat": 25.081139,
"lng": 121.585842
}
},
"id": "NzYqAQYCRh4BWFlTGFtaLUxPSwBXUSJUNF94Glt7SDYTSC1DRXE8Eg==",
"place_id": "NzYqAQYCRh4BWFlTGFtaLUxPSwBXUSJUNF94Glt7SDYTSC1DRXE8Eg==",
"name": "碧湖公園",
"city": "台北市",
"town": "內湖區",
"type": "地點",
"level": "fuzzy",
"likelihood": 100,
"authoritative": "false"
}
}
],
"duration": {
"value": 1169,
"text": "19 分鐘"
},
"distance": {
"value": 5951,
"text": "6.0 公里"
},
"geometry": {
"coordinates": [
... (此為經緯度座標陣列, 供繪製地圖之用; 略)...
],
"type": "LineString"
}
}
],
"status": "OK"
}
給定多途經點,排出次序並規劃路徑 (旅行業務員 / Travelling Salesman Problem (TSP) 最短路徑問題)
請注意,本 API 提供您兩個方式來指定出發地與目的地 :
(方式一)
<地點座標組>
: 以 GPS 座標方式列舉地點。(方式二)
<地點陣列> 給入地址或地名
:- 透過
waypoints
參數,直接給予地址 (或地點名稱),讓台灣圖霸的 Geocoding API 自動為您進行搜尋定址。 - 或是
place_id
方式 (參見 Find Place API) 來指定地點。 - 當然,您也可以在這個參數內直接給入座標。
- 透過
- API
https://api.map8.zone/trip/<交通工具>/<地點座標組>.json?<參數>
- HTTP Method :
- GET
Synopsis
- 交通工具
- 可為
car
(汽車)、bicycle
(自行車)、或foot
(步行)。
- 可為
- 地點座標組
- 選擇性參數 : 此方式乃以 GPS 座標方式指定地點。
- 格式為 :
<地點之經度>,<地點之緯度>;<地點之經度>,<地點之緯度>;...;<地點之經度>,<地點之緯度>.json
。亦即,乃以逗號分隔之<經度>,<緯度>
座標為一組,然後以分號分隔連接數組座標 (請注意,座標格式是<經度>,<緯度>
,而非<緯度>,<經度>
)。
<參數>
- key
- 必要參數,請帶進您的 key。
- waypoints
- 選擇性參數 : 除了以
地點座標組
的方式來指定,您可以改採更為直覺的方式來指定數個地點。透過本參數,您可以採用place_id
方式 (參見 Find Place API) 來指定地點,甚或直接給予地址,讓台灣圖霸的 Geocoding API 自動為您進行搜尋定址。當然,您也可以在這個參數內直接給入座標。 - 格式為 :
<地點>|...|<地點>
-- i.e., 以豎線 (pipe character|
) 分隔之數個地點。其中,每個<地點>
有底下三種選擇 :
- 選擇性參數 : 除了以
- source
- 選擇性參數 : 可為
any
或first
。後者 (first
) 表示欲將透過地點座標組
或waypoints
所指定之地點中的第一個地點作為求最佳路徑順序的起點。any
表示不限制 (所給之任一地點均可作為起點)。預設為any
。請注意系統進行路徑規劃之運算對於source
,destination
與roundtrip
有互相搭配的要求。詳見底下表格。
- 選擇性參數 : 可為
- destination
- 選擇性參數 : 可為
any
或last
。後者 (last
) 表示欲將透過地點座標組
或waypoints
所指定之地點中的最後一個地點作為求最佳路徑順序的終點。any
表示不限制 (所給之任一地點均可作為終點)。預設為any
。請注意系統進行路徑規劃之運算對於source
,destination
與roundtrip
有互相搭配的要求。詳見底下表格。
- 選擇性參數 : 可為
roundtrip
- 選擇性參數 : 指定所求最佳路徑順序是否要求返回起點 (
true
/false
; 預設為false
; 請注意true
/false
值以 如字面 (string literal) 帶入,而非以 1 / 0 或其它字元帶入)。 source
,destination
與roundtrip
必須互相搭配。系統目前支援的組合如下表 :source destination roundtrip 支援與否 first
last
true
是 first
any
true
是 any
last
true
是 any
any
true
是 first
last
false
是 first
any
false
否 any
last
false
否 any
any
false
否 - 若您指定的組合不受支援,則系統會回應您
{"status":"INVALID_REQUEST","message":"NotImplemented"}
。
- 若您指定的組合不受支援,則系統會回應您
- 選擇性參數 : 指定所求最佳路徑順序是否要求返回起點 (
language
- 選擇性參數。可為
en_US
或zh_TW
。預設為zh_TW
。用來顯示矩陣運算結果內的duration
/distance
之text
欄位 (直接將時間 / 距離的秒 / 公尺數值,為您解析成人類可以直接閱讀的字串。譬如 4096 會為您轉譯為 4.1 公里,而 7165 秒會為您轉譯為 1 hour 59 mins。是的,依據本參數所指定的語系來顯示)。
- 選擇性參數。可為
overview
- 選擇性參數 : 是否需要傳回所規劃路徑的路線總覽 (可供您用於將路線繪製在 Map8 地圖上。請取用
geometry
欄位)。可為 :simplified
: 傳回精簡資料。false
: 不傳回。full
(預設值) : 傳回最詳細資料,以繪製出圖面上最為美觀的路徑幾何呈現,不會因為距離長短而有所解析度損失。
- 選擇性參數 : 是否需要傳回所規劃路徑的路線總覽 (可供您用於將路線繪製在 Map8 地圖上。請取用
geometries
- 選擇性參數,可為
polyline
,polyline6
, 或geojson
(預設為geojson
)。
- 選擇性參數,可為
- key
- 交通工具
Request Message Body: None.
Response
- Status code : 200 OK
- 表示成功完成您的 request
回傳結構範例
Response Message Body:
- type: application/json
- 回傳的結構的各個欄位的資訊所代表之意義如后
{ "status" : "Ok", // 處理完成 "trips" : [ { "waypoints" : [ // 地點資訊陣列。依序為系統求出所經過地點之最佳順序 { "routePoint": { // 實際用以計算路徑規劃的精確座標 (i.e., 輸入的座標經過黏到道路後的結果) "distance" : <Number>, // 實際用以計算路徑規劃的精確座標與所給之地點的距離 (單位為公尺) "location" : [ // 實際用以計算路徑規劃的精確座標。為一帶有兩個元素之陣列,為 [<經度>, <緯度>] <Number>, <Number> ] "name" : <String>, // 實際用以計算路徑規劃的精確座標所在的道路名稱 "waypoint_index": <Number>, // 此地點所參照到輸入之 `地點陣列 (也就是輸入的 `waypoints` 參數) 內之索引編號 (從零起算) }, "place": { ... // 此即為 Geocoding API 的 [地址定位] 的回應結果 results[] 陣列中的物件。請詳見 [Geocoding API](https://www.map8.zone/map8-api-docs/#places-2) 的 [Response > 地址定位] 章節的內容 }, }, ... (more results)... ], "duration": { "value": <Number> // 計算得的數值 "text": <String> // 上開數值,依據語系轉譯成文字。譬如,374 將轉譯為 "6 分鐘" (若 `language` 參數為 "zh_TW") }, "distance": { "value": <Number> // 計算得的數值 "text": <String> // 上開數值,依據語系轉譯成文字。譬如,1900 將轉譯為 "1.9 公里" (若 `language` 參數為 "zh_TW") }, } "geometry" : { "coordinates" : [Array], // 為一陣列,每個元素帶有兩個元素之陣列,分別為經度與緯度 (i.e., 此 `geometry` 陣列的每個元素為 [<經度>,<緯度>])。用以於地圖之圖面上繪製完整、美觀的路線圖 "type": "LineString" }, ... (more results)... ] }
Status code : 400 Bad Request
- 表示您的 request 系統偵測到有錯誤而無法完成您的要求。通常是給入的參數多了或少了,或是格式有錯誤,或必要參數卻沒給,等等
Response Message Body:
- type: text/json
{ "status" : <String> // Status Code }
參見 HTTP Status Code 一節說明本 API 回傳值之一般通則
- Status code : 200 OK
[Roads] 道路資訊
功能 : 取得道路屬性與黏路
道路屬性 API (Nearest Roads API)
Syntax
https://api.map8.zone/road/nearestRoads/<交通工具>?key=<您的 key>
&latlng=<緯度>,<經度>
&additional_fields
提醒您 :
URL 所有以 query string 形式帶入的參數,應當都要視情況,適當地經過 URL encode 編碼後再傳入。
以免發生錯誤而收到 HTTP 400 Bad Request。
Example : 此例以
car
(汽車) 作為交通工具
HTTP GET "https://api.map8.zone/road/nearestRoads/car?key=<您的 key>&latlng=25.073448,121.544539&additional_fields=speed,elevated,height,bridge"
{
"html_attribution": [
"台灣圖霸",
"研鼎智能",
"PAPAGO!"
],
"results": [
{
"formatted_address": "台北市中山區 - 中山高汐五高架道路",
"id": "",
"place_id": "",
"name": "中山高汐五高架道路",
"city": "台北市",
"town": "中山區",
"type": "道路",
"distance": 5.10,
"speed": "100",
"elevated": "1",
"height": "",
"bridge": ""
}
],
"status": "OK"
}
對道路進行反定址 (也就是由輸入之地理座標轉為道路),並獲取道路屬性 (速限、高架、橋樑、限高)。
- API :
https://api.map8.zone/road/nearestRoads/<交通工具>?<參數>
- HTTP Method :
- GET
Synopsis
<參數>
- key
- 必要參數,請帶進您的 key。
- 交通工具
- 目前僅支援
car
(汽車)。
- 目前僅支援
- latlng
- 欲取得之
道路
的經緯度
座標 (格式為<緯度>,<經度>
)。
- 欲取得之
additional_fields
指定欲額外索取之欄位,可為 :
值 意義 speed
道路速限 (KPH) height
道路限高 (公尺) elevated
若道路為高架,傳回 1
,平面傳回0
,地下道傳回-1
bridge
若道路為橋,傳回橋名 可指定多個欄位 -- 請以逗點分隔即可,例如
&additional_fields=speed,elevated,height,bridge
。
進階參數 :
- 底下進階選項 (選擇性參數) 可以用來讓您指定更多的定位條件,以取得更優良的定位結果。
- bearing
- 指明座標 (
latlng
參數) 所伴隨之行進方向。為與正北 (true north) 的夾角。範圍為 0 ~ 360 (i.e., 單位為 degree)。
- 指明座標 (
- range
- 指定上述角度 (
bearing
參數) 的容許偏差範圍。合法數值為 0 ~ 180 (i.e., 單位為 degree)。當此參數被指定時,bearing
參數也應被指定。
- 指定上述角度 (
- radius
- 對
道路
進行反定址時所容許的距離範圍。一般應為於實際位置進行 GPS 定位經緯度
座標時所獲得的誤差值。單位為公尺 (meter; m)。 - (以手機而言,您可以考慮使用 Android 的
Location.getAccuracy()
或是 iOS 的CLLocation.horizontalAccuracy
。)
- 對
- 以上參數如圖解 :
- 舉例 : 右方範例之地點,為中山高速公路 (東西向) 與大直橋 (南北向) 之複雜立體交叉路口。藉由指定上述參數 (下例指定為北方偏東 2 度,允許定位誤差為 ±1.5 度),即可獲得所希望的結果 :
HTTP GET "https://api.map8.zone/road/nearestRoads/car?key=<您的 key>&latlng=25.073448,121.544539&additional_fields=speed,elevated,height,bridge&bearing=2&range=3"
{ "html_attribution": [ "台灣圖霸", "研鼎智能", "PAPAGO!" ], "results": [ { "formatted_address": "台北市中山區 - 大直橋明水路方向", "id": "", "place_id": "", "name": "大直橋明水路方向", "city": "台北市", "town": "中山區", "type": "道路", "distance": 10.19, "speed": "50", "elevated": "1", "height": "", "bridge": "大直橋明水路方向" } ], "status": "OK" }
- key
Request Message Body: None.
Response
Status code : 200 OK
- 表示成功完成您的 request
Response Message Body
- Content-type: application/json
{ "html_attributions" : [ // 您必須向使用者表彰之本 API 所屬的圖資版權資訊 "台灣圖霸", "研鼎智能", "PAPAGO!" ], "results" : [ // `搜尋結果` 陣列 { "formatted_address" : <String>, // 地址 (經整理、格式化過的) "id" : <String>, // 此地點於台灣圖霸系統內的地點 ID "place_id" : <String>, // 此地點於台灣圖霸系統內的地點 ID "name" : <String>, // 本筆資料的名稱 (地名、道路名、地點名) (例如 "研鼎智能股份有限公司") "city" : <String>, // 本筆資料所屬的城市 (例如 "台北市") "town" : <String>, // 本筆資料所屬的行政區 (例如 "內湖區") "type" : <String>, // 本筆資料的類型,為 "道路" "speed" : <String>, // 本筆資料之道路速限 (KPH) "height" : <String>, // 本筆資料之道路限高 (公尺) "elevated" : <String>, // 本筆資料之道路若為高架,傳回 `1`,平面傳回 `0`,地下道傳回 `-1` "bridge" : <String>, // 本筆資料之道路若為橋,傳回橋名 } ], "status" : <String> // Status Code }
- 上述每一筆搜尋結果內的各欄位, 若無值, 仍一律回傳, 但帶空值
Status code : 400 Bad Request
- 表示您的 request 系統偵測到有錯誤而無法完成您的要求。通常是給入的參數多了或少了,或是格式有錯誤,或必要參數卻沒給,等等
Response Message Body
- Content-type: application/json
{ "status" : <String> // Status Code }
參見 HTTP Status Code 一節說明本 API 回傳值之一般通則
參見 "status" 欄位 一節說明 "status" 欄位的一般性意義
黏路 API (Snap to Roads API)
Syntax
https://api.map8.zone/road/snapToRoads/<交通工具>/<路徑點座標組>.json?key=<您的 key>
提醒您 :
URL 所有以 query string 形式帶入的參數,應當都要視情況,適當地經過 URL encode 編碼後再傳入。
以免發生錯誤而收到 HTTP 400 Bad Request。
Example : 此例以
car
(汽車) 作為交通工具
HTTP GET "https://api.map8.zone/road/snapToRoads/car/121.57984055289461,25.06516253907658;121.58269442328509,25.06609550812837;121.58453978308859,25.065648461344452;121.58522642859657,25.06419068875931;121.58535517462786,25.062344151916164.json?key=<您的 key>"
{
"html_attribution": [
"台灣圖霸",
"研鼎智能",
"PAPAGO!"
],
"matchings": [
{
"tracepoints": [
{
"alternatives_count": 0,
"waypoint_index": 0,
"location": [
121.579888,
25.06509
],
"name": "新湖三路",
"distance": 9
},
{
"alternatives_count": 0,
"waypoint_index": 1,
"location": [
121.582659,
25.066212
],
"name": "新湖三路",
"distance": 13
},
{
"alternatives_count": 0,
"waypoint_index": 2,
"location": [
121.584532,
25.065644
],
"name": "新湖三路",
"distance": 1
},
{
"alternatives_count": 0,
"waypoint_index": 3,
"location": [
121.585359,
25.064153
],
"name": "行善路",
"distance": 14
},
{
"alternatives_count": 1,
"waypoint_index": 4,
"location": [
121.585366,
25.062366
],
"name": "行善路333巷",
"distance": 3
}
],
"geometry": {
"coordinates": [
... (此為經緯度座標陣列, 供繪製地圖之用; 略)...
],
"type": "LineString"
}
}
],
"status": "OK"
}
給定一路徑依序之座標點,對地圖黏岀最可能路徑 (黏路)。
- API :
https://api.map8.zone/road/snapToRoads/<交通工具>/<路徑點座標組>.json?<參數>
- HTTP Method :
- GET
- Synopsis
- 交通工具
- 可為
car
(汽車)、bicycle
(自行車)、或foot
(步行)。
- 可為
- 路徑點座標組
- 格式為 :
<路徑起點之經度>,<路徑起點之緯度>;<路徑中途點之經度>,<路徑中途點之緯度>;...;<路徑終點之經度>,<路徑終點之緯度>.json
。亦即,乃以逗號分隔之<經度>,<緯度>
座標為一組,然後以分號分隔連接數組座標 (請注意,座標格式是<經度>,<緯度>
,而非<緯度>,<經度>
)。 第一組為起點,最後一組為終點。而中間的數組則為路徑上依序經過的中途點 (waypoints)。
- 格式為 :
- <參數>
- key
- 必要參數,請帶進您的 key。
- key
- 交通工具
- Request Message Body: None.
Response
- Status code : 200 OK
- 表示成功完成您的 request
回傳結構範例
Response Message Body:
- type: application/json
- 回傳的結構的各個欄位的資訊所代表之意義如后
{ "html_attribution": [ "台灣圖霸", "研鼎智能", "PAPAGO!" ], "status" : "Ok", // 處理完成 "matchings": [ // 黏路結果陣列; 視狀況,可能有多種黏路結果 { "tracepoints": [ // 其一黏路結果。陣列中的每個元素,依序為黏路結果的順序。每個元素並針對輸入的 `路徑點座標組` 回傳結果出來。`請注意` : 此陣列內之元素之值可能為 `null` : 表示所對應的 `路徑點座標組` 之黏路結果為失敗。 { "alternatives_count": <Number>, // 此黏到路的地點,另有多少個可黏到路的地點之數量 (表示有其他可能性) "waypoint_index": <Number>, // 此黏到路的地點,為整個陣列中,屬有效黏路 (i.e., 非 null) 元素中的第幾個 (索引編號; 從零起算) "location": [ // 為一帶有兩個元素之陣列,為 [<經度>, <緯度>] <Number>, <Number> ], "name": <String>, // 此黏到路的地點被匹配到的道路名稱 "distance": <Number> // 此黏到路的地點,至被匹配到的道路的直線距離 (單位為公尺) }, ... (more results) ... ], "geometry" : { "coordinates" : [Array], // 為一陣列,每個元素帶有兩個元素之陣列,分別為經度與緯度 (i.e., 此 `geometry` 陣列的每個元素為 [<經度>,<緯度>])。用以於地圖之圖面上繪製完整、美觀的路線圖 "type": "LineString" }, }, ... (more results) ... ] }
Status code : 400 Bad Request
- 表示您的 request 系統偵測到有錯誤而無法完成您的要求。通常是給入的參數多了或少了,或是格式有錯誤,或必要參數卻沒給,等等
Response Message Body:
- type: text/json
{ "status" : <String> // Status Code }
參見 HTTP Status Code 一節說明本 API 回傳值之一般通則
- Status code : 200 OK
https://map8.zone
HTTP Status Code
以上 API,可能回傳的 HTTP status code 如后 :
Error Code | 意義 |
---|---|
400 | Bad Request -- 表示您的 requset 解析有誤。通常是給入的參數多了或少了,或是格式有錯誤,或必要參數卻沒給,等等 |
401 | Unauthorized -- 表示您未給定您的 key,或是您給的 key 並非有效。請跟我們聯絡 |
503 | Service Unavailable -- 表示您的 request 已經超出與我們約定的 QoS (服務品質) 等級。通常過一會兒 (QoS 上限解除) 再重發一次即可成功。如果持續發生,請跟我們聯絡 |
"status" 欄位
以上 API,可能回傳之 status
欄位的意義為 :
status 值 |
意義 |
---|---|
OK |
無發生任何錯誤;該地點被成功偵測,並且至少回傳一則結果 |
ZERO_RESULTS |
表示搜尋雖然完成,但未得到任何有效結果。此狀況譬如可能發生在您對本 API 發出的 request 所給定的中心座標在一個偏遠地區 |
OVER_QUERY_LIMIT |
表示您已經超出您的配額。請跟我們聯絡 |
REQUEST_DENIED |
表示您的 request 無法進行;一般來說是您未給定您的 key,或是您給的 key 並非有效。請跟我們聯絡 |
INVALID_REQUEST |
表示您的 requset 解析有誤。通常是給入的參數多了或少了,或是格式有錯誤,或必要參數卻沒給,等等 |
UNKNOWN_ERROR |
表示是我們的伺服器端的錯誤;再重試一次可能就會成功。如果持續發生此問題,請跟我們聯絡 |
地點類型
所支援的景點類型,為字串,如下 :
- 公路里程
- 交流道入口
- 國道設施
- 國小
- 郵局
- 農漁會
- 休閒渡假
- 遊樂園區
- 寺廟
- 風景區
- 農牧事業區
- 地名
- 幼兒園
- 圖書館
- 村里
- 消防單位
- 軍警單位
- 山岳
- 國中
- 電信公司
- 加油站
- 公眾服務
- 社福機構
- 藝文美術
- 停車場
- 文化紀念
- 公司行號
- 民宿
- 古蹟
- 政府機關
- 衛生所
- 便利商店
- 購物商場
- 旅遊服務中心
- 溫泉
- 墓園
- 飯店旅館
- 森林遊樂區
- 高中職校
- 中式美食
- 露營營地
- 湖泊水庫
- 咖啡茶藝
- 博物館
- 公園
- 體育館
- 診所
- 糕點烘焙
- 汽車展售
- 藥局
- 輪車保修
- 貨運站
- 異國美食
- 生活量販
- 公車站
- 銀行
- 3C賣場
- 居家修繕
- 不動產
- 飲料冰品
- 超級市場
- 影視娛樂
- 補習進修
- 傳統市場
- 醫院
- 高爾夫
- 汽車百貨
- 書局
- 工業區
- 行人出入口
- 體育場
- 證券投資
- 保險公司
- 速食
- 火車站
- 寵物
- 夜市
- 地方小吃
- 觀光工廠
- 大專院校
- 污水處理場
- 國家公園
- 其他
- 渡口碼頭
- 纜車站
- 商圈
- 信用合作社
- 租車公司
- 教堂
- 素食
- 百貨公司
- 外語學校
- 拖吊場
- 動物園
- 自行車道
- 夜生活
- 漁港
- 海濱遊憩
- 美容美髮
- 機場
- 出入口
- 高鐵站
- 捷運站
- 大樓
- 汽車出入口
- 商港
- 自行車出入口
- 社區
- 加氣站
- 充電站
- 公益彩券
- ATM
- 快捷巴士