lh-notice-search

intent

query korea land housing corp (lh) rental, sales, housing welfare, land, and commercial notices posted on apply.lh.or.kr through the official lh open api on data.go.kr. requests route through k-skill-proxy's /v1/lh-notice/* endpoints, returning notice lists and detailed supply info by unit type. use this skill when you need to surface lh notices to users who may not know they exist, helping them find postings before deadlines close.

inputs

proxy connection:

• KSKILL_PROXY_BASE_URL env var (defaults to https://k-skill-proxy.nomadamas.org if unset)
• requires internet connectivity and curl or equivalent http tool
• no user-facing secrets required; DATA_GO_KR_API_KEY lives server-side on k-skill-proxy

search endpoint (/v1/lh-notice/search) parameters:

• panSs or status: notice state (공고중, 접수중, 접수마감, 당첨자발표, 추정공고). omit for all states.
• uppAisTpCd or category: housing major class (01=land, 05=sales housing, 06=rental housing, 13=housing welfare/new couple town, 22=commercial). omit for all.
• aisTpCd: housing subclass code (numeric). examples: 09=permanent rental, 10=happy house, 17=lease-transfer rental, 08=national rental, 26=acquisition rental.
• cnpCdNm or region: region name (예: 서울특별시, 부산광역시, 전국). omit for all.
• panNm or q or keyword: partial match on notice title. example: 행복주택, 청년, 든든주택.
• panNtStDt or startDate: notice posted date start. formats: YYYY-MM-DD, YYYYMMDD, YYYY.MM.DD all accepted.
• clsgDt or endDate: application deadline end date. same format options.
• page: default 1, max 1000.
• pageSize: default 50, max 1000.

detail endpoint (/v1/lh-notice/detail) parameters (all three required):

• panId: notice id from list response pan_id
• ccrCnntSysDsCd: linkage system code from list response ccr_cnnt_sys_ds_cd
• splInfTpCd: supply info type code from list response spl_inf_tp_cd

procedure

1. parse user intent. extract region, housing type (category or aisTpCd), notice state (status), keyword (q), date range (startDate, endDate), and whether user wants list or detail.

   • input: user query in korean
   • output: normalized filter dict with keys panSs, uppAisTpCd, aisTpCd, cnpCdNm, panNm, panNtStDt, clsgDt, page, pageSize

2. build and execute search request. construct url-encoded query string for /v1/lh-notice/search. use KSKILL_PROXY_BASE_URL or default. send GET request with curl -fsS.

   • input: normalized filter dict, BASE url
   • output: http response (json on 200, error struct on 400/502/503)

3. validate search response. check response status. if 200, parse json. if not 200, extract error code and message.

   • input: http response
   • output: either parsed json (items, summary, query, proxy) or error dict with code/message

4. summarize results for display. extract top 3-5 notices from items array. for each, show pan_nm, cnp_cd_nm, pan_dt, clsg_dt, pan_ss, detail_url. calculate days until clsg_dt in kst. flag notices with deadline <= 3 days.

   • input: items array, current date/time in kst
   • output: formatted text summary with filter recap, result count (returned_count / total_count), top notices, urgency flags

5. offer detail lookup. if user asked for specific notice or wants more info, prepare detail request. extract panId, ccrCnntSysDsCd, splInfTpCd from one list result.

   • input: list response item, user intent
   • output: detail query params dict

6. execute detail request (if needed). send GET /v1/lh-notice/detail with three params. parse response.

   • input: detail query params, BASE url
   • output: parsed json with notice (summary) + supply_infos (array of housing types with unit counts)

7. summarize detail for display. show notice title, region, type, posted date, deadline, status, supply_infos table (unit type, count), and apply.lh.or.kr link.

   • input: detail response json
   • output: formatted detail summary

decision points

if user specifies notice id (panId): skip search, go directly to step 6 (detail lookup). require ccrCnntSysDsCd and splInfTpCd or return error.

if search returns 0 results: inform user no notices match filters. suggest broadening filters (remove region, category, or status constraints). do not make up results.

if search returns > 1000 results (total_count > 1000): inform user limit reached. recommend narrowing by region, housing type, or date range. show only first pageSize results.

if upstream returns 400 bad_request: expose error message verbatim. examples: invalid panSs value (not in 공고중, 접수중, 접수마감, 당첨자발표, 추정공고), invalid date format, invalid region name. guide user to correct.

if upstream returns 502 upstream_error with code 30: proxy lacks or has invalid DATA_GO_KR_API_KEY. ask proxy admin to configure.

if upstream returns 502 upstream_error with other code: data.go.kr api returned xml error envelope. recommend retry after a few seconds (not cached).

if upstream returns 502 upstream_invalid_payload: upstream returned non-json. likely data.go.kr service interruption. recommend retry.

if upstream returns 503 upstream_not_configured: proxy not initialized. check KSKILL_PROXY_BASE_URL env var and proxy service status.

if clsg_dt is today (kst): label notice as "오늘 마감" (deadline today).

if clsg_dt is in past: label notice as "마감됨" (closed). do not highlight unless user explicitly asked for closed notices.

if user asks for sh (seoul), gh (gyeonggi), or ih (incheon) notices: explain this skill covers only lh. recommend searching apply.sh.or.kr, apply.gh.or.kr, apply.ih.or.kr separately.

if user asks for application automation, lottery prediction, or score calculation: decline. this skill reads notices only. do not infer or calculate eligibility.

output contract

list response format:

• filter summary line: "(region) (category/type) (status)" e.g. "(부산광역시) (임대주택 영구임대) (공고중)"
• result count: "총 N건, 조회됨 M건" (total_count, returned_count)
• per-notice line: "공고명 | 지역 | 공고일 | 마감일 [마감임박/오늘마감/마감됨] | 공고번호 | 링크"
• if deadline <= 3 days: prepend "⚡ " or "마감임박" flag
• always include detail_url (apply.lh.or.kr direct link)
• optionally suggest detail lookup: "공고번호 X 상세 보려면 panId=X&ccrCnntSysDsCd=Y&splInfTpCd=Z 로 detail 조회"

detail response format:

• notice title, region, housing type (ais_tp_cd_nm), posted date, deadline, status
• supply_infos table: columns HOUSE_TY (unit type), SPL_CNT (count)
• apply.lh.or.kr direct link
• panId, ccrCnntSysDsCd, splInfTpCd included for record-keeping

error response format:

• status: 400, 502, 503
• code: bad_request, upstream_error, upstream_not_configured, upstream_invalid_payload
• message: user-facing explanation (korean preferred)
• upstream_code (optional): raw error code from data.go.kr if applicable

response character limit: compress to 3-5 top notices in list view. detail view can be longer (include full supply table).

outcome signal

user has:

• seen at least one /v1/lh-notice/search result matching their region, housing type, and status intent
• received notice titles, regions, posted/deadline dates, statuses, and official apply.lh.or.kr links in the summary
• been told which notices close soonest (deadline <= 3 days flagged and highlighted)
• optionally requested and received detail for a specific notice including unit type breakdowns