2026년 9월 6일 일요일

[바이브 코딩] 한국천문연구원 특일 정보 API - 오늘의 절기·음력 달력 교구 만들기



오늘의 절기·음력 달력 교구 만들기 — 한국천문연구원 특일 정보 API 완전 정복

🌙 한국천문연구원 특일 정보 API는 공휴일·음력 양력 변환·24절기(입춘·우수·춘분…)·기타 국가의 날을 알려주는 공공데이터포털 기반 서비스입니다. 날짜마다 달라지는 '하늘의 달력'을 학급에서 데이터로 탐구할 수 있게 해줍니다.

'오늘은 무슨 절기일까?'라는 질문이 사회(계절과 생활)·과학(지구 운동) 단원을 잇는 질문이 되고, 학기마다 달라지는 절기 카드를 스스로 채워 넣는 자연 달력 교구가 완성됩니다.

📖 한 줄 정의

심기 모드(데이터 임베딩): API 데이터를 미리 받아 HTML 파일 안 상수로 박아두는 방식(앱 실행 중 외부 통신 0).

학내망 원칙: 학교 배포 웹앱은 개인정보 수집·저장·전송 없음(외부 CDN·API 호출 0, 단일 파일) — 학생은 학내망에서 교사 PC 서버에 접속.

1. 3대 핵심 분석 비교표

무엇이 바뀌었나요? / 영역 초보자를 위한 쉬운 설명 이렇게 한번 써보세요!
하늘의 달력 공휴일·음력·24절기·기타 국가의 날을 한 곳에서 주는 천문학 공식 데이터. 달력이 단순 표가 아니라 데이터가 됩니다. 9월 달력을 뽑아 음력과 양력을 나란히 놓고 비교하기.
키 발급·CORS 공공데이터포털 가입 후 무료 키 발급. 실측으로 이 API의 서버는 브라우저 직접 호출(CORS)을 지원하는 것으로 확인 — 키만 있으면 fetch 가능합니다. 교사 PC 시연용으로 실시간 모드, 학생 배포용은 절기 데이터 심기 모드.
24절기 데이터 입춘부터 대한까지 24개 절기의 날짜가 매년 조금씩 달라지는 이유를 데이터로 체감할 수 있습니다. 올해 24절기 날짜표를 상수로 심고 '가까운 절기 찾기' 놀이.

2. 핵심 아키텍처 해설 — 특일 정보 API와 이중 모드 설계

① URL 해부와 파라미터

특일 정보 서비스는 다음 주소 체계를 사용합니다(공공데이터포털 B090041 서비스):

https://apis.data.go.kr/B090041/openapi/service/SpcdeInfoService/get24DivisionInfo
  ?serviceKey=인증키&solYear=2026&numOfRows=30&pageNo=1
  • getHoliDeInfo: 국가 공휴일 조회 (solYear·solMonth)
  • get24DivisionInfo: 24절기 조회 (입춘·우수·춘분 등)
  • getLunarCalInfo: 음력↔양력 변환
  • getSundryDayInfo: 기타 국가의 날 조회

② 실측 응답 데이터 모양

실측으로 키 없이 호출하면 401(인증 실패) 응답이 오고, 정상 호출 시 날짜 정보가 XML/JSON으로 돌아옵니다:

{
  "response": {
    "body": {
      "items": {
        "item": {
          "dateKind": "24",
          "dateName": "입춘",
          "locdate": "20260204"
        }
      }
    }
  }
}

dateKind가 24면 절기, 01이면 공휴일, 05면 기타 국가의 날입니다. 날짜는 YYYYMMDD 형태로 옵니다.

③ 이중 모드 설계 (실시간 fetch + 심기 폴백)

실측으로 이 API 서버는 CORS를 지원하므로 키만 있으면 브라우저에서 직접 fetch가 가능합니다. 다만 학생 배포용은 외부 통신 0이 원칙이므로 두 모드를 상수 하나로 전환합니다.

const EMBED_SEASONS = [
  { name: "입춘", date: "2026-02-04", note: "봄의 시작" },
  { name: "춘분", date: "2026-03-20", note: "낮과 밤의 길이가 거의 같아짐" },
  { name: "한로", date: "2026-10-08", note: "찬 이슬 맺힐 때" },
  { name: "동지", date: "2026-12-22", note: "밤이 가장 긴 날" }
];

async function loadSeasons(key) {
  if (EMBED_SEASONS.length > 0) return EMBED_SEASONS;   // 심기 모드(데이터 임베딩)
  const qs = new URLSearchParams({ serviceKey: key, solYear: 2026, numOfRows: 30 });
  const res = await fetch(BASE + "/get24DivisionInfo?" + qs);
  const json = await res.json();
  return json.response.body.items.item;
}

3. 초보자를 위한 바이브 코딩 실전 사용 예시

  1. 제미나이 전용 에러 제로 프롬프트 복사 — Gemini에 붙여넣습니다.
  2. 역질문 3가지에 답변 — 달력 범위(학기·연중), 절기 카드 톤, 음력 표시 여부를 결정합니다.
  3. HTML 파일 저장 후 더블클릭 — 절기 카드는 파일 안 상수로 심어 외부 통신 없이 동작합니다.

제미나이 전용 에러 제로 프롬프트

[🚨 에러 방지 기본 안전장치]
1. 결과물은 외부 라이브러리·폰트·이미지 없이 단일 HTML 파일로 완성한다(더블클릭 즉시 실행).
2. 파일 상단 EMBED_SEASONS 상수에 올해 24절기 날짜를 심기 모드(데이터 임베딩)로 내장한다(학생 배포용 외부 통신 0).
3. 실시간 모드는 EMBED_SEASONS가 비어 있을 때만 동작하며, 공공데이터포털 특일 정보 API(SpcdeInfoService)를 fetch한다.
4. 응답 날짜(YYYYMMDD)를 화면용 'YYYY년 M월 D일'로 바꾸는 변환 함수를 반드시 포함한다.
5. '가까운 절기 찾기' 모드: 오늘 날짜와 가장 가까운 절기를 큰 카드로 표시, 남은 일수(D-day) 계산.
6. 학생 표기는 번호·닉네임만 허용(실명·기록 저장 금지), 절기 퀴즈 정답률은 세션 메모리로만 관리.
7. 모바일 터치 대응: 뷰포트 메타 태그 필수, 버튼 최소 44×44px, 360px 화면 가로 스크롤 금지.
8. // TODO, /* 생략 */ 금지 — 끝까지 완성한다.

[❓ 역질문 유도]
Q1. 달력 범위는 무엇으로 할까? (학기 6개월 / 1년 전체)
Q2. 절기 카드 톤은? (파스텔 자연 색 / 풍경 일러스트 느낌)
Q3. 음력 표시도 함께 보여줄까? (음력 양력 나란히 / 절기만)

🎯 에디터 한줄평

'입춘·한로·동지'가 종이 달력의 작은 글자였다면, 데이터가 되는 순간부터는 계산할 수 있는 하늘의 약속입니다. '가까운 절기 찾기'와 D-day 계산이 사회·과학·수학을 자연스럽게 잇는 최고의 다리 역할을 합니다. 특히 두 모드(실시간/심기)를 상수 하나로 전환하는 설계는 학내망 환경의 정답입니다.

📚 기술·교육 참고 링크

By 시간: