Skip to content

api-coverage.md

Latest commit

 

History

History
216 lines (144 loc) · 12.1 KB

api-coverage.md

File metadata and controls

216 lines (144 loc) · 12.1 KB
Raw

API 구현 범위

이 문서는 현재 kma가 구현한 API 개수를 명확히 세기 위한 기준입니다.

요약

현재 직접 타입화된 모델로 구현한 KMA endpoint는 4개이고, data.go.kr 기상청 검색 전체 페이지에서 확인한 KMA 항목 86개를 카탈로그로 제공합니다. 이 중 기존 data.go.kr serviceKey gateway 항목은 38개, 포털 상세기능에서 확인한 gateway operation은 160개, APIHub LINK 항목은 48개입니다. 주요 서비스 helper는 20개 이상의 operation을 감싸며, 별도로 해수욕장 날씨 조회서비스 helper는 6개 operation을 감쌉니다. APIHub 공식 목록을 함수형으로 감싼 endpoint는 470개입니다.

구분 개수 설명
개별 타입화 endpoint 4개 KmaClient가 Pydantic 모델로 반환하는 단기예보 endpoint
data.go.kr 범용 호출 방식 1개 계층 임의 {service}/{operation} 호출 가능
data.go.kr 기상청 카탈로그 86개 공공데이터포털 기상청 검색 전체 페이지에서 제목이 기상청으로 시작하는 항목만 포함
data.go.kr serviceKey gateway operation 160개 카탈로그 중 gateway 항목 38개의 포털 상세기능 operation
data.go.kr/APIHub 정확 중복 109개 APIHub /api/typ02/openApi/{service}/{operation}와 같은 gateway operation
data.go.kr 주요 서비스 helper 20개+ ASOS, 특보, 통보문, 관광코스, 생활기상지수, 지진정보 등
data.go.kr 해수욕장 날씨 helper 6개 BeachInfoservice operation을 Pydantic row 모델로 반환
APIHub 범용 호출 방식 1개 계층 임의 /api/... path 호출 가능
APIHub 함수형 래퍼 470개 apiList.do와 generateAPIUrl.do 기반 함수형 endpoint
APIHub 첨부 metadata 77개 포맷정보, 예제, 코드표 등 첨부 링크
APIHub 탐색 기능 2개 메서드 서비스 목록과 endpoint sample 추출
위치/코드/시간축 타입 계층 1개 계층 LatLon, GridPoint, WeatherCategory, KmaEndpoint, ForecastTimepoint, pivot_forecast_items() 등 public helper

타입화 endpoint 4개

KmaClient가 직접 편의 메서드와 모델을 제공하는 endpoint입니다.

번호 메서드 서비스 endpoint 반환
1 now() VilageFcstInfoService_2.0 getUltraSrtNcst WeatherSnapshot
2 forecast_short() VilageFcstInfoService_2.0 getUltraSrtFcst list[ForecastItem]
3 forecast() VilageFcstInfoService_2.0 getVilageFcst list[ForecastItem]
4 version() VilageFcstInfoService_2.0 getFcstVersion raw mapping

data.go.kr generic 지원

DataGoKrClient는 다음 형태의 KMA gateway endpoint를 호출할 수 있습니다.

http://apis.data.go.kr/1360000/{service}/{operation}

예:

from kma import DataGoKrClient
import asyncio


async def main() -> None:
    async with DataGoKrClient.from_env() as client:
        (await client.request("MidFcstInfoService", "getMidFcst", {"stnId": "108", "tmFc": "202605010600"}))


asyncio.run(main())

이 계층은 특정 endpoint를 개별 모델로 구현한 것이 아니라, 표준 data.go.kr envelope를 범용으로 처리합니다. 따라서 “개별 구현 endpoint 개수”에는 넣지 않습니다.

공공데이터포털 문서에는 인증키 파라미터가 serviceKey 또는 ServiceKey로 섞여 표시됩니다. DataGoKrClient는 기본적으로 serviceKey를 쓰며, 필요한 경우 service_key_param="ServiceKey"로 바꿀 수 있습니다.

data.go.kr 기상청 카탈로그 86개

2026-05-07 기준 공공데이터포털 기상청 오픈 API 검색을 perPage=40으로 모든 페이지 확인했고, 제목이 기상청으로 시작하는 항목만 KMA_DATA_GOKR_DATASETS에 반영했습니다. 기상청이 아닌 기관의 검색 결과는 포함하지 않습니다.

카탈로그 구성은 기존 data.go.kr serviceKey gateway 38개, 해당 gateway operation 160개, APIHub LINK 48개입니다. 이 중 APIHub typ02/openApi와 정확히 같은 {service}/{operation}은 21개 dataset, 109개 operation입니다. 자세한 표는 data.go.kr/APIHub 중복 확인에 있습니다.

DataGoKrClient.dataset(dataset_id)는 카탈로그 metadata를 반환하고, dataset_items(dataset_id, ...)는 기존 serviceKey gateway 항목을 {service}/{operation} 형태로 호출합니다. APIHub LINK 항목은 gateway="apihub"로 표시하며 ApiHubClient 또는 ApiHubGeneratedClient로 호출해야 합니다.

UI나 디버그 도구에서는 api_catalog()를 사용합니다. 이 함수는 data.go.kr 항목을 operation 단위로 펼치고 APIHub LINK 항목을 dataset 단위로 포함해, dataset_name, label, gateway, service, operation, credential_param, service_key_url이 있는 row를 반환합니다.

data.go.kr 주요 서비스 helper

2026-05-07 기준 공공데이터포털 기상청 오픈 API 검색에서 확인한 서비스 중 자주 쓰는 주요 REST 서비스는 DataGoKrClient helper로 감쌉니다. 응답 row는 endpoint별 고정 모델 대신 DataGoKrItem으로 반환해 service, operation, raw, metadata를 제공합니다.

서비스 helper
MidFcstInfoService/getMidSeaFcst mid_sea_forecast()
AsosDalyInfoService/getWthrDataList asos_daily_weather()
AsosHourlyInfoService/getWthrDataList asos_hourly_weather()
WthrWrnInfoService/* weather_warning(), weather_warning_list()
VilageFcstMsgService/* forecast_message(), weather_situation(), land_forecast_message(), sea_forecast_message()
TourStnInfoService1/* tour_village_forecast(), city_tour_climate_index()
LivingWthrIdxServiceV4/* sensible_temperature_index(), uv_index(), air_diffusion_index()
EqkInfoService/* earthquake_info(), earthquake_message(), earthquake_message_list(), tsunami_message(), tsunami_message_list()

중기예보 helper의 tm_fc는 직접 지정할 수 있고, 생략하면 latest_mid_fcst_time()으로 06:00/18:00 발표와 10분 조회 지연을 반영한 최신 tmFc를 선택합니다.

data.go.kr 해수욕장 날씨 helper 6개

공공데이터포털 기상청_전국 해수욕장 날씨 조회서비스는 BeachInfoservice 아래 6개 operation을 제공합니다. DataGoKrClient는 범용 호출도 가능하지만, 이 서비스는 자주 쓰는 파라미터와 응답 row 모델을 전용 helper로 제공합니다.

번호 메서드 endpoint 반환
1 beach_ultra_short_forecast() getUltraSrtFcstBeach list[BeachForecastItem]
2 beach_forecast() getVilageFcstBeach list[BeachForecastItem]
3 beach_wave_height() getWhBuoyBeach list[BeachWaveHeight]
4 beach_tide_info() getTideInfoBeach list[BeachTideItem]
5 beach_sun_info() getSunInfoBeach list[BeachSunTime]
6 beach_water_temperature() getTwBuoyBeach list[BeachWaterTemperature]

APIHub 범용 지원

ApiHubClient는 다음 형태의 APIHub path를 호출할 수 있습니다.

https://apihub.kma.go.kr/api/...

예:

from kma import ApiHubGeneratedClient
import asyncio


async def main() -> None:
    async with ApiHubGeneratedClient.from_env() as hub:
        (await hub.request_path("/api/typ01/url/wrn_reg.php", {"tmfc": "0"}))


asyncio.run(main())

또한 typ02/openApi helper를 제공합니다.

from kma import ApiHubGeneratedClient
import asyncio


async def main() -> None:
    async with ApiHubGeneratedClient.from_env() as hub:
        (await hub.open_api("MidFcstInfoService", "getMidFcst", {"stnId": "108", "tmFc": "202605010600"}))


asyncio.run(main())

APIHub는 텍스트, JSON, XML, 이미지, 바이너리 파일 응답이 섞여 있습니다. kma는 endpoint별 반환 스키마를 모두 Pydantic 모델로 고정하지는 않지만, 공식 목록에서 확인한 endpoint를 ApiHubGeneratedClient의 함수형 메서드로 제공합니다.

예:

import asyncio
from kma import ApiHubGeneratedClient


async def main() -> None:
    async with ApiHubGeneratedClient.from_env() as hub:
        response = (await hub.kma_sfctm2(tm="202605010900", stn="108", help="1"))


asyncio.run(main())

전체 목록은 docs/apihub-endpoints.md에 있습니다.

APIHub 조사 기준

2026-05-06에 공식 페이지를 다시 확인했습니다.

  • apiInfo.do 사용자용 제공내역 분류: 13개
  • apiList.do에서 실제 접근 가능한 wrapper 생성 대상 분류: 13개
  • apiList.do에서 확인한 서비스: 59개
  • 함수형 래퍼 생성 기준: apiList.do 본문 예제 URL, generateAPIUrl.do의 urlList, API URL을 포함한 텍스트 예제 첨부
  • 중복 제거한 path/parameter signature: 470개
  • 첨부 자료 metadata: 77개

apiInfo.do의 제공내역 번호는 사용자 안내용 번호이고, apiList.do의 seqApi는 포털 내부 라우팅 id입니다. 두 번호 체계가 같다고 가정하지 않습니다.

이 470개는 ApiHubGeneratedClient의 함수형 래퍼로 구현되어 있습니다. 다만 응답 row schema를 endpoint별 Pydantic 모델로 모두 고정한 것은 아니며, 응답 종류에 따라 json(), text_table(), image() 등으로 다룹니다.

2026-05-06 APIHub 재대조 결과

공식 APIHub를 다시 수집해 로컬 snapshot과 비교했습니다.

항목 공식 재수집 로컬 구현 차이
endpoint signature 470 470 0
함수 이름 470 470 0
첨부 metadata 77 77 0

seqApi 1~20을 확인했을 때 서비스가 있는 카테고리는 2~12, 14, 15였고, 13은 현재 서비스가 없습니다. 따라서 생성 대상 카테고리에서 13을 제외한 것은 현재 공식 목록과 일치합니다.

검사 중 generateAPIUrl.do가 특정 서비스에서 일시적으로 HTTP 500을 반환하는 경우가 확인되었습니다. tools/update_apihub_endpoints.py는 이제 보조 URL 발행 metadata가 실패해도 apiList.do 본문과 첨부 예제에서 확인되는 endpoint를 계속 수집합니다. 실제 누락 여부는 최종 signature 비교로 확인합니다.

data.go.kr 재검토 결과

data.go.kr의 KMA REST API는 http://apis.data.go.kr/1360000/{service}/{operation} 형태가 반복됩니다. DataGoKrClient는 이 형태를 범용으로 호출하고, 공공데이터포털 기상청 검색 전체 페이지에서 확인한 KMA 항목 86개와 gateway operation 160개를 dataset id 카탈로그로 제공합니다. 모든 data.go.kr 서비스를 endpoint별 개별 함수로 생성하지는 않습니다.

현재 보장 범위:

  • 표준 response.header/body JSON envelope 처리
  • 단일 dict/list items.item 정규화
  • typed result-code exception
  • serviceKey/ServiceKey 인증 파라미터 이름 선택
  • 제목이 기상청으로 시작하는 data.go.kr 검색 항목 86개와 gateway operation 160개 카탈로그

현재 보장하지 않는 범위:

  • data.go.kr의 모든 operation을 endpoint별 Pydantic 모델로 고정 변환
  • JSON이 아닌 XML 전용 또는 파일 다운로드 응답의 자동 모델링
  • 각 서비스별 필수 파라미터 조합 검증
  • APIHub LINK 항목을 serviceKey gateway로 자동 변환

답변 기준

“지금 구현해놓은 API가 몇 개냐”는 질문에는 다음처럼 답합니다.

  • 직접 타입화 구현 endpoint는 4개입니다.
  • data.go.kr 기상청 검색 카탈로그 항목은 86개입니다.
  • APIHub 함수형 래퍼는 470개입니다.
  • 범용 클라이언트까지 포함하면 data.go.kr 임의 service/operation과 APIHub /api/... path를 호출할 수 있습니다.
  • APIHub 470개는 endpoint별 함수 이름을 제공하지만, 모든 응답을 endpoint별 Pydantic 모델로 강제 변환하지는 않습니다.
  • 위치/코드 타입 계층은 endpoint 개수를 늘리는 항목은 아니며, 외부 프로그램에서 좌표계와 category 문자열을 안정적으로 다루기 위한 public API입니다.