k-skill/docs/features/lh-notice-search.md

LH 청약 공고문 조회 가이드

한국토지주택공사(LH)가 apply.lh.or.kr 로 공고하는 임대주택·분양주택·주거복지(신혼희망타운)·토지·상가 공고를 공공데이터포털 공식 LH 공고 Open API(http://apis.data.go.kr/B552555/lhLeaseNoticeInfo1/...)로 조회한다. 프록시 서버가 serviceKey 주입, 캐시, 율속을 맡는다.

이 기능으로 할 수 있는 일

• 공고중·접수중·접수마감 등 상태별 LH 공고 목록 조회
• 지역(시/도), 공고 유형(영구임대·행복주택·전세임대·국민임대·매입임대·분양주택·신혼희망타운 등) 필터링
• 공고명 키워드 검색 (예: "행복주택", "든든주택", "청년", "신혼희망")
• 공고 게시일·접수 마감일 구간 필터
• 공고 상세(주택형별 공급 정보, 공식 링크) 확인

가장 중요한 규칙

기본 경로는 https://k-skill-proxy.nomadamas.org/v1/lh-notice/... 이다. 사용자는 공공데이터포털 ServiceKey 를 준비할 필요가 없다. upstream key(DATA_GO_KR_API_KEY)는 프록시 서버에서만 주입한다.

마감 여부는 KST(Asia/Seoul) 기준으로 판정한다. host local time 을 쓰지 않는다.

본 스킬은 LH 공고 전용이다. SH(서울), GH(경기), iH(인천) 등 지방 주택공사 공고는 포함되지 않는다. 사용자가 그런 공고를 찾으면 본 스킬 범위가 아님을 분명히 말한다.

먼저 필요한 것

• 인터넷 연결
• curl 또는 HTTP 호출이 가능한 도구
• (프록시 운영자 전용) DATA_GO_KR_API_KEY 환경변수

지원 엔드포인트

Route	설명
GET /v1/lh-notice/search	공고 목록 조회. 필터 전부 선택사항.
GET /v1/lh-notice/detail	특정 공고 상세 + 주택형별 공급 정보. panId/ccrCnntSysDsCd/splInfTpCd 모두 필수.

/v1/lh-notice/search 파라미터

파라미터	타입	기본값	설명
panSs / status	string	(없음)	공고중, 접수중, 접수마감, 당첨자발표, 추정공고
uppAisTpCd / category	string	(없음)	01=토지, 05=분양주택, 06=임대주택, 13=주거복지, 22=상가
aisTpCd	digits	(없음)	세부 분류 코드. 예: 09=영구임대, 10=행복주택, 17=전세임대
cnpCdNm / region	string	(없음)	지역명(시/도). 예: 서울특별시, 부산광역시, 전국
panNm / q / keyword	string	(없음)	공고명 부분 검색
panNtStDt / startDate	date	(없음)	공고 게시일 시작. YYYY-MM-DD / YYYYMMDD / YYYY.MM.DD
clsgDt / endDate	date	(없음)	접수 마감일 종료
page	int	1	페이지 (최대 1000)
pageSize / PG_SZ / numOfRows / limit	int	50	페이지당 건수 (최대 1000)

/v1/lh-notice/detail 파라미터

파라미터	타입	필수	설명
panId	digits	✅	공고 ID. 목록 응답의 pan_id 와 동일
ccrCnntSysDsCd	digits	✅	연계시스템 구분 코드. 목록 응답의 ccr_cnnt_sys_ds_cd
splInfTpCd	digits	✅	공급 정보 유형 코드. 목록 응답의 spl_inf_tp_cd

기본 흐름

1. 사용자 요청의 지역·공고 유형·상태를 추출한다.
2. 필터를 붙여 /v1/lh-notice/search 를 호출한다.
3. KST 오늘 날짜로 마감 여부(D-day)를 표시한다.
4. 공고 상위 3-5건(공고명 / 지역 / 공고일 / 마감일 / 상태 / 링크)을 요약한다.
5. 필요하면 /v1/lh-notice/detail 로 주택형별 공급 정보를 추가 조회한다.

CLI 예시

공고중인 부산 영구임대 공고 목록:

curl -fsS --get 'https://k-skill-proxy.nomadamas.org/v1/lh-notice/search' \
  --data-urlencode 'panSs=공고중' \
  --data-urlencode 'uppAisTpCd=06' \
  --data-urlencode 'cnpCdNm=부산광역시' \
  --data-urlencode 'pageSize=20'

키워드 검색 (행복주택, 접수중만):

curl -fsS --get 'https://k-skill-proxy.nomadamas.org/v1/lh-notice/search' \
  --data-urlencode 'q=행복주택' \
  --data-urlencode 'status=접수중'

공고 상세:

curl -fsS --get 'https://k-skill-proxy.nomadamas.org/v1/lh-notice/detail' \
  --data-urlencode 'panId=2015122300019828' \
  --data-urlencode 'ccrCnntSysDsCd=03' \
  --data-urlencode 'splInfTpCd=051'

응답 예시 (목록)

{
  "items": [
    {
      "pan_id": "2015122300019828",
      "pan_nm": "2026년 상반기 부산광역시 영구임대주택 예비입주자 모집 공고",
      "upp_ais_tp_cd": "06",
      "ais_tp_cd": "09",
      "ais_tp_cd_nm": "영구임대",
      "cnp_cd_nm": "부산광역시",
      "pan_ss": "공고중",
      "pan_dt": "2026-04-21",
      "clsg_dt": "2026-05-06",
      "spl_inf_tp_cd": "051",
      "ccr_cnnt_sys_ds_cd": "03",
      "detail_url": "https://apply.lh.or.kr/lhapply/apply/wt/wrtanc/selectWrtancInfo.do?panId=2015122300019828&..."
    }
  ],
  "summary": { "page": 1, "page_size": 20, "returned_count": 1, "total_count": 1 },
  "query": { "pan_ss": "공고중", "upp_ais_tp_cd": "06", "cnp_cd_nm": "부산광역시" },
  "proxy": { "name": "k-skill-proxy", "cache": { "hit": false, "ttl_ms": 300000 } }
}

실패 모드

• 400 bad_request: panSs 값이 허용되지 않거나, 날짜 포맷이 잘못된 경우 등. 메시지를 그대로 사용자에게 노출한다.
• 503 upstream_not_configured: 프록시 서버에 DATA_GO_KR_API_KEY 가 없는 경우. 운영자가 키를 등록해야 한다.
• 502 upstream_error: 공공데이터포털 서버 오류 또는 XML 에러 envelope. upstream_code 에 원본 코드가 들어간다 (예: 30 = 등록되지 않은 서비스키).
• 502 upstream_invalid_payload: 응답이 JSON 이 아닌 경우 (보통 HTML 장애 페이지).

Done when

• 공식 LH 공고 목록을 조회했다.
• 마감 여부를 KST 기준으로 판정해 표시했다.
• 각 결과에 공고 상세 링크(detail_url)를 포함했다.
• 필요한 경우 panId/ccrCnntSysDsCd/splInfTpCd 를 제공해 상세 조회로 이어갈 수 있도록 안내했다.

출처/참고

• LH 청약플러스 공고 목록: https://apply.lh.or.kr/lhapply/apply/wt/wrtanc/selectWrtancList.do?mi=1026
• 공공데이터포털 LH 임대공고문 정보 API: https://www.data.go.kr/data/15058530/openapi.do
• 레퍼런스 오픈소스: heereal/Bunyang_MoeumZip (Next.js 기반 LH/SH 공고 모음집 샘플 구현)