{"openapi":"3.0.3","info":{"title":"臺北市政府官網公開資料 API","description":"市府官網可信資料介面：結構化政府服務、頁面內容、增量變更與批次下載。所有資料由官網 CMS 治理流程產生，與網頁內容同源。","version":"1.0.0","contact":{"name":"臺北市政府"}},"servers":[{"url":"/","description":"This host"}],"tags":[{"name":"services","description":"結構化政府服務（可信資料第三層）"},{"name":"content","description":"頁面與導覽內容"},{"name":"sync","description":"增量變更與批次下載"},{"name":"search","description":"統一搜尋（第五層）"},{"name":"ai","description":"AI 導航（僅查詢與導航，不做行政核定）"}],"paths":{"/api/v1/open/services":{"get":{"tags":["services"],"summary":"查詢政府服務","parameters":[{"name":"X-Tenant-ID","in":"header","required":false,"description":"租戶代碼（如 portal、doit）。也可用 ?tenant= 或子網域指定。","schema":{"type":"string","default":"portal"}},{"name":"q","in":"query","schema":{"type":"string"},"description":"關鍵字（比對名稱、說明、民眾用語）"},{"name":"serviceType","in":"query","schema":{"type":"string","enum":["APPLY","REPORT","QUERY","SUBSIDY","RESERVATION","OTHER"]}},{"name":"district","in":"query","schema":{"type":"string"},"description":"行政區（如 信義區）"},{"name":"page","in":"query","schema":{"type":"integer","default":1}},{"name":"limit","in":"query","schema":{"type":"integer","default":20,"maximum":100}}],"responses":{"200":{"description":"服務列表（僅 ACTIVE / EXPIRING）","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"serviceId":{"type":"string","example":"TPE-SVC-000001"},"title":{"type":"string","example":"路燈故障通報"},"shortDescription":{"type":"string","nullable":true},"citizenTerms":{"type":"array","items":{"type":"string"},"description":"民眾常用說法"},"situations":{"type":"array","items":{"type":"string"}},"serviceType":{"type":"string","enum":["APPLY","REPORT","QUERY","SUBSIDY","RESERVATION","OTHER"]},"region":{"type":"object","properties":{"city":{"type":"string"},"districts":{"type":"array","items":{"type":"string"}}}},"targetAudience":{"type":"array","items":{"type":"string"}},"eligibility":{"type":"array","items":{"type":"string"}},"exclusions":{"type":"array","items":{"type":"string"}},"requiredInformation":{"type":"array","items":{"type":"string"}},"requiredDocuments":{"type":"array","items":{"type":"string"}},"applicationMethods":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["ONLINE","PHONE","IN_PERSON","MAIL","EMAIL"]},"url":{"type":"string"},"value":{"type":"string"}}}},"legalBasis":{"type":"array","items":{"type":"string"}},"faq":{"type":"array","items":{"type":"object","properties":{"q":{"type":"string"},"a":{"type":"string"}}}},"responsibleAgency":{"type":"string"},"officialUrl":{"type":"string","nullable":true},"canonicalUrl":{"type":"string","nullable":true},"status":{"type":"string","enum":["ACTIVE","EXPIRING"]},"effectiveFrom":{"type":"string","format":"date-time","nullable":true},"effectiveTo":{"type":"string","format":"date-time","nullable":true},"lastVerifiedAt":{"type":"string","format":"date-time","nullable":true,"description":"最後人工確認時間"},"nextReviewAt":{"type":"string","format":"date-time","nullable":true,"description":"下次確認期限"},"dataOwner":{"type":"string","description":"業務維護單位"},"version":{"type":"integer"},"lastUpdatedAt":{"type":"string","format":"date-time"}}}},"meta":{"type":"object","properties":{"page":{"type":"integer"},"pageSize":{"type":"integer"},"total":{"type":"integer"},"schemaVersion":{"type":"string"}}}}}}}}}}},"/api/v1/open/services/{serviceId}":{"get":{"tags":["services"],"summary":"取得單一服務完整資料","parameters":[{"name":"X-Tenant-ID","in":"header","required":false,"description":"租戶代碼（如 portal、doit）。也可用 ?tenant= 或子網域指定。","schema":{"type":"string","default":"portal"}},{"name":"serviceId","in":"path","required":true,"schema":{"type":"string"},"example":"TPE-SVC-000001"}],"responses":{"200":{"description":"服務完整結構化資料","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"serviceId":{"type":"string","example":"TPE-SVC-000001"},"title":{"type":"string","example":"路燈故障通報"},"shortDescription":{"type":"string","nullable":true},"citizenTerms":{"type":"array","items":{"type":"string"},"description":"民眾常用說法"},"situations":{"type":"array","items":{"type":"string"}},"serviceType":{"type":"string","enum":["APPLY","REPORT","QUERY","SUBSIDY","RESERVATION","OTHER"]},"region":{"type":"object","properties":{"city":{"type":"string"},"districts":{"type":"array","items":{"type":"string"}}}},"targetAudience":{"type":"array","items":{"type":"string"}},"eligibility":{"type":"array","items":{"type":"string"}},"exclusions":{"type":"array","items":{"type":"string"}},"requiredInformation":{"type":"array","items":{"type":"string"}},"requiredDocuments":{"type":"array","items":{"type":"string"}},"applicationMethods":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["ONLINE","PHONE","IN_PERSON","MAIL","EMAIL"]},"url":{"type":"string"},"value":{"type":"string"}}}},"legalBasis":{"type":"array","items":{"type":"string"}},"faq":{"type":"array","items":{"type":"object","properties":{"q":{"type":"string"},"a":{"type":"string"}}}},"responsibleAgency":{"type":"string"},"officialUrl":{"type":"string","nullable":true},"canonicalUrl":{"type":"string","nullable":true},"status":{"type":"string","enum":["ACTIVE","EXPIRING"]},"effectiveFrom":{"type":"string","format":"date-time","nullable":true},"effectiveTo":{"type":"string","format":"date-time","nullable":true},"lastVerifiedAt":{"type":"string","format":"date-time","nullable":true,"description":"最後人工確認時間"},"nextReviewAt":{"type":"string","format":"date-time","nullable":true,"description":"下次確認期限"},"dataOwner":{"type":"string","description":"業務維護單位"},"version":{"type":"integer"},"lastUpdatedAt":{"type":"string","format":"date-time"}}}}}}}},"404":{"description":"服務不存在或未生效"}}}},"/api/v1/open/changes":{"get":{"tags":["sync"],"summary":"增量變更查詢","description":"回傳 since 之後有異動的服務與頁面，外部系統可據此同步而不必全量下載。","parameters":[{"name":"X-Tenant-ID","in":"header","required":false,"description":"租戶代碼（如 portal、doit）。也可用 ?tenant= 或子網域指定。","schema":{"type":"string","default":"portal"}},{"name":"since","in":"query","schema":{"type":"string","format":"date-time"},"description":"ISO 8601；預設近 7 天"},{"name":"limit","in":"query","schema":{"type":"integer","default":200,"maximum":500}}],"responses":{"200":{"description":"變更清單","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"resourceType":{"type":"string","enum":["service","page"]},"id":{"type":"string"},"title":{"type":"string","nullable":true},"status":{"type":"string"},"changeType":{"type":"string","enum":["CREATED","UPDATED","REMOVED"]},"updatedAt":{"type":"string","format":"date-time"}}}}}}}}},"400":{"description":"since 格式錯誤"}}}},"/datasets/government-services.json":{"get":{"tags":["sync"],"summary":"批次下載全部有效服務（JSON）","parameters":[{"name":"X-Tenant-ID","in":"header","required":false,"description":"租戶代碼（如 portal、doit）。也可用 ?tenant= 或子網域指定。","schema":{"type":"string","default":"portal"}}],"responses":{"200":{"description":"完整資料集"}}}},"/datasets/government-services.csv":{"get":{"tags":["sync"],"summary":"批次下載全部有效服務（CSV）","parameters":[{"name":"X-Tenant-ID","in":"header","required":false,"description":"租戶代碼（如 portal、doit）。也可用 ?tenant= 或子網域指定。","schema":{"type":"string","default":"portal"}}],"responses":{"200":{"description":"CSV（UTF-8 with BOM）"}}}},"/api/v1/search":{"get":{"tags":["search"],"summary":"統一搜尋","description":"關鍵字 + 民眾用語（同義詞）+ 模糊比對的混合搜尋。權重：正式服務 > 服務型頁面 > 新聞；封存與歷史資料不進搜尋。","parameters":[{"name":"X-Tenant-ID","in":"header","required":false,"description":"租戶代碼（如 portal、doit）。也可用 ?tenant= 或子網域指定。","schema":{"type":"string","default":"portal"}},{"name":"q","in":"query","required":true,"schema":{"type":"string"},"example":"路燈壞掉"},{"name":"scope","in":"query","schema":{"type":"string","enum":["all","services","pages"],"default":"all"}},{"name":"limit","in":"query","schema":{"type":"integer","default":10,"maximum":50}}],"responses":{"200":{"description":"搜尋結果（依權重排序）","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["service","page"]},"id":{"type":"string"},"title":{"type":"string"},"snippet":{"type":"string","nullable":true},"url":{"type":"string"},"officialUrl":{"type":"string","nullable":true},"score":{"type":"integer"},"matchedOn":{"type":"string"}}}}}}}}}}}},"/api/v1/ai/service-search":{"post":{"tags":["ai"],"summary":"AI 服務導航","description":"以自然語言描述需求，AI 解析意圖後查詢官方服務資料庫，回傳候選服務與需補充的資訊。候選服務一律來自官方資料，AI 不自創服務、資格或網址。模型失效時自動降級為關鍵字搜尋。","parameters":[{"name":"X-Tenant-ID","in":"header","required":false,"description":"租戶代碼（如 portal、doit）。也可用 ?tenant= 或子網域指定。","schema":{"type":"string","default":"portal"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["query"],"properties":{"query":{"type":"string","maxLength":500,"example":"我家巷口的路燈晚上都不會亮"}}}}}},"responses":{"200":{"description":"意圖解析結果與官方候選服務","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"interpretedNeed":{"type":"string"},"missingFields":{"type":"array","items":{"type":"string"}},"district":{"type":"string","nullable":true},"candidateServiceIds":{"type":"array","items":{"type":"string"}},"candidates":{"type":"array","items":{"type":"object"}},"notice":{"type":"string"}}}}}}}}}}},"/api/v1/open/pages":{"get":{"tags":["content"],"summary":"已發布頁面列表","parameters":[{"name":"X-Tenant-ID","in":"header","required":false,"description":"租戶代碼（如 portal、doit）。也可用 ?tenant= 或子網域指定。","schema":{"type":"string","default":"portal"}},{"name":"category","in":"query","schema":{"type":"string"}},{"name":"page","in":"query","schema":{"type":"integer","default":1}},{"name":"limit","in":"query","schema":{"type":"integer","default":20,"maximum":100}}],"responses":{"200":{"description":"頁面列表"}}}},"/api/v1/open/pages/{slug}":{"get":{"tags":["content"],"summary":"單一頁面完整內容","parameters":[{"name":"X-Tenant-ID","in":"header","required":false,"description":"租戶代碼（如 portal、doit）。也可用 ?tenant= 或子網域指定。","schema":{"type":"string","default":"portal"}},{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"頁面內容"},"404":{"description":"不存在或未發布"}}}},"/api/v1/open/categories":{"get":{"tags":["content"],"summary":"分類樹","parameters":[{"name":"X-Tenant-ID","in":"header","required":false,"description":"租戶代碼（如 portal、doit）。也可用 ?tenant= 或子網域指定。","schema":{"type":"string","default":"portal"}}],"responses":{"200":{"description":"分類樹狀結構"}}}},"/api/v1/open/navigation":{"get":{"tags":["content"],"summary":"導覽列","parameters":[{"name":"X-Tenant-ID","in":"header","required":false,"description":"租戶代碼（如 portal、doit）。也可用 ?tenant= 或子網域指定。","schema":{"type":"string","default":"portal"}}],"responses":{"200":{"description":"導覽樹狀結構"}}}}}}