{
  "openapi": "3.1.0",
  "info": {
    "title": "Kaelith 智慧醫療導航查詢 API",
    "version": "1.3.0",
    "description": "查詢由中央健康保險署公開資料同步建立的本機醫療資源索引。服務時段為公開登錄紀錄，不代表即時掛號、現場量能或醫療建議。",
    "contact": {
      "name": "Kaelith 數位開發",
      "url": "https://kaelith.tw",
      "email": "service@kaelith.tw"
    },
    "license": {
      "name": "網站程式與介面保留權利；政府資料依其原授權條款使用"
    }
  },
  "servers": [
    {
      "url": "https://med.kaelith.tw",
      "description": "正式環境"
    }
  ],
  "externalDocs": {
    "description": "資料來源與判讀方式",
    "url": "https://med.kaelith.tw/data-sources"
  },
  "tags": [
    {
      "name": "Medical resources",
      "description": "醫療院所與藥局查詢"
    },
    {
      "name": "System",
      "description": "服務與資料索引狀態"
    }
  ],
  "paths": {
    "/api/v1/search": {
      "get": {
        "tags": [
          "Medical resources"
        ],
        "operationId": "searchMedicalInstitutions",
        "summary": "查詢醫療資源",
        "description": "依縣市、關鍵字、院所類型、科別與公開服務時段篩選本機索引。特定假期時段適用時會優先於每週固定時段。",
        "parameters": [
          {
            "name": "city",
            "in": "query",
            "required": true,
            "description": "臺灣縣市全名，例如「臺南市」。",
            "schema": {
              "type": "string",
              "enum": [
                "臺北市",
                "新北市",
                "桃園市",
                "臺中市",
                "臺南市",
                "高雄市",
                "基隆市",
                "新竹市",
                "嘉義市",
                "新竹縣",
                "苗栗縣",
                "彰化縣",
                "南投縣",
                "雲林縣",
                "嘉義縣",
                "屏東縣",
                "宜蘭縣",
                "花蓮縣",
                "臺東縣",
                "澎湖縣",
                "金門縣",
                "連江縣"
              ]
            }
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "院所名稱、地址或科別關鍵字。",
            "schema": {
              "type": "string",
              "maxLength": 60
            }
          },
          {
            "name": "type",
            "in": "query",
            "required": false,
            "description": "院所類型；省略時查詢全部。",
            "schema": {
              "type": "string",
              "enum": [
                "hospital",
                "clinic",
                "pharmacy"
              ]
            }
          },
          {
            "name": "department",
            "in": "query",
            "required": false,
            "description": "診療科別名稱。",
            "schema": {
              "type": "string",
              "maxLength": 20
            }
          },
          {
            "name": "open_now",
            "in": "query",
            "required": false,
            "description": "設為 1 時，只保留目前時段有開診登錄的結果。此欄位不是即時營業保證。",
            "schema": {
              "type": "integer",
              "enum": [
                0,
                1
              ],
              "default": 0
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "回傳筆數上限。",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 30
            }
          }
        ],
        "responses": {
          "200": {
            "description": "查詢成功；資料尚未同步時仍回傳 200，並將 meta.syncRequired 設為 true。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchResponse"
                }
              }
            }
          },
          "422": {
            "description": "查詢參數無效。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "請求過於頻繁。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "資料索引格式錯誤。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/status": {
      "get": {
        "tags": [
          "System"
        ],
        "operationId": "getServiceStatus",
        "summary": "取得服務與資料索引狀態",
        "responses": {
          "200": {
            "description": "服務版本、資料筆數、同步狀態與伺服器時間。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StatusResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ScheduleStatus": {
        "type": "object",
        "required": [
          "code",
          "label",
          "basis"
        ],
        "properties": {
          "code": {
            "type": "string",
            "enum": [
              "open",
              "closed",
              "unknown"
            ]
          },
          "label": {
            "type": "string"
          },
          "basis": {
            "type": "string",
            "enum": [
              "holiday",
              "weekly",
              "time"
            ],
            "description": "holiday=特定假期資料；weekly=固定服務時段；time=目前時間不在公開時段區間。"
          }
        }
      },
      "Institution": {
        "type": "object",
        "required": [
          "id",
          "name",
          "type",
          "typeLabel",
          "phone",
          "address",
          "city",
          "departments",
          "updatedAt",
          "schedule"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "醫事機構代碼。"
          },
          "name": {
            "type": "string"
          },
          "type": {
            "type": "string",
            "enum": [
              "hospital",
              "clinic",
              "pharmacy"
            ]
          },
          "typeLabel": {
            "type": "string"
          },
          "phone": {
            "type": "string"
          },
          "address": {
            "type": "string"
          },
          "city": {
            "type": "string"
          },
          "departments": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "updatedAt": {
            "type": "string",
            "format": "date"
          },
          "schedule": {
            "$ref": "#/components/schemas/ScheduleStatus"
          }
        }
      },
      "SearchMetadata": {
        "type": "object",
        "required": [
          "count",
          "syncRequired",
          "datasetUpdatedAt"
        ],
        "properties": {
          "count": {
            "type": "integer",
            "minimum": 0
          },
          "syncRequired": {
            "type": "boolean"
          },
          "datasetUpdatedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "source": {
            "type": "string"
          }
        }
      },
      "SearchResponse": {
        "type": "object",
        "required": [
          "data",
          "meta"
        ],
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Institution"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/SearchMetadata"
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              }
            }
          }
        }
      },
      "DatasetStatus": {
        "type": "object",
        "properties": {
          "generatedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "records": {
            "type": "integer",
            "minimum": 0
          },
          "syncRequired": {
            "type": "boolean"
          },
          "sources": {
            "type": "array",
            "items": {
              "type": "object"
            }
          }
        }
      },
      "StatusResponse": {
        "type": "object",
        "required": [
          "status",
          "version",
          "dataset",
          "time"
        ],
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "ok"
            ]
          },
          "version": {
            "type": "string"
          },
          "dataset": {
            "$ref": "#/components/schemas/DatasetStatus"
          },
          "time": {
            "type": "string",
            "format": "date-time"
          }
        }
      }
    }
  }
}