Skip to content

async_typhoon_client

Async KMA Typhoon Information API client.

This module provides a client for accessing the Korea Meteorological Administration's Typhoon Information (태풍) API for tropical cyclone tracking and forecasting.

Typhoon information provides critical data on tropical cyclones including position, intensity, movement, and forecast tracks for disaster preparedness.

AsyncTyphoonClient

Async client for KMA Typhoon Information API.

The Typhoon Information system provides comprehensive data on tropical cyclones including current position, intensity, movement speed/direction, and forecast tracks for disaster preparedness.

Source code in python/src/kma_mcp/typhoon/async_typhoon_client.py 
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
class AsyncTyphoonClient:
    """Async client for KMA Typhoon Information API.

    The Typhoon Information system provides comprehensive data on
    tropical cyclones including current position, intensity, movement
    speed/direction, and forecast tracks for disaster preparedness.
    """

    BASE_URL = 'https://apihub.kma.go.kr/api/typ01/url'

    def __init__(self, auth_key: str, timeout: float = 30.0) -> None:
        """Initialize Typhoon Information client.

        Args:
            auth_key: KMA API authentication key
            timeout: Request timeout in seconds (default: 30.0)
        """
        self.auth_key = auth_key
        self.timeout = timeout
        self._client = httpx.AsyncClient(timeout=timeout)

    async def __aenter__(self) -> 'AsyncTyphoonClient':
        """Async context manager entry."""
        return self

    async def __aexit__(self, *args: object) -> None:
        """Async context manager exit."""
        await self.close()

    async def close(self) -> None:
        """Close the HTTP client."""
        await self._client.aclose()

    async def _make_request(self, endpoint: str, params: dict[str, Any]) -> dict[str, Any]:
        """Make HTTP request to Typhoon Information API.

        Args:
            endpoint: API endpoint path
            params: Query parameters

        Returns:
            API response as dictionary

        Raises:
            httpx.HTTPError: If request fails
        """
        params['authKey'] = self.auth_key
        url = f'{self.BASE_URL}/{endpoint}'
        response = await self._client.get(url, params=params)
        response.raise_for_status()
        return response.json()

    async def get_current_typhoons(self) -> dict[str, Any]:
        """Get information on currently active typhoons.

        Returns:
            Current active typhoon information

        Example:
            >>> async with AsyncTyphoonClient('your_auth_key')
            >>> ...     data = await client.get_current_typhoons()
        """
        params = {'help': '0'}
        return await self._make_request('kma_typ.php', params)

    async def get_typhoon_by_id(
        self,
        typhoon_id: str,
    ) -> dict[str, Any]:
        """Get detailed information for a specific typhoon.

        Args:
            typhoon_id: Typhoon identification number (e.g., '2501')

        Returns:
            Detailed typhoon information

        Example:
            >>> async with AsyncTyphoonClient('your_auth_key')
            >>> ...     data = await client.get_typhoon_by_id('2501')
        """
        params = {'typ_id': typhoon_id, 'help': '0'}
        return await self._make_request('kma_typ_dtl.php', params)

    async def get_typhoon_forecast(
        self,
        typhoon_id: str,
    ) -> dict[str, Any]:
        """Get forecast track for a specific typhoon.

        Args:
            typhoon_id: Typhoon identification number

        Returns:
            Typhoon forecast track data

        Example:
            >>> async with AsyncTyphoonClient('your_auth_key')
            >>> ...     data = await client.get_typhoon_forecast('2501')
        """
        params = {'typ_id': typhoon_id, 'help': '0'}
        return await self._make_request('kma_typ_fcst.php', params)

    async def get_typhoon_history(
        self,
        year: int | str,
    ) -> dict[str, Any]:
        """Get typhoon history for a specific year.

        Args:
            year: Year in 'YYYY' format

        Returns:
            Typhoon history data for the year

        Example:
            >>> async with AsyncTyphoonClient('your_auth_key')
            >>> ...     data = await client.get_typhoon_history(2024)
        """
        params = {'year': str(year), 'help': '0'}
        return await self._make_request('kma_typ_hist.php', params)

close() async

Close the HTTP client.

Source code in python/src/kma_mcp/typhoon/async_typhoon_client.py 
44
45
46
async def close(self) -> None:
    """Close the HTTP client."""
    await self._client.aclose()

get_current_typhoons() async

Get information on currently active typhoons.

Returns:

  • dict[str, Any] –

    Current active typhoon information

Example

async with AsyncTyphoonClient('your_auth_key') ... data = await client.get_current_typhoons()

Source code in python/src/kma_mcp/typhoon/async_typhoon_client.py 
67
68
69
70
71
72
73
74
75
76
77
78
async def get_current_typhoons(self) -> dict[str, Any]:
    """Get information on currently active typhoons.

    Returns:
        Current active typhoon information

    Example:
        >>> async with AsyncTyphoonClient('your_auth_key')
        >>> ...     data = await client.get_current_typhoons()
    """
    params = {'help': '0'}
    return await self._make_request('kma_typ.php', params)

get_typhoon_by_id(typhoon_id) async

Get detailed information for a specific typhoon.

Parameters:

  • typhoon_id (str) –

    Typhoon identification number (e.g., '2501')

Returns:

Example

async with AsyncTyphoonClient('your_auth_key') ... data = await client.get_typhoon_by_id('2501')

Source code in python/src/kma_mcp/typhoon/async_typhoon_client.py 
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
async def get_typhoon_by_id(
    self,
    typhoon_id: str,
) -> dict[str, Any]:
    """Get detailed information for a specific typhoon.

    Args:
        typhoon_id: Typhoon identification number (e.g., '2501')

    Returns:
        Detailed typhoon information

    Example:
        >>> async with AsyncTyphoonClient('your_auth_key')
        >>> ...     data = await client.get_typhoon_by_id('2501')
    """
    params = {'typ_id': typhoon_id, 'help': '0'}
    return await self._make_request('kma_typ_dtl.php', params)

get_typhoon_forecast(typhoon_id) async

Get forecast track for a specific typhoon.

Parameters:

  • typhoon_id (str) –

    Typhoon identification number

Returns:

Example

async with AsyncTyphoonClient('your_auth_key') ... data = await client.get_typhoon_forecast('2501')

Source code in python/src/kma_mcp/typhoon/async_typhoon_client.py 
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
async def get_typhoon_forecast(
    self,
    typhoon_id: str,
) -> dict[str, Any]:
    """Get forecast track for a specific typhoon.

    Args:
        typhoon_id: Typhoon identification number

    Returns:
        Typhoon forecast track data

    Example:
        >>> async with AsyncTyphoonClient('your_auth_key')
        >>> ...     data = await client.get_typhoon_forecast('2501')
    """
    params = {'typ_id': typhoon_id, 'help': '0'}
    return await self._make_request('kma_typ_fcst.php', params)

get_typhoon_history(year) async

Get typhoon history for a specific year.

Parameters:

  • year (int | str) –

    Year in 'YYYY' format

Returns:

  • dict[str, Any] –

    Typhoon history data for the year

Example

async with AsyncTyphoonClient('your_auth_key') ... data = await client.get_typhoon_history(2024)

Source code in python/src/kma_mcp/typhoon/async_typhoon_client.py 
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
async def get_typhoon_history(
    self,
    year: int | str,
) -> dict[str, Any]:
    """Get typhoon history for a specific year.

    Args:
        year: Year in 'YYYY' format

    Returns:
        Typhoon history data for the year

    Example:
        >>> async with AsyncTyphoonClient('your_auth_key')
        >>> ...     data = await client.get_typhoon_history(2024)
    """
    params = {'year': str(year), 'help': '0'}
    return await self._make_request('kma_typ_hist.php', params)