Name: household-waste-info
Author: nomadamas

Household Waste Info

What this skill does

查詢行政安全部「生活垃圾排放資訊 Open API」，
提供各地區一般生活垃圾、廚餘（飲食物廢棄物）及資源回收品的排放標準、星期與時間資訊。

基本查詢單位為市郡區名稱（SGG_NM）。
回覆結果會整理為易於理解的摘要形式呈現給使用者。
Base URL 以原始 API（https://apis.data.go.kr/1741000/household_waste_info）為準。
僅有 serviceKey（DATA_GO_KR_API_KEY）由 Proxy 伺服器注入與管理。

When to use

「請告訴我江南區的垃圾清運星期」
「我們家附近的廚餘什麼時候可以丟？」
「幫我確認資源回收品的清運時間」
「尋找一般生活垃圾的排放地點與方式」

Prerequisites

網路連線
可使用 curl 與 python3 的環境
可存取原始 API 的環境
可存取用於注入 API 金鑰之 Proxy 的環境

Credential requirements

原則上使用者端不需要必填的驗證金鑰。

可選環境變數：

KSKILL_PROXY_BASE_URL（使用自託管 self-hosted Proxy 時）

驗證金鑰使用原則：

Endpoint 與參數體系遵循原始 API 規範。
serviceKey 數值由 Proxy 伺服器管理並注入。
使用者端本機環境無需設定 DATA_GO_KR_API_KEY。

Official API surface

Base URL: https://apis.data.go.kr/1741000/household_waste_info
Endpoint: GET /info
(key injection only) proxy: 由 k-skill-proxy 在伺服器端注入 serviceKey

Default path

不需要額外的 Client API 層。Base URL 保持以原始 API 為基準。

目前 Proxy 支援的 Query 參數：

cond[SGG_NM::LIKE]：市郡區名稱模糊搜尋（必填）
pageNo / numOfRows（或 page_no / num_of_rows）：必填，數值必須為 1 / 100 — 其他數值或非純數字字串將回傳 400。傳送至 Upstream 時一律固定為第 1 頁、100 筆。
returnType：Proxy 一律強制為 json — 即使 Client 帶入其他數值也會被忽略
serviceKey：由 Proxy 在伺服器端注入 — 嚴禁 Client 端傳送

原始 API 的 cond[DAT_CRTR_YMD::*]、cond[DAT_UPDT_PNT::*] 等附加篩選條件目前不會透過 Proxy 路由轉發（Pass-through）。使用者常見的查詢（例如：「江南區丟垃圾星期」）僅靠市郡區搜尋即已足夠，若有需要，可在 Client 端依據回覆結果中的 DAT_UPDT_PNT 欄位進行排序。

Workflow

1) Ask location first

在未取得使用者地區資訊前，請勿直接查詢。

建議提問：請提供要查詢的地區（市/郡/區）。例如：江南區、水原市靈通區

2) Validate input and resolve query

若市郡區輸入空白，請再次詢問。
若輸入內容不明確，請請使用者提供包含完整上級行政區的格式後重新詢問。

3) Call via proxy (serviceKey injected server-side)

Proxy 會在伺服器端注入 serviceKey 後轉發至原始 API。

curl -fsS --get 'https://k-skill-proxy.nomadamas.org/v1/household-waste/info' \
  --data-urlencode "cond[SGG_NM::LIKE]=강남구" \
  --data-urlencode "pageNo=1" \
  --data-urlencode "numOfRows=100"

returnType 會由 Proxy 強制設為 json，因此 Client 無需另外傳送。

若有設定 KSKILL_PROXY_BASE_URL 則使用該數值；若未設定，則使用預設 Hosted Proxy（k-skill-proxy.nomadamas.org）。

4) Summarize for user

將回覆中所需的項目進行簡要整理：

管理區域/目標區域 (MNG_ZONE_NM, MNG_ZONE_TRGT_RGN_NM)
排放地點/排放方式 (EMSN_PLC, LF_WST_EMSN_MTHD, FOD_WST_EMSN_MTHD, RCYCL_EMSN_MTHD)
排放星期/時間 (LF_WST_EMSN_DOW, FOD_WST_EMSN_DOW, RCYCL_EMSN_DOW 及各自的開始/結束時間)
不清運日 (UNCLLT_DAY)
諮詢單位/聯絡電話 (MNG_DEPT_NM, MNG_DEPT_TELNO)

Done when

已確認使用者的所在地區（市郡區）。
已成功呼叫 Proxy 的 /v1/household-waste/info。
已將清運星期/時間/地點整理為 3~6 個核心重點進行說明。

Failure modes

Proxy 伺服器未設定 DATA_GO_KR_API_KEY 或金鑰已過期（serviceKey 注入失敗）。
搜尋的地區名稱與 API 資料不符，導致查詢結果空白。
公共資料 API 暫時故障或受到流量限制。
遺失必填參數（未傳送 cond[SGG_NM::LIKE]，或未傳送 pageNo / numOfRows）。
pageNo / numOfRows 數值不為 1 / 100，或傳送了非純數字組成的字串（Proxy 回傳 400，未呼叫 Upstream）。

Notes

不要在 Client 端儲存 DATA_GO_KR_API_KEY，僅在 Proxy 伺服器端集中管理。
請勿直接輸出 API 的原始 Payload（Raw data），應整理為易於閱讀的摘要。
若回覆資料有多筆，請優先依最新 DAT_UPDT_PNT 進行排序後呈現。
官方資料來源：韓國公共資料入口網站（https://www.data.go.kr）

household-waste-info

相關技能