🌤️ 디지털 사이니지 날씨 위젯 개발기: 무료 API의 함정부터 기상청 API 허브 정착까지

디지털 사이니지 솔루션의 클라이언트와 프론트엔드를 개발하다 보면, 고객사 화면 한구석을 차지하는 '날씨 위젯'을 구현해야 할 때가 반드시 온다.

단순히 기온과 맑음/흐림 아이콘만 띄우면 되는 간단한 작업처럼 보이지만, 막상 실무에 적용하려고 하면 라이선스, API 호출 제한, 데이터 정확도 등 고려해야 할 산이 한두 개가 아니다.

이번 포스팅에서는 해외 무료 API에서 시작해 기상청 API 허브에 정착하기까지의 좌충우돌 트러블슈팅 과정과 핵심 알고리즘을 정리해 본다.

1. 첫 번째 시도: Open-Meteo와 로컬스토리지 캐싱의 조합

초기 프로토타입은 Open-Meteo API를 활용해 구현했다. 별도의 키 발급 없이 위경도만 던지면 즉시 날씨 데이터를 반환해 주기 때문에 개발 초기 단계에서는 이만한 녀석이 없었다.

사이니지 특성상 디스플레이가 24시간 켜져 있으므로, API 일일 호출 제한(Free Tier)을 방어하는 것이 핵심이었다.

• 해결책: localStorage를 활용해 한 번 받아온 날씨 데이터를 55분간 캐싱하도록 설계했다. (자동 갱신 인터벌은 60분으로 설정하여, 캐시 만료 직후 자연스럽게 새 데이터를 호출하도록 타이머를 맞췄다.)

성능도 응답 속도도 완벽했다. 하지만 진짜 문제는 코드 밖, **'라이선스'**에 있었다.

2. 상업적 이용의 벽: 무료 API는 진짜 무료가 아니다

클라이언트에게 납품하는 상업용(B2B) 서비스에 Open-Meteo의 무료 엔드포인트를 그대로 쓰는 것이 법적으로 문제가 없는지 검토해 보았다. 결론은 **'절대 불가'**였다.

대부분의 해외 무료 날씨 API는 개인 프로젝트나 비상업적 용도에 한해서만 무료 트래픽을 열어둔다. 출처(CC BY 4.0)를 화면에 명시하더라도, 상업용 서비스에서 무료 서버로 계속 요청을 보내면 약관 위반으로 어느 날 갑자기 IP가 영구 차단될 리스크가 컸다. 결국 라이선스 이슈에서 100% 자유롭고 상업적 이용이 허용되는 기상청 공공데이터로 방향을 틀어야 했다.

3. 기상청 API 도입기: "returnReasonCode: 12"의 늪

안전한 대한민국 기상청 데이터를 쓰기로 하고 API 연동을 시도했다. 위경도를 기상청 전용 '격자 좌표(nx, ny)'로 변환하는 공식까지 적용하여 완벽하게 준비했다고 생각했지만, 돌아온 것은 차가운 에러 메시지였다.

returnReasonCode: "12" (해당 오픈API 서비스가 없거나 폐기됨)

원인을 분석하는 과정에서 **공공데이터포털(data.go.kr)**과 **기상청 API 허브(apihub.kma.go.kr)**를 혼동하고 있었다는 사실을 발견했다. 기상청 데이터를 제공한다는 점은 같지만, 두 곳은 발급하는 키의 종류(serviceKey vs authKey)와 엔드포인트 주소가 완전히 달랐던 것이다.

4. 치명적인 발견: '실황' 데이터에는 하늘이 없다?

문서를 파고들며 가장 크게 깨달은 아키텍처적 이슈가 하나 더 있었다. 처음에 구현하려 했던 기상청의 '초단기실황(getUltraSrtNcst)' API에는 아주 치명적인 단점이 존재했다.

• 실황 데이터에는 기온, 습도, 풍속, 강수 형태(비/눈)는 있지만, 가장 중요한 '하늘 상태(SKY - 맑음/구름많음/흐림)' 데이터가 아예 존재하지 않았다.

비가 오지 않을 때 사이니지 화면에 해(☀️)를 띄워야 할지, 구름(☁️)을 띄워야 할지 알 길이 없는 것이다. AWS(자동기상관측장비)는 기계적으로 수치만 잴 뿐, 하늘에 구름이 얼마나 꼈는지 관측하지 않기 때문이다.

5. 최종 해결책: '초단기예보'로의 선회와 API 허브 정착

결국 하늘 상태(SKY)와 강수 형태(PTY)를 조합하여 날씨 아이콘을 정확하게 렌더링하기 위해, 실황이 아닌 '초단기예보(getUltraSrtFcst)' API를 사용하기로 결정했다.

최종적으로 구축한 파이프라인은 다음과 같다.

1. 플랫폼: 공식 문서가 잘 갖춰진 **기상청 API 허브(apihub.kma.go.kr)**의 단기예보 조회서비스(2.0)를 사용.
2. 데이터: 초단기예보조회(getUltraSrtFcst)를 호출하여 맑음/흐림 데이터를 확보.
3. 호출 최적화: 초단기예보가 업데이트되는 '매시 45분' 규칙에 맞춰 시스템 시간을 계산하여 요청.
4. 아이콘 렌더링 로직: 강수가 있을 때는 비/눈 아이콘을 우선하고, 강수가 없을 때만 하늘 상태(SKY) 코드를 참조하여 해나 구름을 띄우는 분기 로직 적용.

6. 날씨 위젯 핵심 알고리즘 (Pseudo-code)

구체적인 언어에 종속되지 않도록, 전체적인 논리 흐름과 데이터 파이프라인을 수도 코드(Pseudo-code)로 정리해 두었다. 프론트엔드뿐만 아니라 백엔드로 로직을 이관할 때도 유용하게 쓰일 수 있다.

6.1. 메인 라이프사이클 (Main Lifecycle)

ALGORITHM WeatherPlayer_Run:
  // 1. UI 렌더링 준비
  IF Target_DOM is NOT found:
    PRINT "DOM 오류: 렌더링 중단"
    EXIT

  // 2. 초기 1회 즉시 실행
  CALL Update_Weather_Flow()

  // 3. 주기적 실행 (타이머)
  START Timer(Interval: 60 minutes) DO:
    CALL Update_Weather_Flow()

6.2. 날씨 업데이트 흐름 (Update Flow)

ALGORITHM Update_Weather_Flow:
  // 1. 좌표 변환 (WGS84 -> 기상청 격자)
  (nx, ny) = CALL Convert_LatLon_To_Grid(User_Lat, User_Lon)

  // 2. 데이터 취득 (캐시 OR API)
  WeatherData = CALL Fetch_Weather_Data(nx, ny)

  // 3. 화면 렌더링
  IF WeatherData is valid:
    CALL Render_Weather_UI(WeatherData)

6.3. 데이터 취득 및 캐싱 (Fetch & Cache)

ALGORITHM Fetch_Weather_Data(nx, ny):
  CacheKey = "KMA_API_" + nx + "_" + ny
  CurrentTime = Get_Current_Time()
  CacheTTL = 55 minutes

  // 1. 로컬 캐시 확인
  IF Cache_Exists(CacheKey):
    CacheData = Load_Cache(CacheKey)
    IF (CurrentTime - CacheData.SavedTime) < CacheTTL:
      RETURN CacheData.Data  // API 호출 없이 캐시 반환

  // 2. 캐시가 없거나 만료되었다면 API 호출 준비
  (BaseDate, BaseTime) = CALL Calculate_KMA_Time(CurrentTime)

  // 3. 기상청 API 허브 호출
  Response = HTTP_GET(
    URL: "[https://apihub.kma.go.kr/.../getUltraSrtFcst](https://apihub.kma.go.kr/.../getUltraSrtFcst)",
    Params: AuthKey, BaseDate, BaseTime, nx, ny, dataType="JSON"
  )

  // 4. 응답 파싱 및 추출 (가장 가까운 시간대의 예보만 픽업)
  ParsedResult = {}
  FOR EACH item IN Response.Items:
    // T1H, SKY, PTY 등 동일한 카테고리가 아직 없으면 첫 번째 값(최신) 저장
    IF item.category IS NOT IN ParsedResult:
      ParsedResult[item.category] = item.fcstValue

  // 5. 새 데이터 캐싱
  SAVE_CACHE(CacheKey, Data: ParsedResult, SavedTime: CurrentTime)

  RETURN ParsedResult

6.4. 발표 시각 산출 (Time Calculation)

ALGORITHM Calculate_KMA_Time(CurrentTime):
  TargetTime = CurrentTime

  // 현재 시각이 매시 45분 이전이라면, 아직 최신 예보가 서버에 없음
  IF TargetTime.Minute < 45:
    TargetTime = TargetTime - 1 hour  // 이전 시간대로 롤백

  BaseDate = FORMAT(TargetTime, "YYYYMMDD")
  BaseTime = FORMAT(TargetTime, "HH") + "30" // 초단기예보는 무조건 분(minute)이 30분

  RETURN (BaseDate, BaseTime)

6.5. 화면 렌더링 및 아이콘 판별 (UI Rendering)

ALGORITHM Render_Weather_UI(Data):
  PTY = Data.PTY (강수형태)
  SKY = Data.SKY (하늘상태)
  Temp = Data.T1H (기온)

  // 1. 날씨 아이콘 판별
  SkyIcon = ""
  RainIcon = ""

  IF PTY > 0: // 비나 눈이 올 때
    SkyIcon = "☁️" // 비가 오면 기본적으로 하늘은 흐림
    IF PTY == 1 OR 4 OR 5: RainIcon = "☔" (비)
    IF PTY == 2 OR 6:      RainIcon = "🌧️❄️" (비/눈)
    IF PTY == 3 OR 7:      RainIcon = "❄️" (눈)
  ELSE: // 비가 안 올 때
    IF SKY == 1: SkyIcon = "☀️" (맑음)
    IF SKY == 3: SkyIcon = "🌤️" (구름많음)
    IF SKY == 4: SkyIcon = "☁️" (흐림)

  // 2. DOM 업데이트
  UPDATE_DOM(Element: SkyContainer, Value: SkyIcon)
  UPDATE_DOM(Element: RainContainer, Value: RainIcon)
  UPDATE_DOM(Element: TempContainer, Value: Temp + "°C")

💡 마무리하며

날씨 위젯 개발은 겉보기엔 간단하지만, 상업적 라이선스 검토, 위경도 좌표 변환, 기상 관측 시스템의 특성(실황 vs 예보)에 대한 이해가 모두 필요한 경험이였다.