날씨 예보

엔드포인트 요약

메서드	경로	설명	인증 필요
GET	`/weather/live`	실황(현재 시각) 기상 데이터	❌
GET	`/weather/ForecastData`	초단기·단기·중기 전체 예보	❌
GET	`/weather/summary`	현재 관측 적합도 요약	❌

실황 날씨 조회

GET /weather/live?lat={위도}&lon={경도}

현재 시각의 실황 기상 데이터를 반환합니다. 매 10분마다 갱신되며 서버 기동 시 즉시 로드됩니다.

응답

{
  "success": true,
  "message": "OK",
  "data": {
    "t1h": 18,
    "vec": 225,
    "wsd": 2.5,
    "pty": 0,
    "rn1": 0.0,
    "reh": 60,
    "sky": 1,
    "suitability": 85
  }
}

필드	타입	설명
`t1h`	Int?	기온 (°C)
`vec`	Int?	풍향 (degree)
`wsd`	Float?	풍속 (m/s)
`pty`	Int?	강수형태 (0: 없음, 1: 비, 2: 비/눈, 3: 눈)
`rn1`	Float?	1시간 강수량 (mm)
`reh`	Int?	습도 (%)
`sky`	Int?	하늘상태 (1: 맑음, 2: 구름조금, 3: 구름많음, 4: 흐림)
`suitability`	Int	관측 적합도 (0~100)

전체 예보 조회

GET /weather/ForecastData?lat={위도}&lon={경도}

한국 내 좌표만 지원합니다. 범위를 벗어나면 400 오류를 반환합니다.

응답 구조

{
  "ultraForecastResponse": [ ... ],
  "shortForecastResponse": [ ... ],
  "midCombinedForecastDTO": [ ... ]
}

초단기 예보 (`ultraForecastResponse`)

현재 시각 기준 약 6시간 이내, 10분 단위 갱신 데이터입니다.

{
  "tmef": "202504261030",
  "t1h": 18,
  "vec": 225,
  "wsd": 2.5,
  "pty": 0,
  "rn1": 0.0,
  "reh": 60,
  "sky": 1,
  "suitability": 85
}

필드	타입	설명
`tmef`	String	예보 시각 (`yyyyMMddHHmm`)
`t1h`	Int?	기온 (°C)
`vec`	Int?	풍향 (degree)
`wsd`	Float?	풍속 (m/s)
`pty`	Int?	강수형태 (0: 없음, 1: 비, 2: 비/눈, 3: 눈)
`rn1`	Float?	1시간 강수량 (mm)
`reh`	Int?	습도 (%)
`sky`	Int?	하늘상태 (1: 맑음, 2: 구름조금, 3: 구름많음, 4: 흐림)
`suitability`	Int	관측 적합도 (0~100)

단기 예보 (`shortForecastResponse`)

3일치 예보, 3시간 단위 갱신 데이터입니다.

{
  "tmef": "202504271200",
  "tmp": 20,
  "tmx": 24,
  "tmn": 14,
  "vec": 180.0,
  "wsd": 1.8,
  "sky": 2,
  "pty": 0,
  "pop": 10,
  "pcp": 0.0,
  "sno": null,
  "reh": 55,
  "suitability": 78
}

필드	타입	설명
`tmef`	String	예보 시각 (`yyyyMMddHHmm`)
`tmp`	Int?	기온 (°C)
`tmx`	Int?	최고 기온 (°C)
`tmn`	Int?	최저 기온 (°C)
`vec`	Float?	풍향 (degree)
`wsd`	Float?	풍속 (m/s)
`sky`	Int?	하늘상태 (1~4)
`pty`	Int?	강수형태
`pop`	Int?	강수확률 (%)
`pcp`	Float?	강수량 (mm)
`sno`	Float?	적설량 (cm)
`reh`	Int?	습도 (%)
`suitability`	Int	관측 적합도 (0~100)

중기 예보 (`midCombinedForecastDTO`)

7~10일치 예보, 하루 2회(06:10 / 18:10) 갱신 데이터입니다.

{
  "tmFc": "202504260600",
  "tmEf": "202504290000",
  "doRegId": "11B00000",
  "siRegId": "11B10101",
  "sky": "WB01",
  "pre": "WB00",
  "rnSt": 10,
  "min": 13,
  "max": 23,
  "suitability": 72
}

필드	타입	설명
`tmFc`	String	발표 시각
`tmEf`	String	예보 시각
`sky`	String?	하늘상태 코드 (WB01: 맑음, WB02: 구름조금, WB03: 구름많음, WB04: 흐림)
`pre`	String?	강수 코드 (WB00: 없음, WB09: 비, WB11: 비/눈, WB12: 눈, WB13: 눈/비)
`rnSt`	Int?	강수확률 (%)
`min`	Int?	최저 기온 (°C)
`max`	Int?	최고 기온 (°C)
`suitability`	Int	관측 적합도 (0~100)

관측 적합도 요약

GET /weather/summary?lat={위도}&lon={경도}

현재 시각 기준 가장 가까운 예보 시간대를 기반으로 요약 정보를 반환합니다.

응답

{
  "success": true,
  "message": "OK",
  "data": {
    "suitability": 85,
    "sky": "맑음",
    "temperature": 18,
    "nextGoodTime": "202504271000"
  }
}

필드	타입	설명
`suitability`	Int	현재 관측 적합도 (0~100)
`sky`	String	하늘 상태 텍스트 (맑음 / 구름조금 / 구름많음 / 흐림 / 정보없음)
`temperature`	Int?	현재 기온 (°C)
`nextGoodTime`	String?	다음 관측 적합 시각 (`yyyyMMddHHmm`), 없으면 `null`

suitability 70점 이상이면 관측 적합으로 판정합니다.

관측 적합도 산출 방식

6개 요소를 가중 합산해 0~100점으로 환산합니다.

요소	초단기	단기	중기
하늘 상태	65%	55%	50%
강수	20%	25%	30%
바람	10%	8%	0%
습도	5%	6%	0%
달 위상	0%	5%	15%
광공해	0%	1%	5%

달 위상: 달 고도 0° 이상이고 보름달에 가까울수록 페널티 적용
광공해: 전국 5km 격자 데이터(light_pollution_korea_5km_grid.csv) 기반
중기는 바람·습도 데이터 신뢰도가 낮아 해당 항목 가중치를 0으로 설정

데이터 갱신 주기

예보 종류	갱신 주기	비고
실황	매 10분	서버 시작 시 즉시 로드
초단기	매 10분	서버 시작 시 즉시 로드
단기	3시간 (02:15 기준)	서버 시작 시 즉시 로드
중기	06:10 / 18:10	기상청 중기 예보 발표 주기

API 호출 실패 시 설정된 횟수만큼 자동 재시도합니다.

API 직접 테스트

실황 날씨 조회

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Query Parameters

lat*number

Formatdouble

lon*number

Formatdouble

Response Body

`/`

curl -X GET "https://byeoldori-server-hbxnfn4woa-du.a.run.app/weather/live?lat=0.1&lon=0.1"

{
  "success": true,
  "message": "string",
  "data": {
    "t1h": 0,
    "vec": 0,
    "wsd": 0.1,
    "pty": 0,
    "rn1": 0.1,
    "reh": 0,
    "sky": 0,
    "suitability": 0
  }
}

Get Forecast Data

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Query Parameters

lat*number

Formatdouble

lon*number

Formatdouble

Response Body

`/`

curl -X GET "https://byeoldori-server-hbxnfn4woa-du.a.run.app/weather/ForecastData?lat=0.1&lon=0.1"

{
  "ultraForecastResponse": [
    {
      "tmef": "string",
      "t1h": 0,
      "vec": 0,
      "wsd": 0.1,
      "pty": 0,
      "rn1": 0.1,
      "reh": 0,
      "sky": 0,
      "suitability": 0
    }
  ],
  "shortForecastResponse": [
    {
      "tmef": "string",
      "tmp": 0,
      "tmx": 0,
      "tmn": 0,
      "vec": 0.1,
      "wsd": 0.1,
      "sky": 0,
      "pty": 0,
      "pop": 0,
      "pcp": 0.1,
      "sno": 0.1,
      "reh": 0,
      "suitability": 0
    }
  ],
  "midCombinedForecastDTO": [
    {
      "tmFc": "string",
      "tmEf": "string",
      "doRegId": "string",
      "siRegId": "string",
      "sky": "string",
      "pre": "string",
      "rnSt": 0,
      "min": 0,
      "max": 0,
      "suitability": 0
    }
  ]
}

날씨 예보 요약

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Query Parameters

lat*number

Formatdouble

lon*number

Formatdouble

Response Body

`/`

curl -X GET "https://byeoldori-server-hbxnfn4woa-du.a.run.app/weather/summary?lat=0.1&lon=0.1"

{
  "success": true,
  "message": "string",
  "data": {
    "suitability": 0,
    "sky": "string",
    "temperature": 0,
    "nextGoodTime": "string"
  }
}

날씨 예보

200*/*

200*/*

200*/*

On this page

`/`

`/`

`/`