베스트트랙은 태풍 종료 후, 예보 현업 상황에서 실시간으로 활용하지 못했던 관측 자료들을 수집하여 충분한 시간을 거쳐 정밀 재분석하여 생산한 최적의 태풍정보입니다. 태풍 분석 정보의 불확실성을 최소화하고, 모든 가용 데이터를 종합하여 도출한 '태풍 분석의 결정체'라 할 수 있습니다.

베스트트랙은 태풍 종료 후 다음과 같은 절차를 통해 생산되고, 확정됩니다.

태풍의 위치(위‧경도), 중심기압, 최대풍속, 강도 등급, 강풍반경, 폭풍반경 정보를 포함합니다.

• 기상청 누리집(https://www.kma.go.kr/kma/): 알림‧자료 > 기상간행물 > 국가태풍센터 간행물 > 베스트트랙

• 기상청 API허브(https://apihub.kma.go.kr/): 태풍 > 태풍 베스트트랙

• IBTrACS(International Best Track Archive for Climate Stewardship)

소스코드 : typhoon_besttrack_example.py

태풍 베스트트랙 자료를 조회하고 태풍 중심 위치 및 강풍반경을 시각화하기 위해 필요한 라이브러리를 설치합니다.

pip install requests pandas matplotlib cartopy numpy

import os
from datetime import datetime
 
import numpy as np
import requests
import pandas as pd
 
import matplotlib
matplotlib.use("Agg")
import matplotlib.pyplot as plt
from matplotlib import font_manager
from matplotlib.lines import Line2D
from matplotlib.patches import Patch
 
import cartopy.crs as ccrs
import cartopy.feature as cfeature
from cartopy.geodesic import Geodesic

API 인증키와 API 주소, 조회할 태풍 정보를 설정합니다.

AUTH_KEY = "본인의_API_인증키"
 
BASE_URL = "https://apihub.kma.go.kr/api/typ01/url/typ_besttrack.php"
 
YEAR = 2023
TCID = "2311"
TY_NAME = f"Typhoon {TCID}"
 
HELP = 1
 
RAW_TEXT_FILE = f"typhoon_besttrack_{YEAR}_{TCID}_raw.txt"
OUTPUT_CSV = f"typhoon_besttrack_{YEAR}_{TCID}.csv"
OUTPUT_PNG = f"typhoon_besttrack_map_{YEAR}_{TCID}.png"

BASE_URL은 (신)기상자료개방포털 > API > 태풍 > 태풍 베스트트랙메뉴의 호출 URL을 사용합니다.

YEAR에는 태풍 발생 연도를 입력합니다.

TCID에는 태풍 번호를 입력합니다.

예를 들어 2023년 11호 태풍은 2311로 입력합니다.

태풍 베스트트랙 API를 호출하여 응답 원문 TEXT를 받아옵니다.

def fetch_besttrack_text(year, tcid):
    params = {
        "year": year,
        "tcid": tcid,
        "help": HELP,
        "authKey": AUTH_KEY,
    }
 
    response = requests.get(BASE_URL, params=params, timeout=60)
    response.raise_for_status()
 
    text = response.text
 
    with open(RAW_TEXT_FILE, "w", encoding="utf-8") as f:
        f.write(text)
 
    return text

API 응답에는 설명 줄과 실제 데이터 줄이 함께 포함됩니다.

설명 줄은 #으로 시작하므로 제외하고 실제 데이터 줄만 사용합니다.

def extract_data_lines(text):
    lines = []
 
    for raw_line in text.splitlines():
        line = raw_line.strip()
 
        if not line:
            continue
 
        if line.startswith("#"):
            continue
 
        lines.append(line)
 
    return lines

베스트트랙 응답 자료의 컬럼은 다음과 같습니다.

COLS = [
    "GRADE",
    "TYNO",
    "YY",
    "MM",
    "DD",
    "HH",
    "LON",
    "LAT",
    "MAX_WS",
    "PRES",
    "R15",
    "R25",
]

응답 텍스트를 pandas DataFrame으로 변환합니다.

def parse_besttrack_text(text):
    data_lines = extract_data_lines(text)
 
    rows = []
 
    for line in data_lines:
        clean = line.replace(",", " ")
        parts = [p for p in clean.split() if p]
 
        if len(parts) < 12:
            continue
 
        rows.append(parts[:12])
 
    df = pd.DataFrame(rows, columns=COLS)
    return df

숫자형 컬럼과 시간 컬럼을 변환하고 결측값을 처리합니다.

def clean_besttrack_df(df):
    numeric_cols = [
        "TYNO", "YY", "MM", "DD", "HH",
        "LON", "LAT", "MAX_WS",
        "PRES", "R15", "R25"
    ]
 
    for col in numeric_cols:
        df[col] = pd.to_numeric(df[col], errors="coerce")
 
    for col in ["MAX_WS", "PRES", "R15", "R25"]:
        df.loc[df[col] <= -9, col] = pd.NA
 
    if df["YY"].dropna().max() < 100:
        df["YYYY"] = df["YY"].apply(
            lambda x: int(2000 + x) if pd.notna(x) else pd.NA
        )
    else:
        df["YYYY"] = df["YY"]
 
    def make_dt(row):
        try:
            return datetime(
                int(row["YYYY"]),
                int(row["MM"]),
                int(row["DD"]),
                int(row["HH"])
            )
        except Exception:
            return pd.NaT
 
    df["datetime"] = df.apply(make_dt, axis=1)
 
    df = df.dropna(subset=["LAT", "LON"]).copy()
 
    df = df.sort_values("datetime").reset_index(drop=True)
 
    return df

지도 표출을 위한 기본 지도를 생성합니다.

def setup_map():
    fig = plt.figure(figsize=(12, 10))
    ax = plt.axes(projection=ccrs.PlateCarree())
 
    ax.add_feature(cfeature.LAND, facecolor="#f2f2f2")
    ax.add_feature(cfeature.OCEAN, facecolor="#e6f2ff")
    ax.add_feature(cfeature.COASTLINE, linewidth=0.8)
    ax.add_feature(cfeature.BORDERS, linewidth=0.5)
 
    ax.gridlines(
        draw_labels=True,
        linewidth=0.4,
        linestyle="--",
        alpha=0.5
    )
 
    return fig, ax

태풍 중심 위치를 선과 점으로 연결하여 태풍 경로를 표출합니다.

ax.plot(
    df["LON"],
    df["LAT"],
    color="black",
    linewidth=1.5,
    linestyle="-",
    transform=ccrs.PlateCarree()
)
 
ax.scatter(
    df["LON"],
    df["LAT"],
    s=30,
    color="royalblue",
    edgecolors="black",
    linewidths=0.3,
    transform=ccrs.PlateCarree()
)

15m/s 및 25m/s 풍속반경을 원 형태로 표출합니다.

draw_wind_radius(
    ax=ax,
    lon=row["LON"],
    lat=row["LAT"],
    radius_value=row["R15"],
    edgecolor="orange",
    facecolor="gold",
    alpha=0.10,
    linewidth=0.8
)
 
draw_wind_radius(
    ax=ax,
    lon=row["LON"],
    lat=row["LAT"],
    radius_value=row["R25"],
    edgecolor="red",
    facecolor="red",
    alpha=0.06,
    linewidth=1.0
)

태풍 생성 지점, 소멸 지점, 최대세력 지점을 함께 표시합니다.

ax.scatter(
    first_row["LON"],
    first_row["LAT"],
    s=120,
    color="limegreen",
    edgecolors="black",
    marker="o"
)
 
ax.scatter(
    last_row["LON"],
    last_row["LAT"],
    s=120,
    color="black",
    edgecolors="white",
    marker="X"
)
 
ax.scatter(
    peak_row["LON"],
    peak_row["LAT"],
    s=180,
    color="magenta",
    edgecolors="black",
    marker="*"
)

최종 태풍 경로 지도는 PNG 파일로 저장합니다.

plt.savefig(
    OUTPUT_PNG,
    dpi=150,
    bbox_inches="tight"
)

전체 실행 코드는 다음과 같습니다.

text = fetch_besttrack_text(YEAR, TCID)
 
df = parse_besttrack_text(text)
 
df = clean_besttrack_df(df)
 
df.to_csv(
    OUTPUT_CSV,
    index=False,
    encoding="utf-8-sig"
)
 
plot_typhoon_track(df)

실행하면 다음 파일이 생성됩니다.