Lh Notice Search

# LH 청약 공고문 조회

## What this skill does

한국토지주택공사(LH)가 `apply.lh.or.kr` 로 공고하는 **임대주택·분양주택·주거복지(신혼희망타운 등)·토지·상가 공고**를 공공데이터포털(`data.go.kr`)의 공식 LH 공고 Open API로 조회한다. 요청은 `k-skill-proxy` 의 `/v1/lh-notice/*` 라우트로 보내고, 결과는 공고 목록·공고 상세(주택형별 공급 정보)로 정리한다.

본 스킬은 사회초년생, 청년, 신혼부부처럼 **LH 공고 존재 자체를 모르는 사용자**가 공고 마감 전에 공고문을 빠르게 찾을 수 있도록 돕는다.

## When to use

- "LH 영구임대 공고 지금 뭐 올라와 있어?"
- "신혼희망타운 공고 요즘 나온 거 정리해줘"
- "부산광역시 LH 임대주택 공고중인 것 보여줘"
- "전세임대 공고 중 마감 임박한 거 찾아줘"
- "공고번호 2015122300019828 상세 정보 보여줘"
- "행복주택 청년 모집 공고 요약해줘"

## When not to use

- 개별 사용자의 자격 심사, 당첨 예측, 가점 계산
- 청약 신청 자동화/자동 제출 (본 스킬은 read-only 조회다)
- 청약통장·주택도시기금 계좌 업무 (해당 범위는 LH 공고와 별개다)
- SH(서울주택도시공사)·GH(경기주택도시공사)·iH(인천도시공사) 전용 공고 (본 스킬은 LH 공고만 다룬다)

## Inputs

- `panSs` (또는 `status`): 공고 상태. `공고중`, `접수중`, `접수마감`, `당첨자발표`, `추정공고` 중 하나. 비우면 전체.
- `uppAisTpCd` (또는 `category`): 주택 대분류. `01`(토지), `05`(분양주택), `06`(임대주택), `13`(주거복지·신혼희망타운), `22`(상가).
- `aisTpCd`: 세부 분류 코드 (숫자). 예: `09`=영구임대, `10`=행복주택, `17`=전세임대.
- `cnpCdNm` (또는 `region`): 지역명. 예: `서울특별시`, `부산광역시`, `전국`.
- `panNm` (또는 `q`, `keyword`): 공고명 부분 검색 키워드. 예: `행복주택`, `청년`, `든든주택`.
- `panNtStDt` (또는 `startDate`): 공고 게시일 시작. YYYY-MM-DD / YYYYMMDD / YYYY.MM.DD 모두 허용.
- `clsgDt` (또는 `endDate`): 접수 마감일 종료. 날짜 포맷 동일.
- `page` (기본 1, 최대 1000), `pageSize` (기본 50, 최대 1000).

상세 조회 (`/v1/lh-notice/detail`) 는 `panId`, `ccrCnntSysDsCd`, `splInfTpCd` 세 값 모두 필수다. 이 값은 목록 응답의 `pan_id`, `ccr_cnnt_sys_ds_cd`, `spl_inf_tp_cd` 를 그대로 쓰면 된다.

## Prerequisites

- 인터넷 연결
- `curl` (또는 동일한 HTTP 호출이 가능한 도구)

사용자에게 필요한 시크릿은 없다. 공공데이터포털 `DATA_GO_KR_API_KEY` 는 `k-skill-proxy` 서버 쪽에만 둔다.

## Default path

`KSKILL_PROXY_BASE_URL` 환경변수가 있으면 그 값, 없으면 기본 `https://k-skill-proxy.nomadamas.org` 를 사용한다.

```bash
BASE="${KSKILL_PROXY_BASE_URL:-https://k-skill-proxy.nomadamas.org}"
BASE="${BASE%/}"
```

## Supported endpoints

### 공고 목록 조회

```
GET /v1/lh-notice/search
```

필터는 선택사항이다. 필터 없이 호출하면 최근 공고를 상태 무관하게 최대 50건 돌려준다. 마감 임박한 공고만 보고 싶다면 `panSs=공고중` 과 `clsgDt` 로 구간을 좁힌다.

### 공고 상세 조회

```
GET /v1/lh-notice/detail?panId={공고ID}&ccrCnntSysDsCd={연계시스템코드}&splInfTpCd={공급정보유형코드}
```

상세 응답은 `notice`(공고 요약) + `supply_infos`(주택형/필지/상가호 별 공급 정보 배열) 를 돌려준다.

## Example requests

### 목록 — 부산 영구임대 공고중

```bash
curl -fsS --get "${BASE}/v1/lh-notice/search" \
  --data-urlencode 'panSs=공고중' \
  --data-urlencode 'uppAisTpCd=06' \
  --data-urlencode 'cnpCdNm=부산광역시' \
  --data-urlencode 'pageSize=20'
```

### 목록 — 키워드 "행복주택" 으로 접수중

```bash
curl -fsS --get "${BASE}/v1/lh-notice/search" \
  --data-urlencode 'q=행복주택' \
  --data-urlencode 'status=접수중'
```

### 상세 — 특정 공고

```bash
curl -fsS --get "${BASE}/v1/lh-notice/detail" \
  --data-urlencode 'panId=2015122300019828' \
  --data-urlencode 'ccrCnntSysDsCd=03' \
  --data-urlencode 'splInfTpCd=051'
```

## Response shape

### 목록 응답

```json
{
  "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",
      "rcrit_pblanc_dt": null,
      "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 }
  }
}
```

### 상세 응답

```json
{
  "notice": {
    "pan_id": "201512230001