NAV Navbar
範例

Introduction

感謝您使用 Logo 28x28 台灣圖霸 | Map8 Platform 地圖平台 -- 客供地理資料 (MyPlaces) API！

MyPlaces API 為 台灣圖霸 因應客戶時常有自行維護地理資料的使用情境，推出讓您能夠依照自己的需求，即時地建立及維護您地圖平台上運用所需的地理資料集的 API 集合；MyPlaces API 提供了用戶多種地理運算的方式 (例如: 範圍搜尋、交集選取) 來查找您所建立的資料，方便您透過程式化的方式來存取及維護；您也可以儲存您自訂的 JSON 格式資料，讓您的應用更加有彈性、更具競爭力。

Notation

  1. 左右鍵符號 (大於、小於符號, 也就是 < >) 所描述的是一個變數 (variable) 的 formal parameter 形式。本文件底下若提及參數部分，使用到此表示法時，請讀者將之代換成實際的內容 (也就是代換為 actual parameter，並且，不留下 < > 符號)。例如, https://api.map8.zone/find?keyword=<關鍵詞> 若實際關鍵詞為 taiwan，則實際呼叫時，應代換為 https://api.map8.zone/find?keyword=taiwan。
  2. 位於 API 欄位內格式的 <參數>，為標準的 URL 之 query string 格式編碼 (i.e., name=value 以 URL % 編碼, 並以 & 連接)
  3. 除非另有指定，否則，地理經緯度座標 (lat 或 latitude 均指經度，lng 或 longitude 均指緯度) 以 WGS84 / EPSG:4326 為地理座標系統

基礎資料結構

客供地理資料集我們已為用戶制定了基礎常用的欄位，詳如下表:

Field Type Description
UUID 32 個字元 僅允許 [a-zA-Z0-9] 與底線 (underscore). 除外之字元, 包括 unicode, 或是符號字元如 dash, pound sign, slash 等等均不允許，請勿使用. (例如, ATM00001)
name TEXT
(最長 32 字元)		 此筆地理資料之名稱 (例如, 統一安佃)
city TEXT
(最長 16 字元)		 此筆地理資料所屬之城市 (例如, 台南市)
town TEXT
(最長 16 字元)		 此筆地理資料所屬之行政區 (例如, 安南區)
addr TEXT
(最長 64 字元)		 此筆地理資料之地址 (例如, 台南市安南區海佃路四段548號)
tel TEXT
(最長 64 字元)		 此筆地理資料之電話 (例如, 06-87921567)
lat FLOAT 此筆地理資料之緯度 (WGS84 / EPSG:4326) (例如, 23.0646486829)
lng FLOAT 此筆地理資料之經度 (WGS84 / EPSG:4326) (例如, 120.172123715)
polygonLatLngArray TEXT
(最長 4096 字元)		 此筆地理資料之多邊形幾何座標描述 (僅支援 Well-known text 格式)，若您需要使用交集選取的 API，則需要維護此欄位。
cat TEXT
(最長 16 字元)		 此筆地理資料之類型標記 (例如, ATM) 可運用於篩選
desc TEXT
(最長為 1024 字元)		 此筆地理資料之附加資料。您可以運用 JSON 格式來定義您自己所需要的欄位及內容，達成擴充資訊的目的以符合您的應用所需。

注意事項

API Index

客供地理資料 (MyPlaces) API

[Create / Update] 建立、更新資料

POST data 範例

[
    {
        "UUID": "CCTV00001",
        "name": "101.台江大道、海佃路四段",
        "city": "台南市",
        "town": "安南區",
        "lat": 23.0611431585022,
        "lng": 120.177289169092,
        "cat": "CCTV",
        "desc": "{\"DeviceID\":\"294\",\"DeviceIP\":\"10.1.65.101\",\"DeviceName\":\"101.台江大道、海佃路四段\",\"ChannelNum\":\"0\",\"CameraID\":\"1660\",\"CameraName\":\"1.台江大道西向腳踏車道後車牌\"}"
    },
    {
        "UUID": "ATM00001",
        "name": "統一安佃",
        "city": "台南市",
        "town": "安南區",
        "cat": "ATM",
        "addr": "台南市安南區海佃路四段548號",
        "lat": 23.0646486829,
        "lng": 120.172123715,
        "desc": "{\"ResponsiblePrecinct\":\"第三分局\",\"ResponsiblePoliceStation\":\"原佃派出所\",\"FinancialInstitutionCode\":\"822\",\"FinancialInstitution\":\"中國信託商業銀行\",\"LocationName\":\"統一安佃\",\"LocationProperties\":\"超商\"}"
    },
    {
        "UUID":"PLG00001",
        "city":"台北市",
        "town":"內湖區",
        "name":"九華公園",
        "lat":25.08837,
        "lng":121.55976,
        "cat":"公園",
        "desc":"{\"customId\":\"0001\"}",
        "polygonLatLngArray":"POLYGON((121.56102745589806 25.0888265420256, 121.56117194062625 25.088766723582623, 121.56190262053389 25.088770462236724, 121.56192738934607 25.088650825267763, 121.56190674866957 25.088527449520413, 121.56180767342772 25.08846763093122, 121.56172511072663 25.088478846919628, 121.561176068762 25.08845641494284, 121.5610769935202 25.088624654665068, 121.56102745589806 25.0888265420256))"
    }
]

建立、更新成功的輸出資料範例

Total number of your input rows = 1848
...
[2020-06-23T14:06:34+00:00] Number of rows processed = 185 (10.01%)
...
[2020-06-23T14:07:46+00:00] Number of rows processed = 370 (20.02%)
...
[2020-06-23T14:16:01+00:00] Number of rows processed = 1848 (100.00%)

{"status":"OK"}

[Delete] 刪除資料

刪除資料成功的輸出範例

{"status":"OK","deleted":{"collection_id":"","UUID":"<UUID1>,<UUID2>"}}

刪除資料失敗的輸出範例 (400)

{"status" => "INVALID_REQUEST","error":"`UUID` not specified."}

刪除資料失敗的輸出範例 (500)

{"status":"Internal Server Error","attempt-to-delete":{"collection_id":"","UUID":"<UUID1>,<UUID2>"}}

[Read] 取得資料

輸出範例 (取得指定 UUID 之資料)

{
    "html_attribution":[
        "台灣圖霸",
        "研鼎智能",
        "PAPAGO!"
    ],
    "results":[
        {
            "formatted_address":"",
            "geometry":{
                "location":{
                    "lat":24.35114181818182,
                    "lng":120.62548854545453
                }
            },
            "id":"24002269",
            "place_id":"VU1FAAQAQxZPNzxuNQR4LTAXKBB9RitRIB9hY2FaMxYOQAwACw==",
            "name":"大甲國小",
            "tel":"",
            "city":"台中市",
            "town":"大甲區",
            "type":"地點",
            "chain":"",
            "branch":"",
            "cat":"學校",
            "kind":"",
            "desc":"",
            "geo":{
                "type":"MultiPolygon",
                "coordinates":[
                    [
                        [
                            [
                                120.624937,
                                24.352228
                            ],
                            ... (more points) ...
                            [
                                120.624937,
                                24.352228
                            ]
                        ]
                    ]
                ]
            }
        }
    ],
    "status":"OK"
}

輸出範例 (取得指定矩形範圍內之資料)

{
    "html_attribution":[
        "台灣圖霸",
        "研鼎智能",
        "PAPAGO!"
    ],
    "results":[
        {
            "formatted_address":"",
            "geometry":{
                "location":{
                    "lat":24.345707714285716,
                    "lng":120.58818776190476
                }
            },
            "id":"24002291",
            "place_id":"VU1FAAQATB5PFA4YJykDDiJLMTNufyR+PR1la0J7KTo2Dl5XCw==",
            "name":"大安國小",
            "tel":"",
            "city":"台中市",
            "town":"大安區",
            "type":"地點",
            "chain":"",
            "branch":"",
            "cat":"學校",
            "kind":"",
            "desc":"",
            "geo":{
                "type":"MultiPolygon",
                "coordinates":[
                    [
                        [
                            [
                                120.588257,
                                24.344463
                            ],
                            ... (more points) ...
                            [
                                120.588257,
                                24.344463
                            ]
                        ]
                    ]
                ]
            }
        },
        ... (more results) ...,
        {
            "formatted_address":"",
            "geometry":{
                "location":{
                    "lat":24.34618783333333,
                    "lng":120.58655516666666
                }
            },
            "id":"24002295",
            "place_id":"VU1FAAQATBpPOgN5TzkEAlUrC0dffl5EJDgZeFp2KhM3NgcACw==",
            "name":"台中市大安區公所",
            "tel":"",
            "city":"台中市",
            "town":"大安區",
            "type":"地點",
            "chain":"",
            "branch":"",
            "cat":"政府機關",
            "kind":"",
            "desc":"",
            "geo":{
                "type":"MultiPolygon",
                "coordinates":[
                    [
                        [
                            [
                                120.586612,
                                24.345911
                            ],
                            ... (more points) ...
                            [
                                120.586612,
                                24.345911
                            ]
                        ]
                    ]
                ]
            }
        }
    ],
    "status":"OK"
}

輸出範例 (取得全部資料)

{
    "html_attribution":[
        "台灣圖霸",
        "研鼎智能",
        "PAPAGO!"
    ],
    "results":[
        {
            "formatted_address":"",
            "geometry":{
                "location":{
                    "lat":25.039962000000003,
                    "lng":121.5106695
                }
            },
            "id":"24001648",
            "place_id":"VU1FAAcEQRdPFjxBGkFkJhISAQYOUxB8RBNTWXBNVR9RFCAACw==",
            "name":"國史館",
            "tel":"",
            "city":"台北市",
            "town":"中正區",
            "type":"地點",
            "chain":"",
            "branch":"",
            "cat":"政府機關",
            "kind":"",
            "desc":"",
            "geo":{

            }
        },
        ... (more results) ...,
        {
            "formatted_address":"",
            "geometry":{
                "location":{
                    "lat":25.038011,
                    "lng":121.514230875
                }
            },
            "id":"24001634",
            "place_id":"VU1FAAcERhtPGTxiRyh1C15OUgNjY192GCJlCUlOFSFQCg1XCw==",
            "name":"北一女中",
            "tel":"",
            "city":"台北市",
            "town":"中正區",
            "type":"地點",
            "chain":"",
            "branch":"",
            "cat":"學校",
            "kind":"",
            "desc":"",
            "geo":{

            }
        }
    ],
    "status":"OK",
    "pagination":{
        "firstPageNumber":1,
        "lastPageNumber":602,
        "pageRows":10,
        "totalRows":6016
    }
}

MyPlaces API 提供了多種取得資料的方式供您選擇使用，如下將為您一一說明:

[Nearby search] 鄰近範圍搜尋

輸出資料範例

{
  "html_attribution": [
    "台灣圖霸",
    "研鼎智能",
    "PAPAGO!"
  ],
  "results": [
    {
      "formatted_address": "新北市新店區中正路61號",
      "geometry": {
        "location": {
          "lat": 24.99117899,
          "lng": 121.312643511
        }
      },
      "id": "730abad6-bd25-4342-bf9e-e1a8eea37c65",
      "place_id": "730abad6-bd25-4342-bf9e-e1a8eea37c65",
      "name": "誠品書店新店北新店",
      "tel": "",
      "city": "新北市",
      "town": "新店區",
      "type": "地點",
      "chain": "",
      "branch": "",
      "cat": "生活消費",
      "distance": 0,
      "desc": "{\"whitelistId\":\"10000\",\"city\":\"新北市\",\"area\":\"新店區\",\"zipCode\":\"231\",\"website\":\"http://meet.eslite.com/tw/tc\",\"fb\":\"https://zh-tw.facebook.com/eslite\",\"contact\":\"林真真\",\"status\":0}"
    }
  ],
  "status": "OK"
}

指定中心座標及範圍，以進行鄰近搜尋。

[Intersect search] 交集選取

輸出資料範例

{
  "html_attribution": [
    "台灣圖霸",
    "研鼎智能",
    "PAPAGO!"
  ],
  "results": [
    {
      "formatted_address": "",
      "geometry": {
        "location": {
          "lat": 24.345707714285716,
          "lng": 120.58818776190476
        }
      },
      "id": "24002291",
      "place_id": "VU1FAAQATB5PFA4YJykDDiJLMTNufyR+PR1la0J7KTo2Dl5XCw==",
      "name": "大安國小",
      "tel": "",
      "city": "台中市",
      "town": "大安區",
      "type": "地點",
      "chain": "",
      "branch": "",
      "cat": "學校",
      "kind": "",
      "desc": "",
      "geo": {}
    }
  ],
  "status": "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 表示是我們的伺服器端的錯誤；再重試一次可能就會成功。如果持續發生此問題，請跟我們聯絡
範例