Household Waste Info

このスキルの動作

行政安全部生活쓰레기配出情報Open APIを照会して、地域別の生活쓰레기/食品쓰레기/リサイクル品の配出基準と曜日/時間情報を案内します。

• 基本照会単位は市郡区名(SGG_NM)です。
• 応答はユーザーにとってわかりやすい要約形式で整理されます。
• Base URLは元のAPI(https://apis.data.go.kr/1741000/household_waste_info)を基準とします。
• serviceKey(DATA_GO_KR_API_KEY)のみproxyサーバーで注入/管理します。

使用時機

• 「江南区のゴミ配出曜日を教えて」
• 「我が町の食品ゴミはいつ出す?」
• 「リサイクル品の配出時間を確認して」
• 「生活ゴミの配出場所/方法を探して」

前提条件

• インターネット接続
• curl、python3が使用可能な環境
• 元のAPI へのアクセス可能環境
• API キー注入用proxyへのアクセス可能環境

認証情報の要件

基本的にユーザー側の必須認証キーはありません。

オプション環境変数:

• KSKILL_PROXY_BASE_URL (self-hosted proxyを使用する場合)

認証キー使用原則:

1. endpoint/パラメータ体系は元のAPIに従います。
2. serviceKeyの値はproxyサーバーが管理して注入します。
3. ユーザー側のローカル環境にDATA_GO_KR_API_KEYを置く必要はありません。

公式API インターフェース

• Base URL: https://apis.data.go.kr/1741000/household_waste_info
• Endpoint: GET /info
• (キー注入のみ) proxy: k-skill-proxyがサーバー側からserviceKeyを注入

デフォルトパス

追加クライアントAPIレイヤーは不要です。Base URLは元のAPIを基準に維持されます。

現在proxyがサポートしているクエリパラメータ:

• cond[SGG_NM::LIKE]: 市郡区名の包含検索 (必須)
• pageNo / numOfRows(またはpage_no / num_of_rows): 必須、値は必ず1 / 100 — その他の値・非整数(数字以外の)文字列は**400**。upstreamには常に1ページ・100件のみ送信されます。
• returnType: proxyが常にjsonに強制 — クライアントが値を送っても無視されます
• serviceKey: proxyがサーバー側で注入 — クライアント側から送信禁止

元のAPIのcond[DAT_CRTR_YMD::*]、cond[DAT_UPDT_PNT::*]といった追加フィルタは現在proxyルートではパススルーされません。ユーザーが送る一般的な質問(「江南区のゴミ配出曜日」)は市郡区基準の検索のみで十分なため、必要であれば応答からDAT_UPDT_PNT基準でクライアント側でソートします。

ワークフロー

1) まず位置情報を質問する

ユーザーの地域情報がない状態で直ちに照会しません。

• 推奨質問: 確認したい地域(市/郡/区)を教えてください。例: 江南区、水原市栄通区

2) 入力を検証してクエリを解決する

• 市郡区の入力が空の場合は再度質問します。
• あいまいな入力の場合は上位行政区域を含む形式で再質問します。

3) proxyを経由して呼び出す (serviceKeyはサーバー側で注入)

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に強制するため、クライアント側から別途送信する必要はありません。

KSKILL_PROXY_BASE_URLがあればその値を使用し、なければ既定のhosted proxy(k-skill-proxy.nomadamas.org)を使用します。

4) ユーザーむけに要約する

応答から必要な項目のみを簡潔にまとめます。

• 管理区域/対象地域 (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)

完了条件

• ユーザーの地域(市郡区)を確認しました。
• proxy /v1/household-waste/info の呼び出しに成功しました。
• 配出曜日/時間/場所を3〜6個のキーポイントで要約して案内しました。

失敗のパターン

• proxyサーバーにDATA_GO_KR_API_KEYがない、または期限切れの場合 (serviceKey注入失敗)
• 検索地域名がAPIデータと不一致して結果が空の場合
• 公共データAPI一時障害/トラフィック制限
• 必須パラメータ欠落(cond[SGG_NM::LIKE]、またはpageNo / numOfRows未送信)
• pageNo / numOfRowsの値が1 / 100でない、または数字のみで表現されていない文字列の場合(proxy 400、upstream未呼び出し)

注意事項

• ユーザー側にDATA_GO_KR_API_KEYを保存せず、proxyサーバーでのみ管理します。
• API raw payloadをそのまま公開せず、ユーザーフレンドリーに要約します。
• 応答が複数件の場合は最新のDAT_UPDT_PNT基準で優先的にソートして表示します。
• 公式データ出典: 公共データポータル (https://www.data.go.kr)