# 「口罩咧？」API 使用說明

:::danger
【重要通知】
由於[健保特約機構口罩剩餘數量明細清單](http://testnhi.pstcom.com.tw/Datasets/DatasetDetail.aspx?id=656)已停止更新，本服務亦不再維護，敬請見諒。
:::

* 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

curl https://findmasks.herokuapp.com/places

#### JavaScript

fetch('https://findmasks.herokuapp.com/places')
    .then((response) => response.json())
    .then((data) => {
        // Put your code here
    })
    .catch((error) => {
        // Handle the error
    });

#### jQuery

$.ajax({
    url: 'https://findmasks.herokuapp.com/places',
    dataType: 'json',
    success: function(data) {
        // Put your code here
    },
    error: function(xhr) {
        // Handle the error
    }
});

### 成功回應範例

{
    "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

curl https://findmasks.herokuapp.com/places/2331230018

#### JavaScript

fetch('https://findmasks.herokuapp.com/places/2331230018')
    .then((response) => response.json())
    .then((data) => {
        // Put your code here
    })
    .catch((error) => {
        // Handle the error
    });

#### jQuery

$.ajax({
    url: 'https://findmasks.herokuapp.com/places/2331230018',
    dataType: 'json',
    success: function(data) {
        // Put your code here
    },
    error: function(xhr) {
        // Handle the error
    }
});

### 成功回應範例

{
    "type": "Feature",
    "geometry": {
        "type": "Point",
        "coordinates": [121.399996, 25.147051]
    },
    "properties": {
        "id": "2331230018",
        "name": "新北市八里區衛生所",
        "phone": "[phone]",
        "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)。