Skip to content

async_uv_client

Async KMA UV Radiation Observation API client.

This module provides a client for accessing the Korea Meteorological Administration's UV Radiation (자외선관측) API for ultraviolet index observations.

UV radiation observations monitor ultraviolet radiation levels for public health protection and sun safety guidance.

AsyncUVClient

Async client for KMA UV Radiation Observation API.

The UV observation system monitors ultraviolet radiation levels and provides UV index data for public health protection and sun safety recommendations.

Source code in python/src/kma_mcp/surface/async_uv_client.py 
 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
class AsyncUVClient:
    """Async client for KMA UV Radiation Observation API.

    The UV observation system monitors ultraviolet radiation levels
    and provides UV index data for public health protection and
    sun safety recommendations.
    """

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

    def __init__(self, auth_key: str, timeout: float = 30.0) -> None:
        """Initialize UV Radiation 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) -> 'AsyncUVClient':
        """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 UV Radiation 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_observation_data(
        self,
        tm: str | datetime,
        stn: int | str = 0,
    ) -> dict[str, Any]:
        """Get UV radiation observation data for a single time.

        This is the only documented API endpoint for UV observations.
        UV observations monitor ultraviolet A and erythema B radiation levels.

        Args:
            tm: Time in 'YYYYMMDDHHmm' format or datetime object
            stn: Station number (0 for all stations)

        Returns:
            UV radiation observation data

        Example:
            >>> async with AsyncUVClient('your_auth_key') as client:
            ...     data = await client.get_observation_data('202203211500')
            >>> # Or using datetime
            >>> from datetime import datetime
            >>> async with AsyncUVClient('your_auth_key') as client:
            ...     data = await client.get_observation_data(datetime(2022, 3, 21, 15, 0))

        Note:
            - UV observation stations: Anmyeondo, Gosan, Ulleungdo, Seoul,
              Pohang, Mokpo, Gangneung (7 stations)
            - Measures UVA (320-400nm) and erythema UVB (280-320nm)
            - Data available from January 1994 to present
        """
        if isinstance(tm, datetime):
            tm = tm.strftime('%Y%m%d%H%M')

        params = {'tm': tm, 'stn': str(stn), 'help': '1'}
        return await self._make_request('kma_sfctm_uv.php', params)

close() async

Close the HTTP client.

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

get_observation_data(tm, stn=0) async

Get UV radiation observation data for a single time.

This is the only documented API endpoint for UV observations. UV observations monitor ultraviolet A and erythema B radiation levels.

Parameters:

  • tm (str | datetime) –

    Time in 'YYYYMMDDHHmm' format or datetime object

  • stn (int | str, default: 0 ) –

    Station number (0 for all stations)

Returns:

  • dict[str, Any] –

    UV radiation observation data

Example

async with AsyncUVClient('your_auth_key') as client: ... data = await client.get_observation_data('202203211500')

Or using datetime

from datetime import datetime async with AsyncUVClient('your_auth_key') as client: ... data = await client.get_observation_data(datetime(2022, 3, 21, 15, 0))

Note
  • UV observation stations: Anmyeondo, Gosan, Ulleungdo, Seoul, Pohang, Mokpo, Gangneung (7 stations)
  • Measures UVA (320-400nm) and erythema UVB (280-320nm)
  • Data available from January 1994 to present
Source code in python/src/kma_mcp/surface/async_uv_client.py 
 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
async def get_observation_data(
    self,
    tm: str | datetime,
    stn: int | str = 0,
) -> dict[str, Any]:
    """Get UV radiation observation data for a single time.

    This is the only documented API endpoint for UV observations.
    UV observations monitor ultraviolet A and erythema B radiation levels.

    Args:
        tm: Time in 'YYYYMMDDHHmm' format or datetime object
        stn: Station number (0 for all stations)

    Returns:
        UV radiation observation data

    Example:
        >>> async with AsyncUVClient('your_auth_key') as client:
        ...     data = await client.get_observation_data('202203211500')
        >>> # Or using datetime
        >>> from datetime import datetime
        >>> async with AsyncUVClient('your_auth_key') as client:
        ...     data = await client.get_observation_data(datetime(2022, 3, 21, 15, 0))

    Note:
        - UV observation stations: Anmyeondo, Gosan, Ulleungdo, Seoul,
          Pohang, Mokpo, Gangneung (7 stations)
        - Measures UVA (320-400nm) and erythema UVB (280-320nm)
        - Data available from January 1994 to present
    """
    if isinstance(tm, datetime):
        tm = tm.strftime('%Y%m%d%H%M')

    params = {'tm': tm, 'stn': str(stn), 'help': '1'}
    return await self._make_request('kma_sfctm_uv.php', params)