| name | sh-notice-search |
| description | 서울주택도시개발공사(SH) 공개 공고/공지 게시판에서 청약·주택 공고 목록, 상세 본문, 첨부 미리보기 메타데이터를 직접 조회한다. |
| license | MIT |
| metadata | {"category":"housing","locale":"ko-KR","phase":"v1"} |
SH Notice Search
What this skill does
서울주택도시개발공사(SH, www.i-sh.co.kr)의 공고 및 공지 공개 HTML 게시판을 직접 읽어 청약·주택 공고 목록과 상세 본문, 첨부파일 메타데이터를 JSON으로 정리한다.
- 키워드로 SH 공고/공지 목록을 검색한다.
- 공식 게시판 분류(주택임대, 주택분양, 주택매입/주거복지, 토지, 상가/공장 등)를 선택한다.
- 상세 페이지에서 본문, 담당부서, 등록일, 조회수, 실제 첨부파일명을 추출한다.
- 첨부는 아이콘 템플릿이 아니라
existFile('N') onclick이 달린 실제 첨부 앵커와 downList 메타데이터를 기준으로 추출한다.
청약 신청, 서류 제출, 로그인 필요한 마이페이지 조회, 결제, 알림 발송은 하지 않는다.
When to use
- "SH 행복주택 공고 찾아줘"
- "서울주택도시개발공사 매입임대 공고 보여줘"
- "SH 공고 seq 304371 상세와 첨부파일 알려줘"
- "SH 분양 공고 최신 목록 조회"
Prerequisites
- 인터넷 연결
- Node.js 18+
- 이 저장소의
sh-notice-search npm package 또는 동일 로직
Public access path discovered
Primary source: official SH public HTML board
- default rent list:
https://www.i-sh.co.kr/app/lay2/program/S1T294C297/www/brd/m_247/list.do?multi_itm_seq=2
- default rent detail:
https://www.i-sh.co.kr/app/lay2/program/S1T294C297/www/brd/m_247/view.do?multi_itm_seq=2&seq=<seq>
- title keyword search: add
srchWord=<keyword>&srchTp=0
- content keyword search: add
srchWord=<keyword>&srchTp=1
- fixed board page size: 10 rows per page; use
page for pagination.
Discovery result: direct unauthenticated fetches from www.i-sh.co.kr return list/detail HTML. A live smoke on 2026-05-15 showed srchWord=행복주택 without srchTp returned the full rent board count, while srchTp=0 narrowed the result set. Therefore the client always sends srchTp when a keyword is present.
No k-skill-proxy route is used because this upstream is public and does not require an API key.
Supported category aliases
| Input aliases | Official tab |
|---|
rent, 임대, 주택임대 | 주택임대 (multi_itm_seq=2) |
sale, 분양, 주택분양 | 주택분양 (multi_itm_seq=1) |
purchase, 매입, 매입임대, welfare, 주거복지 | 주택매입 (multi_itm_seq=512) |
land, 토지 | 토지 |
commercial, 상가, 공장 | 상가/공장 |
compensation, 보상, 이주 | 보상/이주 |
design, 현상설계 | 현상설계 |
etc, 기타 | 기타 |
all, 전체 | 전체 |
주거복지는 SH 공고 및 공지의 공개 탭명이 아니라 사용자 친화 alias이며, 현재는 SH의 공개 주택매입 탭으로 매핑한다. 답변할 때는 이 매핑을 밝힌다.
Workflow
1. Search notices
const { searchNotices } = require("sh-notice-search")
const result = await searchNotices({
keyword: "행복주택",
category: "임대",
page: 1,
limit: 5
})
console.log(result.items)
CLI:
node packages/sh-notice-search/src/cli.js 행복주택 --category 임대 --limit 5
node packages/sh-notice-search/src/cli.js 매입임대 --category 주거복지 --status 진행
Returned list fields include:
seq
title
department
registered_date
views
is_new
category, category_name
status, status_basis
detail_url
2. Fetch detail
const { getNoticeDetail } = require("sh-notice-search")
const detail = await getNoticeDetail({ seq: "304371", category: "임대" })
console.log(detail.notice.content_text)
console.log(detail.notice.attachments)
CLI:
node packages/sh-notice-search/src/cli.js --seq 304371 --category 임대
Attachment fields:
filename
file_seq
file_size
file_type
preview_url (official SH preview/converter URL)
Direct download URLs are intentionally not returned. Hand off detail_url or preview_url to the user's browser.
3. Interpret status conservatively
The SH public board list does not expose a first-class status field like 접수중/마감. The package can filter by status, but it is a title-text classifier:
open/진행: titles with 모집공고, 입주자 모집, 신청, 접수, 공고
closed/마감: titles with 마감, 계약결과, 결과, 완료, 종료
announced/당첨자: titles with 당첨, 발표
When answering, disclose that status is inferred from the title unless the detailed 공고문 body states exact dates.
Done when
- Official SH list/detail URLs were queried directly from the user machine.
- Keyword searches include
srchTp so srchWord is not ignored.
- Pagination uses
page and recognizes the fixed 10-row board page size.
- Attachments are extracted from actual
existFile() anchors/downList metadata, not extension icon templates.
- Public source URLs are shown, and login/application automation is avoided.
Failure modes
- SH can change board paths, table markup, JavaScript functions, or
downList structure; parsing may become partial or fail.
- IP-rate-limit, NetFunnel throttling, maintenance pages, or temporary 4xx/5xx responses can block live fetches. Do not bypass CAPTCHA/login/queue protections.
srchWord without srchTp is known to be ignored by the SH board; always send srchTp=0 for title or srchTp=1 for content.
pageSize larger than 10 does not make SH return more rows. Use page for additional results.
- Attachment preview URLs may require browser handoff and can be governed by SH's current direct-link/download policy.
- Status is inferred from title text because the public list lacks an explicit status column.
Notes
- Read-only lookup only.
- No proxy, no API key, no secrets.
- Do not automate 청약 신청, 로그인, 서류 제출, payment, or 마이페이지 flows.