applyhome — 청약홈 분양정보 조회 (공공데이터 API)

한국부동산원이 공공데이터포털에 제공하는 청약홈 오픈 API(api.odcloud.kr)를 조회한다. 사이트(applyhome.co.kr) 스크래핑이 아니라 공식 JSON API다.

인증

data.go.kr에서 "한국부동산원_청약홈 분양정보 조회 서비스"를 활용신청하고 Decoding 키를 받아 둔다. scripts/applyhome.sh 는 키를 이 순서로 찾는다:

1. 환경변수 APPLYHOME_API_KEY
2. ~/.claude/applyhome.env 의 APPLYHOME_API_KEY=... 한 줄 (APPLYHOME_ENV_FILE 로 경로 변경 가능)

키 만료·한도 초과 시 data.go.kr 마이페이지에서 확인한다 (개발계정 일 1,000회).

대표 시나리오 → 커맨드 매핑

사용법 (전부 읽기 전용 — 자유 실행)

S=~/.claude/skills/applyhome/scripts/applyhome.sh

$S upcoming 서울                # 접수시작일이 오늘 이후인 APT 공고 (특공·1순위 접수일 표시)
$S search 월곶                  # 단지명+공급위치 키워드 검색 (APT+오피스텔+무순위, 최근 90일)
$S newlywed 경기                # 특공 접수 예정 공고 + 신혼희망타운 목록
$S apt 2026-08-01 서울          # 모집공고일 기준 APT 목록 (FROM 생략="" → 30일 전부터)
$S apt-detail 2026000364        # 공고 상세 (전체 필드 JSON, PBLANC_URL 포함)
$S models 2026000364            # 주택형별 공급세대수·특공세대수·분양최고가(만원)
$S officetel "" 서울            # 오피스텔/도시형/생활숙박/민간임대
$S remndr                       # 무순위·잔여세대(줍줍)
$S competition 2026000355       # 경쟁률 — APT→무순위→오피스텔 순 자동 폴백
$S stat-area 202607             # 지역별 신청·당첨자 통계 (YYYYMM)
$S raw <path> ['cond[필드::연산]=값' ...]   # 임의 엔드포인트 직접 호출

• 목록의 첫 컬럼 **공고관리번호(HOUSE_MANAGE_NO)**를 apt-detail/models/competition에 넘긴다.
• 지역명은 청약홈 표기 그대로: 서울/경기/인천/부산/대구/대전/광주/울산/세종/강원/충북/충남/전북/전남/경북/경남/제주.
• search 빈 결과 = 최근 90일 내 해당 키워드 공고가 없는 것. 기간을 넓히려면 raw ... 'cond[HSSPLY_ADRES::LIKE]=월곶' (RCRIT_PBLANC_DE 조건 없이).
• 경쟁률은 접수 마감된 공고에만 존재. 접수 전 공고는 빈 결과가 정상.

신혼부부 관련 답변 가이드

• newlywed 출력은 두 부분: ① 특공 접수 예정 공고 — 민영·국민주택 특공에는 보통 신혼부부 유형이 포함되지만 유형별 배정 세대수는 API에 없으므로 공고문 링크(PBLANC_URL) 확인을 안내한다. ② 신혼희망타운 — 전량 신혼부부·예비신혼부부 대상 (HOUSE_SECD_NM 필터).
• 신혼부부 특공 기본 자격(민영 기준): 혼인 7년 이내(또는 6세 이하 자녀), 무주택 세대, 소득·자산 기준 충족, 청약통장 6개월+. 상세 기준은 공고마다 다르므로 공고문이 최종.

청약 제도 지식 (시나리오 4 — API 아님, 답변용 요약)

• 1순위 조건 (민영주택): 청약통장 가입 후 일정 기간 경과(규제지역 24개월, 수도권 12개월, 그 외 6개월) + 지역·면적별 예치금 충족 (서울 85㎡ 이하 300만원 ~ 모든면적 1,500만원). 규제지역은 추가로 세대주여야 하고, 재당첨 제한·5년 내 당첨 세대 제외.
• 1순위 조건 (국민주택): 가입 기간 + 납입 횟수(규제지역 24회, 수도권 12회, 그 외 6회), 무주택 세대 구성원만 가능. 40㎡ 초과는 저축총액, 이하는 납입횟수로 경쟁.
• 2순위: 1순위가 아닌 청약통장 가입자 전부. 1순위에서 미달돼야 기회가 온다.
• 당첨자 선정 (민영): 가점제(무주택기간 32점 + 부양가족 35점 + 통장가입기간 17점 = 84점 만점) 와 추첨제를 면적·지역별 비율로 혼용.
• 특별공급 유형: 신혼부부·생애최초·다자녀·노부모부양·기관추천 등. 각각 소득/자산/무주택 요건.
• 개인의 가점 계산·자격 확인은 로그인 영역이라 불가 — 청약홈 사이트의 "청약가점 계산기"를 안내한다.

한계

• 공개 공고·경쟁률 데이터만 제공. 개인 청약신청, 가점/자격 조회, 청약통장 정보는 불가능.
• perPage=100 고정 — 초과가 예상되면 기간(FROM)이나 지역 조건을 좁힌다.

추가 리소스

• scripts/applyhome.sh — API 래퍼 (키 로드, cond 인코딩, jq 정형 출력)
• 엔드포인트: ApplyhomeInfoDetailSvc/v1/{getAPTLttotPblancDetail, getAPTLttotPblancMdl, getUrbtyOfctlLttotPblancDetail, getUrbtyOfctlLttotPblancMdl, getRemndrLttotPblancDetail, getRemndrLttotPblancMdl}, ApplyhomeInfoCmpetRtSvc/v1/{getAPTLttotPblancCmpet, getRemndrLttotPblancCmpet, getUrbtyOfctlLttotPblancCmpet}, ApplyhomeStatSvc/v1/{getAPTReqstAreaStat, getAPTReqstAgeStat, getAPTPrzwnerAreaStat}