kpublic

한국 공공데이터포털(data.go.kr) API를 함정 없이 쓰는 파이썬 SDK.

포털에서 키를 받고 처음 API를 붙이면 거의 모두가 같은 곳에서 넘어진다. 인코딩 키를 넣어서 SERVICE_KEY_IS_NOT_REGISTERED_ERROR, JSON을 요청했는데 XML 에러가 와서 json.loads 크래시, HTTP 200인데 본문 resultCode는 실패, 데이터 없음이 items: ""로 오는 것, 기상청 격자 좌표… kpublic은 그 함정들을 코어에서 전부 처리하고, 자주 쓰는 API는 어댑터로 감싼다.

pip install kpublic

import kpublic

c = kpublic.Client("포털에서 복사한 키")   # 인코딩 키든 디코딩 키든 그대로 붙여넣으면 된다

# 어댑터 — 서울시청 지금 날씨
kma = kpublic.kma.Forecast(c)
now = kma.ultra_now(lat=37.5665, lon=126.9780)   # 격자 변환·발표시각 계산 자동
now.values            # {'T1H': 23.1, 'RN1': 0.0, 'REH': 78.0, 'PTY': 0.0, ...}
now.label("T1H")      # '기온(℃)'

# 어댑터 — 미세먼지 / 공휴일
kpublic.airkorea.AirKorea(c).by_sido("서울")[0].pm25      # 18.0  (결측 '-'는 None)
kpublic.holidays.Holidays(c).get(2026, 9)                 # [Holiday(date=2026-09-24, name='추석', ...), ...]

# 범용 — 어떤 data.go.kr API든 경로만 알면 된다
r = c.get("1360000/AsosDalyInfoService/getWthrDataList",
          dataCd="ASOS", dateCd="DAY", startDt="20260901", endDt="20260907", stnIds=108, dataType="JSON")
r.items, r.total_count

# 자동 페이징 — totalCount 보고 끝까지
for row in c.iter_items("B552584/ArpltnInfrqncyInqireSvc/getCtprvnRltmMesureDnsty",
                        sidoName="전국", returnType="json", ver="1.3", page_size=100):
    ...

코어가 대신 처리하는 것

어댑터

어댑터가 없는 API는 Client.get(path, **params)로 그대로 부른다. 코어의 함정 처리는 똑같이 적용된다.

활용신청은 API마다 따로

키는 계정당 하나지만 API마다 활용신청을 해야 한다(대부분 자동승인). 안 하면 ServiceKeyError(30).

• 기상청 단기예보 — https://www.data.go.kr/data/15084084/openapi.do
• 에어코리아 대기오염 — https://www.data.go.kr/data/15073861/openapi.do
• 천문연 특일정보 — https://www.data.go.kr/data/15012690/openapi.do

신청 후 확인: KPUBLIC_SERVICE_KEY=발급키 python scripts/smoke.py

검증 상태 (0.1.0, 2026-09-09)

실서버 검증에서 잡힌 것 2건: 게이트웨이 오류의 4xx 처리 순서, 에어코리아 서비스 ID 오타(ArpltnInfrqncy… → ArpltnInforInqireSvc). 둘 다 단위 테스트만으로는 못 잡는 종류다.

개발

uv sync --group dev
uv run pytest
uv run ruff check . && uv run mypy src
uv build

로드맵

• 0.2 — AsyncClient(같은 코어), 응답 캐시(sqlite), 기상청 ASOS·중기예보, 한강홍수통제소
• 0.3 — pandas/polars 변환 헬퍼, CLI

라이선스

MIT