Skip to content

uv_client

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.

UVClient

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/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
class UVClient:
    """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.Client(timeout=timeout)

    def __enter__(self) -> 'UVClient':
        """Context manager entry."""
        return self

    def __exit__(self, *args: object) -> None:
        """Context manager exit."""
        self.close()

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

    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 = self._client.get(url, params=params)
        response.raise_for_status()
        return response.json()

    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:
            >>> client = UVClient('your_auth_key')
            >>> data = client.get_observation_data('202203211500')
            >>> # Or using datetime
            >>> from datetime import datetime
            >>> data = 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 self._make_request('kma_sfctm_uv.php', params)

close()

Close the HTTP client.

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

get_observation_data(tm, stn=0)

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

client = UVClient('your_auth_key') data = client.get_observation_data('202203211500')

Or using datetime

from datetime import datetime data = 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/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
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:
        >>> client = UVClient('your_auth_key')
        >>> data = client.get_observation_data('202203211500')
        >>> # Or using datetime
        >>> from datetime import datetime
        >>> data = 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 self._make_request('kma_sfctm_uv.php', params)