Skip to content

params

Pydantic validators for KMA API parameters.

DateParam

Bases: BaseModel

Validates date in YYYYMMDD format.

Example

date_param = DateParam(value='20250101') date_param.value '20250101' DateParam(value='20250230') # Invalid date InvalidDateError: Invalid date: 20250230

Source code in python/src/kma_mcp/validation/params.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
class DateParam(BaseModel):
    """Validates date in YYYYMMDD format.

    Example:
        >>> date_param = DateParam(value='20250101')
        >>> date_param.value
        '20250101'
        >>> DateParam(value='20250230')  # Invalid date
        InvalidDateError: Invalid date: 20250230
    """

    value: Annotated[str, Field(pattern=r'^\d{8}$', examples=['20250101'])]

    @field_validator('value')
    @classmethod
    def validate_date(cls, v: str) -> str:
        """Validate that the date string represents a valid date."""
        if len(v) != 8 or not v.isdigit():
            msg = f'Date must be 8 digits in YYYYMMDD format, got: {v}'
            raise InvalidDateError(msg)

        try:
            datetime.strptime(v, '%Y%m%d')  # noqa: DTZ007
        except ValueError as e:
            msg = f'Invalid date: {v}'
            raise InvalidDateError(msg) from e

        return v

    def __str__(self) -> str:
        """Return string representation of the date."""
        return self.value

validate_date(v) classmethod

Validate that the date string represents a valid date.

Source code in python/src/kma_mcp/validation/params.py 
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
@field_validator('value')
@classmethod
def validate_date(cls, v: str) -> str:
    """Validate that the date string represents a valid date."""
    if len(v) != 8 or not v.isdigit():
        msg = f'Date must be 8 digits in YYYYMMDD format, got: {v}'
        raise InvalidDateError(msg)

    try:
        datetime.strptime(v, '%Y%m%d')  # noqa: DTZ007
    except ValueError as e:
        msg = f'Invalid date: {v}'
        raise InvalidDateError(msg) from e

    return v

DateTimeParam

Bases: BaseModel

Validates datetime in YYYYMMDDHHmm format.

Example

dt_param = DateTimeParam(value='202501011200') dt_param.value '202501011200' DateTimeParam(value='202501012560') # Invalid time InvalidTimeError: Invalid datetime: 202501012560

Source code in python/src/kma_mcp/validation/params.py 
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
class DateTimeParam(BaseModel):
    """Validates datetime in YYYYMMDDHHmm format.

    Example:
        >>> dt_param = DateTimeParam(value='202501011200')
        >>> dt_param.value
        '202501011200'
        >>> DateTimeParam(value='202501012560')  # Invalid time
        InvalidTimeError: Invalid datetime: 202501012560
    """

    value: Annotated[str, Field(pattern=r'^\d{12}$', examples=['202501011200'])]

    @field_validator('value')
    @classmethod
    def validate_datetime(cls, v: str) -> str:
        """Validate that the datetime string represents a valid datetime."""
        if len(v) != 12 or not v.isdigit():
            msg = f'Datetime must be 12 digits in YYYYMMDDHHmm format, got: {v}'
            raise InvalidTimeError(msg)

        try:
            datetime.strptime(v, '%Y%m%d%H%M')  # noqa: DTZ007
        except ValueError as e:
            msg = f'Invalid datetime: {v}'
            raise InvalidTimeError(msg) from e

        return v

    def __str__(self) -> str:
        """Return string representation of the datetime."""
        return self.value

validate_datetime(v) classmethod

Validate that the datetime string represents a valid datetime.

Source code in python/src/kma_mcp/validation/params.py 
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
@field_validator('value')
@classmethod
def validate_datetime(cls, v: str) -> str:
    """Validate that the datetime string represents a valid datetime."""
    if len(v) != 12 or not v.isdigit():
        msg = f'Datetime must be 12 digits in YYYYMMDDHHmm format, got: {v}'
        raise InvalidTimeError(msg)

    try:
        datetime.strptime(v, '%Y%m%d%H%M')  # noqa: DTZ007
    except ValueError as e:
        msg = f'Invalid datetime: {v}'
        raise InvalidTimeError(msg) from e

    return v

LatitudeParam

Bases: BaseModel

Validates latitude coordinate.

Valid range for Korea region: 33.0 to 43.0

Example

lat = LatitudeParam(value=37.5) lat.value 37.5

Source code in python/src/kma_mcp/validation/params.py 
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
class LatitudeParam(BaseModel):
    """Validates latitude coordinate.

    Valid range for Korea region: 33.0 to 43.0

    Example:
        >>> lat = LatitudeParam(value=37.5)
        >>> lat.value
        37.5
    """

    value: Annotated[
        float,
        Field(
            ge=33.0,
            le=43.0,
            examples=[37.5],
            description='Latitude in decimal degrees (Korea region: 33-43)',
        ),
    ]

    @field_validator('value')
    @classmethod
    def validate_latitude(cls, v: float) -> float:
        """Validate latitude is within Korea region."""
        if not (33.0 <= v <= 43.0):
            msg = f'Latitude must be between 33.0 and 43.0 for Korea region, got: {v}'
            raise InvalidCoordinateError(msg)
        return v

    def __str__(self) -> str:
        """Return string representation of the latitude."""
        return str(self.value)

validate_latitude(v) classmethod

Validate latitude is within Korea region.

Source code in python/src/kma_mcp/validation/params.py 
156
157
158
159
160
161
162
163
@field_validator('value')
@classmethod
def validate_latitude(cls, v: float) -> float:
    """Validate latitude is within Korea region."""
    if not (33.0 <= v <= 43.0):
        msg = f'Latitude must be between 33.0 and 43.0 for Korea region, got: {v}'
        raise InvalidCoordinateError(msg)
    return v

LongitudeParam

Bases: BaseModel

Validates longitude coordinate.

Valid range for Korea region: 124.0 to 132.0

Example

lon = LongitudeParam(value=127.0) lon.value 127.0

Source code in python/src/kma_mcp/validation/params.py 
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 LongitudeParam(BaseModel):
    """Validates longitude coordinate.

    Valid range for Korea region: 124.0 to 132.0

    Example:
        >>> lon = LongitudeParam(value=127.0)
        >>> lon.value
        127.0
    """

    value: Annotated[
        float,
        Field(
            ge=124.0,
            le=132.0,
            examples=[127.0],
            description='Longitude in decimal degrees (Korea region: 124-132)',
        ),
    ]

    @field_validator('value')
    @classmethod
    def validate_longitude(cls, v: float) -> float:
        """Validate longitude is within Korea region."""
        if not (124.0 <= v <= 132.0):
            msg = f'Longitude must be between 124.0 and 132.0 for Korea region, got: {v}'
            raise InvalidCoordinateError(msg)
        return v

    def __str__(self) -> str:
        """Return string representation of the longitude."""
        return str(self.value)

validate_longitude(v) classmethod

Validate longitude is within Korea region.

Source code in python/src/kma_mcp/validation/params.py 
191
192
193
194
195
196
197
198
@field_validator('value')
@classmethod
def validate_longitude(cls, v: float) -> float:
    """Validate longitude is within Korea region."""
    if not (124.0 <= v <= 132.0):
        msg = f'Longitude must be between 124.0 and 132.0 for Korea region, got: {v}'
        raise InvalidCoordinateError(msg)
    return v

StationParam

Bases: BaseModel

Validates station ID.

Station ID can be: - 0: All stations - 1-999: ASOS/AWS station number - 47001-47999: WMO station code (for upper-air stations)

Example

stn = StationParam(value=108) stn.value 108 stn = StationParam(value=0) # All stations stn.value 0

Source code in python/src/kma_mcp/validation/params.py 
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
class StationParam(BaseModel):
    """Validates station ID.

    Station ID can be:
    - 0: All stations
    - 1-999: ASOS/AWS station number
    - 47001-47999: WMO station code (for upper-air stations)

    Example:
        >>> stn = StationParam(value=108)
        >>> stn.value
        108
        >>> stn = StationParam(value=0)  # All stations
        >>> stn.value
        0
    """

    value: Annotated[int, Field(ge=0, le=99999, examples=[0, 108, 47122])]

    @field_validator('value')
    @classmethod
    def validate_station(cls, v: int) -> int:
        """Validate station ID range."""
        if v < 0 or v > 99999:
            msg = f'Station ID must be between 0 and 99999, got: {v}'
            raise InvalidStationError(msg)
        return v

    def __str__(self) -> str:
        """Return string representation of the station ID."""
        return str(self.value)

validate_station(v) classmethod

Validate station ID range.

Source code in python/src/kma_mcp/validation/params.py 
121
122
123
124
125
126
127
128
@field_validator('value')
@classmethod
def validate_station(cls, v: int) -> int:
    """Validate station ID range."""
    if v < 0 or v > 99999:
        msg = f'Station ID must be between 0 and 99999, got: {v}'
        raise InvalidStationError(msg)
    return v

YearParam

Bases: BaseModel

Validates year in YYYY format.

Example

year = YearParam(value=2025) year.value 2025 YearParam(value=1800) # Too old InvalidDateError: Year must be between 1900 and 2100, got: 1800

Source code in python/src/kma_mcp/validation/params.py 
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
class YearParam(BaseModel):
    """Validates year in YYYY format.

    Example:
        >>> year = YearParam(value=2025)
        >>> year.value
        2025
        >>> YearParam(value=1800)  # Too old
        InvalidDateError: Year must be between 1900 and 2100, got: 1800
    """

    value: Annotated[int, Field(ge=1900, le=2100, examples=[2025])]

    def __str__(self) -> str:
        """Return string representation of the year."""
        return str(self.value)