v1.0

실측 정확도로 가중한
다중모델 앙상블 예보 API
A multi-model ensemble forecast API,
weighted by measured skill

GFS · GEFS · ECMWF 의 과거 예보를 실제 관측과 대조해 변수 · 리드타임 · 지역 · 계절별 정확도를 측정하고, 그 정확도로 계산한 최적가중(NNLS)으로 새 예보를 결합합니다. 단순 평균보다 홀드아웃 기준 평균 6.8% 정확했습니다. We score three global models against actual observations by variable, lead time, region and season, then blend today's forecasts with the optimal (NNLS) weights those scores imply — on held-out data, 6.8% better than a plain average.

1,546,316검증 비교 건수 (2023–2026)verified comparisons (2023–2026)
98.1%등가중 대비 우세한 조합 비율of cases beat equal weighting
0–168h12시간 간격 15개 리드타임15 lead times, 12-hour steps
6 vars · 4 regions기온 · 기압 · 바람 · 고도temperature, pressure, wind, height
이 API 가 특별한 이유. 대부분의 예보 API 는 한 기관의 모델을 그대로 전달합니다. 여기서는 어떤 모델이 언제 얼마나 틀리는지를 먼저 측정하고, 그 측정값으로 결합합니다. 정확도 자체도 /accuracy 로 조회할 수 있습니다. What makes this different. Most forecast APIs relay one provider's model. Here we first measure how wrong each model is, and when, and blend accordingly. The measured skill itself is queryable via /accuracy.

빠른 시작Quick start

1. 아래 키 신청으로 API 키를 받습니다 (무료 티어 즉시 발급). 2. 모든 요청에 X-API-Key 헤더를 넣습니다. 3. 아래 예제를 그대로 실행합니다. 1. Request a key below (free tier, issued on request). 2. Send it in the X-API-Key header on every call. 3. Run the example below as-is.

curl -s "https://mme.bluematrix.center/forecast/point?lat=37.5&lon=127&var=t2m" \
  -H "X-API-Key: mme_YOUR_KEY"

인증Authentication

세 가지 방식 중 하나로 키를 전달합니다. 헤더 방식을 권장합니다 — 쿼리스트링은 서버 로그와 브라우저 히스토리에 그대로 남습니다. Pass the key in one of three ways. Prefer the header — query strings end up in server logs and browser history.

방식Method예시Example
HTTP headerX-API-Key: mme_...권장Recommended
Bearer tokenAuthorization: Bearer mme_...표준 클라이언트 호환For standard clients
Query string?api_key=mme_...테스트용만 — 로그에 남습니다Testing only — leaks into logs

/, /health, /meta, /docs, /openapi.json 은 키 없이 열려 있습니다. /, /health, /meta, /docs and /openapi.json need no key.

엔드포인트Endpoint reference

Base URL https://mme.bluematrix.center  ·  모든 응답은 JSON · UTF-8. 목록형 응답은 {"n":건수,"rows":[...]} 형태입니다. All responses are JSON/UTF-8. List responses use {"n":count,"rows":[...]}.

GET/forecast/point지점 예보 시계열Point forecast series

위·경도 한 지점의 결합 예보를 리드타임 순서로 돌려줍니다. 격자값을 이중선형 보간합니다. Blended forecast for one location, ordered by lead time. Grid values are bilinearly interpolated.

paramtype설명Description
latfloat, 필수required-90 ~ 90
lonfloat, 필수required-180 ~ 360
varstring생략 시 전 변수omit for all variables
{
  "lat": 37.5, "lon": 127.0,
  "init": "2026-08-21 00:00:00",
  "method": "nnls",
  "models": "gfs,gefs,ecmwf",
  "grid_deg": 1.5,
  "lead_h": [0, 12, 24, 36, 48, 60, 72, 84, 96, 108, 120, 132, 144, 156, 168],
  "series": { "t2m": [296.974, 296.265, 297.043, ...] }
}
GET/forecast/latest최신 예보 메타Latest run metadata

현재 서비스 중인 예보의 초기시각 · 사용 모델 · 격자 · 변수 목록. 파라미터 없음. 폴링 주기를 정할 때 attrs.init 을 기준으로 삼으세요. Init time, models used, grid and variable list for the run currently being served. No parameters. Poll against attrs.init to detect a new run.

GET/accuracy모델별 실측 정확도Measured model skill

각 모델이 실제로 얼마나 틀렸는지 (RMSE · MAE · 편차). 이 값이 가중치의 근거입니다. How wrong each model actually was (RMSE, MAE, bias). These numbers drive the weights.

param허용값Accepted
modelgfs · gefs · ecmwf · ecmwf04
vart2m · t850 · msl · u10 · v10 · z500
regionglobal · nh · wp · korea
seasonALL · DJF · MAM · JJA · SON  (기본default ALL)
lead_h0, 12, 24, … 168
{"n": 1, "rows": [
  {"model":"ecmwf","var":"t2m","lead_h":24,"region":"korea","season":"ALL",
   "rmse":1.4812,"mae":1.1233,"bias":-0.0871,"n_init":835}
]}
GET/weights학습된 결합 가중치Learned blend weights

다섯 가지 결합 방식의 가중치와 모델별 편차 보정값. 실제 예보에는 w_nnls_* 가 쓰입니다. Weights for five blending schemes plus per-model bias corrections. Production uses w_nnls_*.

var · region · season · lead_h 로 필터링합니다.filter the result.

{"n": 1, "rows": [
  {"var":"t2m","lead_h":0,"region":"korea","season":"JJA","n_train":184,
   "w_eq_gfs":0.33333, "w_inv_gfs":0.31837,
   "w_nnls_gfs":0.0, "w_nnls_gefs":0.49878, "w_nnls_ecmwf":0.50122,
   "bias_gfs":-0.36311, "bias_gefs":-0.37438, "bias_ecmwf":-0.13166}
]}
GET/eval홀드아웃 성능 비교Held-out benchmark

학습에 쓰지 않은 기간에서 다섯 방식의 RMSE 를 비교합니다. rmse_eq(단순평균) 대비 rmse_nnls 가 이 서비스의 실효 개선폭입니다. rmse_best(그 조합의 최고 단일모델)가 종종 단순평균보다 나쁘다는 점이 결합의 근거입니다. RMSE of the five schemes on data never used for fitting. rmse_nnls versus rmse_eq is the real gain. That rmse_best — the single best model for that cell — is often worse than a plain average is precisely why blending pays.

{"n": 1, "rows": [
  {"var":"t2m","lead_h":0,"region":"korea","season":"DJF","n_eval":59,
   "rmse_eq":0.86329,"rmse_inv":0.86183,"rmse_nnls":0.85630,
   "rmse_shrink":0.85477,"rmse_best":0.99328}
]}
GET/climatology기후값 기준선Climatological baseline

"예보 없이 평년값만 쓰면 얼마나 틀리는가". 예보의 가치를 재는 기준선입니다. var · region 으로 필터링합니다. How wrong you would be using the seasonal normal alone — the baseline against which forecast value is measured. Filter by var and region.

GET/coverage원자료 수집 커버리지Source data coverage

모델 · 연도별로 실제 확보된 초기시각 비율. 정확도 수치를 인용할 때 표본 충실도를 함께 확인하세요. Share of init cycles actually retrieved, per model and year. Check this alongside any skill figure you cite.

GET/meta사전 · 파라미터 목록Dictionary

모델 · 변수 · 단위 · 한글 라벨 · 지역 · 리드타임 · 계절 · 기간. 키 불필요. 클라이언트의 드롭다운은 하드코딩하지 말고 여기서 받아 채우세요. Models, variables, units, labels, regions, leads, seasons, period. No key required. Populate client dropdowns from here rather than hard-coding them.

GET/usage내 쿼터 · 사용량Your quota
{"tier":"free","per_min":30,"per_day":1000,
 "used_today":142,"remaining_today":858,"date_utc":"2026-08-22",
 "key_id":"k_3f9c1a20","org":"Example Corp"}
GET/health서비스 상태Service status

키 불필요. 모니터링에 사용하세요.No key required. Use for monitoring.

{"ok":true,"catalogue":true,"weights":true,"forecasts":1,"served":"..."}

요금 · 제한Tiers & limits

티어Tier분당Per minute일별Per day대상For
Free301,000평가 · 개인 프로젝트 · 시제품Evaluation, side projects, prototypes
Partner30050,000상용 서비스 — 개별 협의Production use — by arrangement

일별 한도는 UTC 00:00 에 초기화됩니다. 모든 응답에 잔여량 헤더가 붙습니다: X-RateLimit-Remaining-Minute, X-RateLimit-Remaining-Day, X-RateLimit-Reset(초). Daily counters reset at 00:00 UTC. Every response carries X-RateLimit-Remaining-Minute, X-RateLimit-Remaining-Day and X-RateLimit-Reset (seconds).

권장 사용 패턴. 예보는 하루 한 번(00Z) 갱신됩니다. 매 요청마다 호출하지 말고 /forecast/latestattrs.init 이 바뀔 때만 다시 받아 캐시하세요. 정확도 · 가중치 데이터는 분기 단위로만 바뀌므로 로컬 캐시가 맞습니다. How to use this well. Forecasts refresh once a day (00Z). Don't call per user request — re-fetch only when attrs.init from /forecast/latest changes, and cache. Skill and weight tables change quarterly at most; cache them locally.

에러Errors

HTTPerror원인 · 조치Cause & fix
400알 수 없는 변수/지역명. /meta 로 허용값 확인Unknown variable or region — check /meta
401missing_api_key키가 없습니다No key sent
403invalid_api_key등록되지 않았거나 폐기된 키Unknown or revoked key
429rate_limit_exceeded분당 한도 초과. Retry-After 초 후 재시도Per-minute limit — wait Retry-After seconds
429daily_quota_exceeded일 한도 초과. UTC 자정 초기화Daily quota — resets at 00:00 UTC
503카탈로그/예보 적재 전. 잠시 후 재시도Catalogue or forecast not loaded yet — retry shortly
{"error":"rate_limit_exceeded",
 "message":"Too many requests per minute.",
 "message_ko":"분당 호출 한도를 넘었습니다.",
 "docs":"https://mme.bluematrix.center/"}

데이터와 방법Data & method

예보 원자료Forecast sourcesNOAA GFS · GEFS (public domain), ECMWF Open Data (CC BY 4.0)
검증 기준Verification truth각 초기시각의 리드 0 해석장Lead-0 analysis of each cycle
기간Period2023-01-01 ~ 2026-08-13
가중 방식Weighting오차 공분산 기반 NNLS 최적결합 (w ≥ 0, Σw = 1), 편차 보정 포함NNLS optimal combination on the error covariance (w ≥ 0, Σw = 1), with bias correction
검증 설계Validation학습 2024–2025 / 평가 2026 홀드아웃, 위도 가중Train 2024–2025, score 2026 held out; latitude-weighted
갱신Refresh예보 매일 1회(00Z) · 가중치 분기Forecast daily (00Z); weights quarterly
고지. 본 서비스는 공개 수치예보 자료를 재가공한 것으로, 기상청 등 공식 기관의 특보 · 경보를 대체하지 않습니다. 인명 · 재산이 걸린 판단에는 공식 예보를 사용하십시오. 원자료 라이선스(ECMWF CC BY 4.0)에 따라 출처를 표기해야 합니다. Notice. This service reprocesses public NWP output and does not replace official warnings from national meteorological services. Use official forecasts for decisions involving life or property. Attribution is required under the source licence (ECMWF CC BY 4.0).

키 신청Request a key

아래 내용을 적어 메일 주시면 무료 티어 키를 발급합니다. Email the following and we will issue a free-tier key.

회사/팀Organisation이름과 연락처Name and contact
용도Use case한두 문장이면 충분합니다One or two sentences is enough
예상 호출량Expected volume일 단위 추정치 — 티어 판단용Rough calls per day — decides the tier

leokim7@gmail.com