mirror of
https://github.com/NomaDamas/k-skill.git
synced 2026-09-14 16:37:18 +08:00
Jeffrey (Dongkyu) Kim
617a025931
Wraps the official data.go.kr LH (Korea Land & Housing Corporation) 청약 공고 Open API (B552555/lhLeaseNoticeInfo1/*) so agents can look up LH 임대/분양/주거복지/토지/상가 공고 by region, status, category, keyword, and notice ID without asking users for a ServiceKey. Reuses the shared DATA_GO_KR_API_KEY the proxy already manages; users see '불필요'. Adapter handles both the LH-specific [CMN, dsList] JSON envelope and the standard data.go.kr <OpenAPI_ServiceResponse> XML error envelope; refuses to cache failure responses so transient upstream errors self-heal. Closes #145.
138 lines
6.4 KiB
Markdown
138 lines
6.4 KiB
Markdown
# 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 예시
|
|
|
|
공고중인 부산 영구임대 공고 목록:
|
|
|
|
```bash
|
|
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'
|
|
```
|
|
|
|
키워드 검색 (행복주택, 접수중만):
|
|
|
|
```bash
|
|
curl -fsS --get 'https://k-skill-proxy.nomadamas.org/v1/lh-notice/search' \
|
|
--data-urlencode 'q=행복주택' \
|
|
--data-urlencode 'status=접수중'
|
|
```
|
|
|
|
공고 상세:
|
|
|
|
```bash
|
|
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'
|
|
```
|
|
|
|
## 응답 예시 (목록)
|
|
|
|
```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",
|
|
"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 공고 모음집 샘플 구현)
|