Back to Details

household-waste-info

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Household Waste Info

生活垃圾信息

What this skill does

这个Skill的功能

행정안전부 생활쓰레기배출정보 Open API를 조회해 지역별 생활쓰레기/음식물쓰레기/재활용품 배출 기준과 요일/시간 정보를 안내한다.
  • 기본 조회 단위는 시군구명(
    SGG_NM
    )이다.
  • 응답은 사용자에게 이해하기 쉬운 요약 형태로 정리한다.
  • Base URL은 원본 API(
    https://apis.data.go.kr/1741000/household_waste_info
    )를 기준으로 한다.
  • serviceKey
    (
    DATA_GO_KR_API_KEY
    )만 proxy 서버에서 주입/관리한다.
查询行政安全部生活垃圾排放信息Open API，为用户提供各地区生活垃圾/厨余垃圾/可回收物的排放标准、日期及时间信息。
  • 默认查询单位为市郡区名（
    SGG_NM
    ）
  • 响应内容会整理为用户容易理解的摘要形式
  • 基础URL以原始API（
    https://apis.data.go.kr/1741000/household_waste_info
    ）为准
  • 仅
    serviceKey
    （
    DATA_GO_KR_API_KEY
    ）由代理服务器注入/管理

When to use

适用场景

  • "강남구 쓰레기 배출 요일 알려줘"
  • "우리 동네 음식물쓰레기 언제 버려?"
  • "재활용품 배출 시간 확인해줘"
  • "생활쓰레기 배출 장소/방법 찾아줘"
  • "告诉我江南区的垃圾排放日期"
  • "我们小区什么时候扔厨余垃圾？"
  • "帮我确认可回收物的投放时间"
  • "帮我找生活垃圾的投放地点/方法"

Prerequisites

前置条件

  • 인터넷 연결
  • curl
    , 
    python3
    사용 가능 환경
  • 원본 API 접근 가능 환경
  • API 키 주입용 proxy 접근 가능 환경
  • 互联网连接
  • 可使用
    curl
    、
    python3
    的环境
  • 可访问原始API的环境
  • 可访问API密钥注入用代理的环境

Credential requirements

凭证要求

기본적으로 사용자 측 필수 인증키는 없다.
선택 환경변수:
  • KSKILL_PROXY_BASE_URL
    (self-hosted proxy를 쓸 때)
인증키 사용 원칙:
  1. endpoint/파라미터 체계는 원본 API를 따른다.
  2. serviceKey
    값은 proxy 서버가 관리하고 주입한다.
  3. 사용자 측 로컬 환경에 
    DATA_GO_KR_API_KEY
    를 둘 필요가 없다.
默认用户侧无需提供认证密钥。
可选环境变量:
  • KSKILL_PROXY_BASE_URL
    （使用自行部署的代理时配置）
认证密钥使用原则:
  1. 端点/参数体系遵循原始API规范
  2. serviceKey
    值由代理服务器管理并注入
  3. 用户本地环境无需存储
    DATA_GO_KR_API_KEY

Official API surface

官方API概览

  • Base URL: 
    https://apis.data.go.kr/1741000/household_waste_info
  • Endpoint: 
    GET /info
  • (key injection only) proxy: 
    k-skill-proxy
    가 
    serviceKey
    를 서버 측에서 주입
  • 基础URL: 
    https://apis.data.go.kr/1741000/household_waste_info
  • 端点: 
    GET /info
  • （仅密钥注入）代理: 
    k-skill-proxy
    在服务端注入
    serviceKey

Default path

默认路径

추가 client API 레이어는 불필요하다. Base URL은 원본 API를 기준으로 유지한다.
현재 proxy가 지원하는 쿼리 파라미터(이외 값은 무시된다):
  • serviceKey
    : proxy가 서버 측에서 주입하는 인증키 (
    DATA_GO_KR_API_KEY
    ) — 클라이언트에서 전달 금지
  • pageNo
    : 페이지 번호 (기본값 
    1
    )
  • numOfRows
    : 페이지 크기 (기본값 
    20
    , 최대 100)
  • returnType
    : proxy가 항상 
    json
    으로 강제 — 클라이언트가 값을 보내도 무시된다
  • cond[SGG_NM::LIKE]
    : 시군구명 포함 검색 (필수)
원본 API의 
cond[DAT_CRTR_YMD::*]
, 
cond[DAT_UPDT_PNT::*]
같은 부가 필터는 현재 proxy 라우트에서 패스스루되지 않는다. 사용자가 보내는 일반적인 질의("강남구 쓰레기 배출 요일")는 시군구 기준 검색만으로 충분하므로, 필요하다면 응답에서 
DAT_UPDT_PNT
기준으로 클라이언트에서 정렬한다.
无需额外的客户端API层，基础URL保持为原始API地址。
当前代理支持的查询参数（其他参数将被忽略）:
  • serviceKey
    : 代理在服务端注入的认证密钥（
    DATA_GO_KR_API_KEY
    ）—— 禁止客户端传递
  • pageNo
    : 页码（默认值 
    1
    ）
  • numOfRows
    : 单页数据量（默认值 
    20
    ，最大100）
  • returnType
    : 代理强制返回
    json
    格式 —— 客户端传递的该参数将被忽略
  • cond[SGG_NM::LIKE]
    : 包含市郡区名的模糊搜索（必填）
原始API的
cond[DAT_CRTR_YMD::*]
、
cond[DAT_UPDT_PNT::*]
等附加过滤参数当前不会通过代理路由透传。用户的常规查询（如"江南区垃圾排放日期"）仅需基于市郡区搜索即可满足需求，如有需要可在客户端按响应中的
DAT_UPDT_PNT
（数据更新时间）排序。

Workflow

工作流程

1) Ask location first

1) 首先询问地区

사용자 지역 정보 없이 바로 조회하지 않는다.
  • 권장 질문: 
    확인할 지역(시/군/구)을 알려주세요. 예: 강남구, 수원시 영통구
无用户地区信息时不直接发起查询。
  • 推荐询问话术: 
    请告知需要查询的地区（市/郡/区）。例如：江南区、水原市灵通区

2) Validate input and resolve query

2) 验证输入并解析查询

  • 시군구 입력이 비어 있으면 다시 물어본다.
  • 모호한 입력이면 상위 행정구역 포함 형태로 재질문한다.
  • 市郡区输入为空时再次询问用户
  • 输入模糊时请用户补充上级行政区划信息后再次确认

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

3) 通过代理调用（服务端注入serviceKey）

proxy가 
serviceKey
를 서버 측에서 주입한 뒤 원본 API로 전달한다.
bash
curl -fsS --get 'https://k-skill-proxy.nomadamas.org/v1/household-waste/info' \
  --data-urlencode "pageNo=1" \
  --data-urlencode "numOfRows=20" \
  --data-urlencode "cond[SGG_NM::LIKE]=강남구"
returnType
은 proxy가 항상 
json
으로 강제하므로 클라이언트에서 별도로 보낼 필요가 없다.
KSKILL_PROXY_BASE_URL
이 있으면 그 값을 사용하고, 없으면 기본 hosted proxy(
k-skill-proxy.nomadamas.org
)를 사용한다.
代理在服务端注入
serviceKey
后转发请求到原始API。
bash
curl -fsS --get 'https://k-skill-proxy.nomadamas.org/v1/household-waste/info' \
  --data-urlencode "pageNo=1" \
  --data-urlencode "numOfRows=20" \
  --data-urlencode "cond[SGG_NM::LIKE]=강남구"
returnType
由代理强制设置为
json
，因此客户端无需额外传递该参数。
如果配置了
KSKILL_PROXY_BASE_URL
则使用该值，否则使用默认托管代理（
k-skill-proxy.nomadamas.org
）。

4) Summarize for user

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
    )
仅从响应中提取必要项做简要整理:
  • 管理区域/目标区域（
    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개 핵심 포인트로 요약해 안내했다.
  • 已确认用户所在地区（市/郡/区）
  • 代理接口
    /v1/household-waste/info
    调用成功
  • 已将投放日期/时间/地点整理为3~6个核心要点告知用户

Failure modes

异常场景

  • 프록시 서버에 
    DATA_GO_KR_API_KEY
    가 없거나 만료된 경우 (
    serviceKey
    주입 실패)
  • 검색 지역명이 API 데이터와 불일치하여 결과가 비는 경우
  • 공공데이터 API 일시 장애/트래픽 제한
  • 필수 파라미터 누락(
    cond[SGG_NM::LIKE]
    )
  • 代理服务器未配置
    DATA_GO_KR_API_KEY
    或密钥已过期（
    serviceKey
    注入失败）
  • 搜索的地区名与API数据不匹配导致无返回结果
  • 公共数据API临时故障/流量限制
  • 缺失必填参数（
    cond[SGG_NM::LIKE]
    ）

Notes

注意事项

  • 사용자 측에 
    DATA_GO_KR_API_KEY
    를 저장하지 않고 proxy 서버에서만 관리한다.
  • API raw payload를 그대로 노출하지 말고 사용자 친화적으로 요약한다.
  • 응답이 여러 건이면 최신 
    DAT_UPDT_PNT
    기준으로 우선 정렬해 보여준다.
  • 공식 데이터 출처: 공공데이터포털 (
    https://www.data.go.kr
    )
  • 不在用户侧存储
    DATA_GO_KR_API_KEY
    ，仅在代理服务器管理该密钥
  • 不要直接暴露API原始返回内容，需整理为用户友好的摘要形式
  • 如有多条响应结果，优先按最新的
    DAT_UPDT_PNT
    排序后展示
  • 官方数据来源: 公共数据门户（
    https://www.data.go.kr
    ）