# 「口罩咧?」API 使用說明 * 08:00–20:59 口罩剩餘數量每 3 分鐘更新一次 * 網頁前端實際使用範例可參考「口罩咧?」[網站](https://www.findmasks.tw)或[原始碼](https://github.com/mingjunlu/findmasks-frontend) ## 讀取所有地點 回傳所有健保特約藥局與衛生所的**部分資訊**,格式為 [GeoJSON FeatureCollection Object](https://tools.ietf.org/html/rfc7946#section-3.3)。 ``` GET https://findmasks.herokuapp.com/places ``` > 若需要一次拿回所有地點的詳細資料,可以參考[其他開發資源](https://g0v.hackmd.io/gGrOI4_aTsmpoMfLP1OU4A#開發資源:),例如[藥局+衛生所即時庫存 geojson by kiang](https://raw.githubusercontent.com/kiang/pharmacies/master/json/points.json)。 ### 範例碼 #### Shell ```shell curl https://findmasks.herokuapp.com/places ``` #### JavaScript ```javascript= fetch('https://findmasks.herokuapp.com/places') .then((response) => response.json()) .then((data) => { // Put your code here }) .catch((error) => { // Handle the error }); ``` #### jQuery ```javascript= $.ajax({ url: 'https://findmasks.herokuapp.com/places', dataType: 'json', success: function(data) { // Put your code here }, error: function(xhr) { // Handle the error } }); ``` ### 成功回應範例 ```json { "type": "FeatureCollection", "features": [ { "type": "Feature", "geometry": { "type": "Point", "coordinates": [121.399996, 25.147051] }, "properties": { "id": "2331230018", "name": "新北市八里區衛生所", "masksLeft": 27, "childMasksLeft": 43, "updatedAt": "2020-04-25T17:18:34.385Z" } }, { "type": "Feature", "geometry": { "type": "Point", "coordinates": [121.737185, 25.024684] }, "properties": { "id": "2331240014", "name": "新北市平溪區衛生所", "masksLeft": 84, "childMasksLeft": 70, "updatedAt": "2020-04-25T17:18:34.385Z" } } ] } ``` ## 讀取特定地點 回傳特定健保特約藥局或衛生所的**完整資訊**,格式為 [GeoJSON Feature Object](https://tools.ietf.org/html/rfc7946#section-3.2)。 ``` GET https://findmasks.herokuapp.com/places/<id> ``` ### URL 參數 | 參數 | 描述 | | --- | ----------------------- | | id | 欲取得相關資訊之醫事機構代碼 | ### 範例碼 #### Shell ```shell curl https://findmasks.herokuapp.com/places/2331230018 ``` #### JavaScript ```javascript= fetch('https://findmasks.herokuapp.com/places/2331230018') .then((response) => response.json()) .then((data) => { // Put your code here }) .catch((error) => { // Handle the error }); ``` #### jQuery ```javascript= $.ajax({ url: 'https://findmasks.herokuapp.com/places/2331230018', dataType: 'json', success: function(data) { // Put your code here }, error: function(xhr) { // Handle the error } }); ``` ### 成功回應範例 ```json { "type": "Feature", "geometry": { "type": "Point", "coordinates": [121.399996, 25.147051] }, "properties": { "id": "2331230018", "name": "新北市八里區衛生所", "phone": "(02)26102137", "address": "新北市八里區舊城路16號", "masksLeft": 1, "childMasksLeft": 210, "opensOn": [ "休息", "上午、下午", "上午、下午", "上午", "上午、下午", "上午", "休息" ], "note": "109年民族掃墓節連續假期(4/2~4/5)休診", "updatedAt": "2020-03-29T06:32:45.000Z" } } ``` ## 常見問答 ### 為什麼已經停售口罩的藥局還會出現在回傳資料裡? > 已經有藥局向健保署反映這個問題了,目前等待健保署系統修正中。 > > 5/1 補充:健保署系統已於 4/18 增加新功能,讓藥局能夠標記其為完售狀態與否(號碼牌已發送完畢/當日停止販售),若藥局端設定正確的話,該藥局將不會出現在健保署系統產出的資料中。至於「口罩咧?」API 則會暫時保留完售的藥局資料,若連續多天都沒有該藥局的新資料,才會將其移除。 ### 為什麼幾分鐘前還有藥局或衛生所的資料,現在卻查不到? > 為了避免對未販售口罩的健保特約藥局造成困擾,健保署系統會把「口罩已售罄」、「號碼牌發送完畢」,以及「目前未營業」的藥局、衛生所排除在輸出資料之外,因此可能會出現突然查不到資料的情形。 > > 4/20 更新:針對那些突然消失的藥局、衛生所,「口罩咧?」API 會繼續回傳資料,至於該地點的相關資料,則會停留在最後一次從健保署取得資料的情形。 > > 5/1 補充:若連續多天都沒再收到新資料,「口罩咧?」API 會將其移除。 ### 為什麼有些藥局的座標不準? > 藥局與衛生所的座標資料是多位熱心網友整理而成,並非官方資料,因此可能與實際位置有所落差。若發現錯誤座標,歡迎點選右手邊的對話框圖示 <i class="fa fa-comment-o"></i> 留言回報。 ## 補充說明 每個地點即是一個 [GeoJSON Object](https://tools.ietf.org/html/rfc7946#section-3),其 `properties` 格式如下: | 屬性  | 類型    | 描述  | | -------------- | ---------------- | ----------------------- | | id | String | 醫事機構代碼 | | name | String | 醫事機構名稱 | | phone | String | 醫事機構電話 | | address | String | 醫事機構地址 | | masksLeft | Number | 成人口罩剩餘數   | | childMasksLeft | Number | 兒童口罩剩餘數   | | opensOn | Array of Strings | 營業時段 [^opensOn]   | | note | String | 備註 [^note]  | | updatedAt | String | 資料更新時間 [^updatedAt] | [^opensOn]: 長度為 7 或 0 的陣列,其索引值對應到一週的天數,例如 `opensOn[0]` 代表星期日的營業時段,`opensOn[1]` 代表星期一,`opensOn[2]` 代表星期二⋯⋯依此類推。若為空陣列,則代表無法取得該機構的營業時段資訊。 [^note]: 資料來源為[全民健康保險特約院所固定服務時段](https://data.nhi.gov.tw/Datasets/DatasetDetail.aspx?id=441)。若為空字串,則代表無法取得該機構提供的備註。 [^updatedAt]: 格式為 [ISO 8601 Extended Format](http://en.wikipedia.org/wiki/ISO_8601)。