Skip to content

gts_client

Client for KMA Global Meteorology GTS (Global Telecommunication System) API.

Provides access to worldwide meteorological observation data collected through the WMO Global Telecommunication System.

GTSClient

Client for accessing KMA Global Meteorology GTS data.

Provides access to: - Global SYNOP observations (surface synoptic reports) - Global ship observations (marine weather) - Global buoy observations (ocean buoys) - Aircraft reports (AIREP)

Source code in python/src/kma_mcp/global_met/gts_client.py 
 12
 13
 14
 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
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
class GTSClient:
    """Client for accessing KMA Global Meteorology GTS data.

    Provides access to:
    - Global SYNOP observations (surface synoptic reports)
    - Global ship observations (marine weather)
    - Global buoy observations (ocean buoys)
    - Aircraft reports (AIREP)
    """

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

    def __init__(self, auth_key: str, timeout: float = 30.0):
        """Initialize GTS client.

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

    def __enter__(self) -> 'GTSClient':
        """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 an API request."""
        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_synop_observations(
        self,
        tm: str,
        dtm: int = 3,
        stn: int = 0,
    ) -> dict[str, Any]:
        """Get global SYNOP surface observations.

        SYNOP reports are surface synoptic observations from land stations
        worldwide, transmitted through the GTS network.

        Args:
            tm: Observation time in 'YYYYMMDDHHmm' format
            dtm: Data time range in hours before tm (default: 3)
                 Options: 3, 6, 12, 24
            stn: Station ID (0 for all stations, default: 0)

        Returns:
            Global SYNOP observation data

        Example:
            >>> with GTSClient('api_key') as client:
            >>>     data = client.get_synop_observations('202501011200', dtm=3)
        """
        params = {'tm': tm, 'dtm': dtm, 'stn': stn, 'help': '0'}
        return self._make_request('gts_bufr_syn.php', params)

    def get_ship_observations(
        self,
        tm: str,
        dtm: int = 3,
    ) -> dict[str, Any]:
        """Get global ship observations.

        Ship reports provide marine weather observations from vessels at sea,
        transmitted through the GTS network.

        Args:
            tm: Observation time in 'YYYYMMDDHHmm' format
            dtm: Data time range in hours before tm (default: 3)
                 Options: 3, 6, 12, 24

        Returns:
            Global ship observation data

        Example:
            >>> with GTSClient('api_key') as client:
            >>>     data = client.get_ship_observations('202501011200', dtm=6)
        """
        params = {'tm': tm, 'dtm': dtm, 'help': '0'}
        return self._make_request('gts_bufr_ship.php', params)

    def get_buoy_observations(
        self,
        tm: str,
        dtm: int = 3,
        stn: str = '',
    ) -> dict[str, Any]:
        """Get global buoy observations.

        Buoy reports provide marine weather observations from moored and
        drifting buoys worldwide, transmitted through the GTS network.

        Args:
            tm: Observation time in 'YYYYMMDDHHmm' format
            dtm: Data time range in hours before tm (default: 3)
                 Options: 3, 6, 12, 24
            stn: Buoy station ID (empty string for all, default: '')

        Returns:
            Global buoy observation data

        Example:
            >>> with GTSClient('api_key') as client:
            >>>     data = client.get_buoy_observations('202501011200', dtm=3)
        """
        params = {'tm': tm, 'dtm': dtm, 'stn': stn, 'help': '0'}
        return self._make_request('gts_bufr_buoy.php', params)

    def get_aircraft_reports(
        self,
        tm: str,
        dtm: int = 60,
        stn: int = 0,
    ) -> dict[str, Any]:
        """Get aircraft meteorological reports (AIREP).

        AIREP provides in-flight weather observations from commercial aircraft,
        transmitted through the GTS network.

        Args:
            tm: Observation time in 'YYYYMMDDHHmm' format
            dtm: Data time range in minutes before tm (default: 60)
                 Note: dtm is in MINUTES for aircraft reports
            stn: Station/aircraft ID (0 for all, default: 0)

        Returns:
            Aircraft meteorological report data

        Example:
            >>> with GTSClient('api_key') as client:
            >>>     data = client.get_aircraft_reports('202501011200', dtm=120)
        """
        params = {'tm': tm, 'dtm': dtm, 'stn': stn, 'help': '0'}
        return self._make_request('gts_airep1.php', params)

    def get_surface_chart(
        self,
        tm: str,
    ) -> dict[str, Any]:
        """Get GTS surface weather chart.

        Surface charts provide synoptic analysis and forecast maps
        distributed through the GTS network.

        Args:
            tm: Chart time in 'YYYYMMDDHHmm' format

        Returns:
            Surface weather chart data/image

        Example:
            >>> with GTSClient('api_key') as client:
            >>>     data = client.get_surface_chart('202501011200')
        """
        params = {'tm': tm, 'help': '0'}
        return self._make_request('gts_cht_sfc.php', params)

    def get_synop_chart(
        self,
        tm: str,
    ) -> dict[str, Any]:
        """Get GTS SYNOP analysis chart.

        SYNOP charts provide surface synoptic analysis maps
        distributed through the GTS network.

        Args:
            tm: Chart time in 'YYYYMMDDHHmm' format

        Returns:
            SYNOP analysis chart data/image

        Example:
            >>> with GTSClient('api_key') as client:
            >>>     data = client.get_synop_chart('202501011200')
        """
        params = {'tm': tm, 'help': '0'}
        return self._make_request('gts_cht_syn.php', params)

close()

Close the HTTP client.

Source code in python/src/kma_mcp/global_met/gts_client.py 
42
43
44
def close(self) -> None:
    """Close the HTTP client."""
    self._client.close()

get_aircraft_reports(tm, dtm=60, stn=0)

Get aircraft meteorological reports (AIREP).

AIREP provides in-flight weather observations from commercial aircraft, transmitted through the GTS network.

Parameters:

  • tm (str) –

    Observation time in 'YYYYMMDDHHmm' format

  • dtm (int, default: 60 ) –

    Data time range in minutes before tm (default: 60) Note: dtm is in MINUTES for aircraft reports

  • stn (int, default: 0 ) –

    Station/aircraft ID (0 for all, default: 0)

Returns:

  • dict[str, Any] –

    Aircraft meteorological report data

Example

with GTSClient('api_key') as client: data = client.get_aircraft_reports('202501011200', dtm=120)

Source code in python/src/kma_mcp/global_met/gts_client.py 
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
def get_aircraft_reports(
    self,
    tm: str,
    dtm: int = 60,
    stn: int = 0,
) -> dict[str, Any]:
    """Get aircraft meteorological reports (AIREP).

    AIREP provides in-flight weather observations from commercial aircraft,
    transmitted through the GTS network.

    Args:
        tm: Observation time in 'YYYYMMDDHHmm' format
        dtm: Data time range in minutes before tm (default: 60)
             Note: dtm is in MINUTES for aircraft reports
        stn: Station/aircraft ID (0 for all, default: 0)

    Returns:
        Aircraft meteorological report data

    Example:
        >>> with GTSClient('api_key') as client:
        >>>     data = client.get_aircraft_reports('202501011200', dtm=120)
    """
    params = {'tm': tm, 'dtm': dtm, 'stn': stn, 'help': '0'}
    return self._make_request('gts_airep1.php', params)

get_buoy_observations(tm, dtm=3, stn='')

Get global buoy observations.

Buoy reports provide marine weather observations from moored and drifting buoys worldwide, transmitted through the GTS network.

Parameters:

  • tm (str) –

    Observation time in 'YYYYMMDDHHmm' format

  • dtm (int, default: 3 ) –

    Data time range in hours before tm (default: 3) Options: 3, 6, 12, 24

  • stn (str, default: '' ) –

    Buoy station ID (empty string for all, default: '')

Returns:

Example

with GTSClient('api_key') as client: data = client.get_buoy_observations('202501011200', dtm=3)

Source code in python/src/kma_mcp/global_met/gts_client.py 
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
def get_buoy_observations(
    self,
    tm: str,
    dtm: int = 3,
    stn: str = '',
) -> dict[str, Any]:
    """Get global buoy observations.

    Buoy reports provide marine weather observations from moored and
    drifting buoys worldwide, transmitted through the GTS network.

    Args:
        tm: Observation time in 'YYYYMMDDHHmm' format
        dtm: Data time range in hours before tm (default: 3)
             Options: 3, 6, 12, 24
        stn: Buoy station ID (empty string for all, default: '')

    Returns:
        Global buoy observation data

    Example:
        >>> with GTSClient('api_key') as client:
        >>>     data = client.get_buoy_observations('202501011200', dtm=3)
    """
    params = {'tm': tm, 'dtm': dtm, 'stn': stn, 'help': '0'}
    return self._make_request('gts_bufr_buoy.php', params)

get_ship_observations(tm, dtm=3)

Get global ship observations.

Ship reports provide marine weather observations from vessels at sea, transmitted through the GTS network.

Parameters:

  • tm (str) –

    Observation time in 'YYYYMMDDHHmm' format

  • dtm (int, default: 3 ) –

    Data time range in hours before tm (default: 3) Options: 3, 6, 12, 24

Returns:

Example

with GTSClient('api_key') as client: data = client.get_ship_observations('202501011200', dtm=6)

Source code in python/src/kma_mcp/global_met/gts_client.py 
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
def get_ship_observations(
    self,
    tm: str,
    dtm: int = 3,
) -> dict[str, Any]:
    """Get global ship observations.

    Ship reports provide marine weather observations from vessels at sea,
    transmitted through the GTS network.

    Args:
        tm: Observation time in 'YYYYMMDDHHmm' format
        dtm: Data time range in hours before tm (default: 3)
             Options: 3, 6, 12, 24

    Returns:
        Global ship observation data

    Example:
        >>> with GTSClient('api_key') as client:
        >>>     data = client.get_ship_observations('202501011200', dtm=6)
    """
    params = {'tm': tm, 'dtm': dtm, 'help': '0'}
    return self._make_request('gts_bufr_ship.php', params)

get_surface_chart(tm)

Get GTS surface weather chart.

Surface charts provide synoptic analysis and forecast maps distributed through the GTS network.

Parameters:

  • tm (str) –

    Chart time in 'YYYYMMDDHHmm' format

Returns:

  • dict[str, Any] –

    Surface weather chart data/image

Example

with GTSClient('api_key') as client: data = client.get_surface_chart('202501011200')

Source code in python/src/kma_mcp/global_met/gts_client.py 
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
def get_surface_chart(
    self,
    tm: str,
) -> dict[str, Any]:
    """Get GTS surface weather chart.

    Surface charts provide synoptic analysis and forecast maps
    distributed through the GTS network.

    Args:
        tm: Chart time in 'YYYYMMDDHHmm' format

    Returns:
        Surface weather chart data/image

    Example:
        >>> with GTSClient('api_key') as client:
        >>>     data = client.get_surface_chart('202501011200')
    """
    params = {'tm': tm, 'help': '0'}
    return self._make_request('gts_cht_sfc.php', params)

get_synop_chart(tm)

Get GTS SYNOP analysis chart.

SYNOP charts provide surface synoptic analysis maps distributed through the GTS network.

Parameters:

  • tm (str) –

    Chart time in 'YYYYMMDDHHmm' format

Returns:

  • dict[str, Any] –

    SYNOP analysis chart data/image

Example

with GTSClient('api_key') as client: data = client.get_synop_chart('202501011200')

Source code in python/src/kma_mcp/global_met/gts_client.py 
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
def get_synop_chart(
    self,
    tm: str,
) -> dict[str, Any]:
    """Get GTS SYNOP analysis chart.

    SYNOP charts provide surface synoptic analysis maps
    distributed through the GTS network.

    Args:
        tm: Chart time in 'YYYYMMDDHHmm' format

    Returns:
        SYNOP analysis chart data/image

    Example:
        >>> with GTSClient('api_key') as client:
        >>>     data = client.get_synop_chart('202501011200')
    """
    params = {'tm': tm, 'help': '0'}
    return self._make_request('gts_cht_syn.php', params)

get_synop_observations(tm, dtm=3, stn=0)

Get global SYNOP surface observations.

SYNOP reports are surface synoptic observations from land stations worldwide, transmitted through the GTS network.

Parameters:

  • tm (str) –

    Observation time in 'YYYYMMDDHHmm' format

  • dtm (int, default: 3 ) –

    Data time range in hours before tm (default: 3) Options: 3, 6, 12, 24

  • stn (int, default: 0 ) –

    Station ID (0 for all stations, default: 0)

Returns:

  • dict[str, Any] –

    Global SYNOP observation data

Example

with GTSClient('api_key') as client: data = client.get_synop_observations('202501011200', dtm=3)

Source code in python/src/kma_mcp/global_met/gts_client.py 
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
def get_synop_observations(
    self,
    tm: str,
    dtm: int = 3,
    stn: int = 0,
) -> dict[str, Any]:
    """Get global SYNOP surface observations.

    SYNOP reports are surface synoptic observations from land stations
    worldwide, transmitted through the GTS network.

    Args:
        tm: Observation time in 'YYYYMMDDHHmm' format
        dtm: Data time range in hours before tm (default: 3)
             Options: 3, 6, 12, 24
        stn: Station ID (0 for all stations, default: 0)

    Returns:
        Global SYNOP observation data

    Example:
        >>> with GTSClient('api_key') as client:
        >>>     data = client.get_synop_observations('202501011200', dtm=3)
    """
    params = {'tm': tm, 'dtm': dtm, 'stn': stn, 'help': '0'}
    return self._make_request('gts_bufr_syn.php', params)