kpubdata 0.3.0__tar.gz → 0.4.0__tar.gz

{kpubdata-0.3.0 → kpubdata-0.4.0}/ARCHITECTURE.md

@@ -349,9 +349,10 @@ Not part of the core runtime contract.
 Examples:
 
 - pandas export
-- MCP adapter
 - plugin loaders
 
+MCP adapter는 별도 레포(kpubdata-mcp 등)로 분리합니다. 코어 런타임에 포함하지 않습니다.
+
 ## 4. Main abstractions
 
 ### 4.1 Client
@@ -475,7 +476,7 @@ src/kpubdata/
       mappings.py
   adapters/
     pandas.py
-    mcp.py
+    # MCP adapter는 별도 레포(kpubdata-mcp 등)로 분리
 ```
 
 ## 9. Execution flow
@@ -546,4 +547,3 @@ Do **not** change the core just because one adapter is weird.
 | :--- | :--- | :--- |
 | [kpubdata-builder](https://github.com/yeongseon/kpubdata-builder) | [ARCHITECTURE.md](https://github.com/yeongseon/kpubdata-builder/blob/main/ARCHITECTURE.md) | Builder 아키텍처 |
 | [kpubdata-studio](https://github.com/yeongseon/kpubdata-studio) | [ARCHITECTURE.md](https://github.com/yeongseon/kpubdata-studio/blob/main/ARCHITECTURE.md) | Studio 아키텍처 |
-

{kpubdata-0.3.0 → kpubdata-0.4.0}/CHANGELOG.md

@@ -7,7 +7,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-## [0.3.0] - 2025-04-22
+## [0.3.1] - 2026-04-23
+
+### Fixed
+- Source `__version__` from `importlib.metadata` instead of hardcoded string (#127)
+- Add 활용신청 (activation request) hint to datago 403 `AuthError` and document API key activation requirement (#128)
+- Add required parameters to metro integration tests (#140)
+
+## [0.3.0] - 2026-04-22
 
 ### Added
 - `localdata` provider: expand permit datasets from 26 to **195**, covering all official KSIC categories — health (13), animal (18), culture (53), living (26), food (32), resources & environment (37), other (16)
@@ -19,7 +26,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Unit and contract tests plus SGIS fixture responses for boundary and auth/error scenarios
 - Full fixture, unit test, and contract test coverage for all 195 localdata datasets
 
-## [0.2.0] - 2025-04-17
+## [0.2.3] - 2026-04-19
+
+### Fixed
+- `LofinAdapter` SSL context ignored when `Client` passes shared transport
+
+### Added
+- 7 real estate transaction datasets to datago provider (`apt_rent`, `offi_trade`, `offi_rent`, `rh_trade`, `rh_rent`, `sh_trade`, `sh_rent`)
+- Treat `resultCode` `'000'` as success for RTMS endpoints
+
+## [0.2.2] - 2026-04-17
+
+### Added
+- Cursor pagination support and pagination documentation
+
+## [0.2.1] - 2026-04-17
+
+### Added
+- `SUPPORTED_DATA.md` 실API 최종 검증일 컬럼 추가
+- Single-page pagination contract and `list_all()` implementation
+
+## [0.2.0] - 2026-04-17
 
 ### Added
 - Single-page pagination contract for all adapters (datago, bok, lofin, kosis)
@@ -35,7 +62,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Unreachable single-record adapter stubs
 - Single-record access from the provider and dataset public APIs
 
-## [0.1.0] - 2025-04-10
+## [0.1.0] - 2026-04-10
 
 ### Added
 

{kpubdata-0.3.0 → kpubdata-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kpubdata
-Version: 0.3.0
+Version: 0.4.0
 Summary: Dialect-inspired Python access framework for Korean public data
 Author: Yeongseon Choe
 License: MIT
@@ -166,6 +166,11 @@ KPubData가 지원하는 각 기관의 API 키를 발급받아 [환경 변수](h
 - **절차**: 회원가입 → 지방행정인허가 Open API(일반음식점/휴게음식점) 활용신청 → 승인 후 인증키 확인
 - **환경 변수**: `KPUBDATA_LOCALDATA_API_KEY`
 
+#### 소상공인시장진흥공단 상가(상권)정보 (data.go.kr) — `semas`
+- **가입 URL**: [https://www.data.go.kr](https://www.data.go.kr)
+- **절차**: 회원가입 → 소상공인시장진흥공단 상가(상권)정보 Open API 활용신청 → 승인 후 인증키 확인
+- **환경 변수**: `KPUBDATA_SEMAS_API_KEY`
+
 #### 서울 열린데이터광장 (data.seoul.go.kr) — `seoul`
 - **가입 URL**: [https://data.seoul.go.kr/](https://data.seoul.go.kr/)
 - **절차**: 회원가입 → 원하는 Open API 페이지에서 인증키 신청/확인 → 마이페이지에서 발급 키 확인
@@ -198,6 +203,9 @@ export KPUBDATA_LOFIN_API_KEY="your-lofin-api-key"
 # 지방행정인허가
 export KPUBDATA_LOCALDATA_API_KEY="your-localdata-service-key"
 
+# 소상공인시장진흥공단 상가(상권)정보
+export KPUBDATA_SEMAS_API_KEY="your-semas-service-key"
+
 # 서울 열린데이터광장
 export KPUBDATA_SEOUL_API_KEY="your-seoul-api-key"
 
@@ -221,6 +229,7 @@ client = Client(provider_keys={
     "kosis": "YOUR_KOSIS_API_KEY",
     "lofin": "YOUR_LOFIN_API_KEY",
     "localdata": "YOUR_DATA_GO_KR_API_KEY",
+    "semas": "YOUR_SEMAS_API_KEY",
     "seoul": "YOUR_SEOUL_API_KEY",
     "sgis": "YOUR_SGIS_CONSUMER_KEY:YOUR_SGIS_CONSUMER_SECRET",
 })
@@ -349,7 +358,18 @@ for item in result.items:
     print(item["BPLC_NM"], item["ROAD_NM_ADDR"])
 ```
 
-### 10. 전체 페이지 자동 조회 (list_all)
+### 10. 소상공인 상가정보 조회 (Semas)
+
+```python
+client = Client(provider_keys={"semas": "YOUR_SEMAS_API_KEY"})
+ds = client.dataset("semas.store_radius")
+result = ds.list(cx="127.02758", cy="37.49794", radius="250", page_size=10)
+
+for item in result.items:
+    print(item["bizesNm"], item["rdnmAdr"])
+```
+
+### 11. 전체 페이지 자동 조회 (list_all)
 
 대량의 데이터를 페이지 단위로 자동 순회하려면 `list_all()`을 사용합니다.
 
@@ -363,7 +383,7 @@ for batch in ds.list_all(fyr="2024"):
         print(item)
 ```
 
-### 11. pandas DataFrame 변환
+### 12. pandas DataFrame 변환
 
 조회 결과를 pandas DataFrame으로 변환하여 분석할 수 있습니다.
 
@@ -494,4 +514,4 @@ KPubData의 설계 철학과 사용 방법을 안내하는 문서 목록입니
 - [Pandas](https://pandas.pydata.org/docs/getting_started/intro_tutorials/index.html)(데이터 분석용 파이썬 라이브러리) 데이터프레임 변환 어댑터 추가
 
 ### v0.3
-- 표준 코어를 기반으로 한 경량 [MCP](https://modelcontextprotocol.io/)(Model Context Protocol — AI 모델이 외부 도구를 사용하는 표준 규약) 어댑터 지원
+- Provider 확장 (지역 기반 추가 데이터셋)

{kpubdata-0.3.0 → kpubdata-0.4.0}/README.md

@@ -129,6 +129,11 @@ KPubData가 지원하는 각 기관의 API 키를 발급받아 [환경 변수](h
 - **절차**: 회원가입 → 지방행정인허가 Open API(일반음식점/휴게음식점) 활용신청 → 승인 후 인증키 확인
 - **환경 변수**: `KPUBDATA_LOCALDATA_API_KEY`
 
+#### 소상공인시장진흥공단 상가(상권)정보 (data.go.kr) — `semas`
+- **가입 URL**: [https://www.data.go.kr](https://www.data.go.kr)
+- **절차**: 회원가입 → 소상공인시장진흥공단 상가(상권)정보 Open API 활용신청 → 승인 후 인증키 확인
+- **환경 변수**: `KPUBDATA_SEMAS_API_KEY`
+
 #### 서울 열린데이터광장 (data.seoul.go.kr) — `seoul`
 - **가입 URL**: [https://data.seoul.go.kr/](https://data.seoul.go.kr/)
 - **절차**: 회원가입 → 원하는 Open API 페이지에서 인증키 신청/확인 → 마이페이지에서 발급 키 확인
@@ -161,6 +166,9 @@ export KPUBDATA_LOFIN_API_KEY="your-lofin-api-key"
 # 지방행정인허가
 export KPUBDATA_LOCALDATA_API_KEY="your-localdata-service-key"
 
+# 소상공인시장진흥공단 상가(상권)정보
+export KPUBDATA_SEMAS_API_KEY="your-semas-service-key"
+
 # 서울 열린데이터광장
 export KPUBDATA_SEOUL_API_KEY="your-seoul-api-key"
 
@@ -184,6 +192,7 @@ client = Client(provider_keys={
     "kosis": "YOUR_KOSIS_API_KEY",
     "lofin": "YOUR_LOFIN_API_KEY",
     "localdata": "YOUR_DATA_GO_KR_API_KEY",
+    "semas": "YOUR_SEMAS_API_KEY",
     "seoul": "YOUR_SEOUL_API_KEY",
     "sgis": "YOUR_SGIS_CONSUMER_KEY:YOUR_SGIS_CONSUMER_SECRET",
 })
@@ -312,7 +321,18 @@ for item in result.items:
     print(item["BPLC_NM"], item["ROAD_NM_ADDR"])
 ```
 
-### 10. 전체 페이지 자동 조회 (list_all)
+### 10. 소상공인 상가정보 조회 (Semas)
+
+```python
+client = Client(provider_keys={"semas": "YOUR_SEMAS_API_KEY"})
+ds = client.dataset("semas.store_radius")
+result = ds.list(cx="127.02758", cy="37.49794", radius="250", page_size=10)
+
+for item in result.items:
+    print(item["bizesNm"], item["rdnmAdr"])
+```
+
+### 11. 전체 페이지 자동 조회 (list_all)
 
 대량의 데이터를 페이지 단위로 자동 순회하려면 `list_all()`을 사용합니다.
 
@@ -326,7 +346,7 @@ for batch in ds.list_all(fyr="2024"):
         print(item)
 ```
 
-### 11. pandas DataFrame 변환
+### 12. pandas DataFrame 변환
 
 조회 결과를 pandas DataFrame으로 변환하여 분석할 수 있습니다.
 
@@ -457,4 +477,4 @@ KPubData의 설계 철학과 사용 방법을 안내하는 문서 목록입니
 - [Pandas](https://pandas.pydata.org/docs/getting_started/intro_tutorials/index.html)(데이터 분석용 파이썬 라이브러리) 데이터프레임 변환 어댑터 추가
 
 ### v0.3
-- 표준 코어를 기반으로 한 경량 [MCP](https://modelcontextprotocol.io/)(Model Context Protocol — AI 모델이 외부 도구를 사용하는 표준 규약) 어댑터 지원
+- Provider 확장 (지역 기반 추가 데이터셋)

kpubdata-0.4.0/ROADMAP.md

@@ -0,0 +1,101 @@
+# Roadmap — KPubData
+
+> kpubdata는 **한국 공공데이터 접근 코어 프레임워크**에 집중합니다.
+> MCP, HTTP API 등 서비스 레이어는 본체에 포함하지 않으며, 필요 시 별도 레포(`kpubdata-mcp` 등)로 분리합니다.
+
+## 개발 3축
+
+| 축 | 설명 | 대표 이슈 |
+| :--- | :--- | :--- |
+| **Core** | 핵심 계약(contract), 스키마, 메타데이터, discovery 안정화 | #55, #57, #63 |
+| **Plugin Ecosystem** | entry-point plugin discovery, provider scaffolding 도구 | #112, #61 |
+| **Provider Adapters** | 기관별 어댑터 확장 (datago, localdata, semas, bok, ...) | #87-#94, #161-#168 |
+
+---
+
+## v0.1 ✅
+
+Foundation release.
+
+- finalize core contracts
+- implement transport skeleton
+- implement 3 distinct adapters (datago, bok, kosis)
+- support XML + JSON
+- support discovery + list + raw
+- ship docs and contract tests
+
+## v0.2 ✅
+
+Stabilization and ergonomics.
+
+- dataset metadata enrichment
+- schema improvements
+- pandas adapter (`to_pandas()`)
+- single-page pagination contract + `list_all()`
+- more examples and documentation
+
+## v0.3 ✅
+
+Provider expansion.
+
+- localdata provider: 195개 인허가 데이터셋
+- sgis provider: 행정구역 경계 GeoJSON
+- semas provider: 상가(상권)정보 17개 데이터셋
+- seoul provider: 지하철 실시간, 따릉이
+- lofin provider: 6개 재정 데이터셋
+- datago provider: 부동산 실거래가, 관광, 지하철 어댑터 추가
+
+## v0.4 — Core 안정화
+
+- dataset metadata enrichment (#55)
+- schema improvements (#57)
+- more robust discovery (#63)
+- documentation (#59, #172)
+- integration tests (#80)
+
+## v0.5 — Provider 확장
+
+- datago: 실시간 도로교통정보 (#87), 농수축산물 가격정보 (#88)
+- datago: 건축물대장 (#90), 사업자등록 상태조회 (#91)
+- datago: 의약품 안전사용정보 (#92), 지하철역별 승하차 인원 (#93)
+- datago: 기상청 중기예보 (#94)
+- datago: 워크넷 채용정보 (#161), 긴급재난문자 (#162), 채권시세정보 (#163)
+- datago: NEIS 급식식단정보 (#164), 식품이력추적 (#165), 전국체육시설 (#166)
+- datago: 문화시설 (#167), 환경소음 측정망 (#168)
+
+## v1.0 criteria
+
+- public API feels stable
+- adapter contract proven across multiple provider families (7+ providers)
+- plugin discovery로 외부 provider 패키지 등록 가능
+- docs/examples sufficient for external users
+- breakage policy and versioning discipline established
+
+---
+
+## 본체에 포함하지 않는 것
+
+아래 항목은 kpubdata 코어에 넣지 않습니다. 필요 시 product family 별도 레포로 분리합니다.
+
+| 항목 | 분리 대상 레포 | 상태 |
+| :--- | :--- | :--- |
+| MCP adapter | `kpubdata-mcp` | 미생성 (필요 시 분리) |
+| HTTP/REST API 서비스 | `kpubdata-api` | 미생성 (필요 시 분리) |
+| LLM tool schema / agent helper | `kpubdata-mcp` | 미생성 (필요 시 분리) |
+
+---
+
+## 관련 문서
+
+### 이 저장소 내 문서
+| 문서 | 설명 |
+| :--- | :--- |
+| [PRD.md](./PRD.md) | 제품 요구사항 정의 |
+| [ARCHITECTURE.md](./ARCHITECTURE.md) | 시스템 아키텍처 설계 |
+| [API_SPEC.md](./API_SPEC.md) | 파이썬 API 명세 |
+
+### KPubData Product Family
+| 저장소 | 문서 | 설명 |
+| :--- | :--- | :--- |
+| [kpubdata-builder](https://github.com/yeongseon/kpubdata-builder) | [ROADMAP.md](https://github.com/yeongseon/kpubdata-builder/blob/main/ROADMAP.md) | Builder 로드맵 |
+| [kpubdata-studio](https://github.com/yeongseon/kpubdata-studio) | [ROADMAP.md](https://github.com/yeongseon/kpubdata-studio/blob/main/ROADMAP.md) | Studio 로드맵 |

{kpubdata-0.3.0 → kpubdata-0.4.0}/SUPPORTED_DATA.md

@@ -235,10 +235,27 @@
 | 지원 | 테스트 검증 | - | 지방행정인허가 (`localdata`) | `caregiver_training_institution` | 요양보호사교육기관 인허가 | [공공데이터포털](https://www.data.go.kr) 서비스키 | [data.go.kr](https://www.data.go.kr) | 행정안전부 제공, 기타/전문교육기관 |
 | 지원 | 테스트 검증 | - | 지방행정인허가 (`localdata`) | `funeral_director_training_institution` | 장례지도사교육기관 인허가 | [공공데이터포털](https://www.data.go.kr) 서비스키 | [data.go.kr](https://www.data.go.kr) | 행정안전부 제공, 기타/전문교육기관 |
 | 지원 | 테스트 검증 | - | 지방행정인허가 (`localdata`) | `free_job_placement` | 무료직업소개소 인허가 | [공공데이터포털](https://www.data.go.kr) 서비스키 | [data.go.kr](https://www.data.go.kr) | 행정안전부 제공, 기타/사무지원 |
-| 지원 | 테스트 검증 | - | 지방행정인허가 (`localdata`) | `paid_job_placement` | 유료직업소개소 인허가 | [공공데이터포털](https://www.data.go.kr) 서비스키 | [data.go.kr](https://www.data.go.kr) | 행정안전부 제공, 기타/사무지원 | 스키장업 인허가 | [공공데이터포털](https://www.data.go.kr) 서비스키 | [data.go.kr](https://www.data.go.kr) | 행정안전부 제공, KSIC R93 |
+| 지원 | 테스트 검증 | - | 지방행정인허가 (`localdata`) | `paid_job_placement` | 유료직업소개소 인허가 | [공공데이터포털](https://www.data.go.kr) 서비스키 | [data.go.kr](https://www.data.go.kr) | 행정안전부 제공, 기타/사무지원 |
 | 지원 | 테스트 검증 | - | 통계청 통계지리정보서비스 (`sgis`) | `boundary.sido` | 시도 행정구역 경계 | SGIS `consumer_key` + `consumer_secret` | [sgis.kostat.go.kr](https://sgis.kostat.go.kr/developer/html/main.html) | GeoJSON FeatureCollection 응답을 레코드 단위(`items`)로 정규화 |
 | 지원 | 테스트 검증 | - | 통계청 통계지리정보서비스 (`sgis`) | `boundary.sigungu` | 시군구 행정구역 경계 | SGIS `consumer_key` + `consumer_secret` | [sgis.kostat.go.kr](https://sgis.kostat.go.kr/developer/html/main.html) | `boundary/hadmarea.geojson` + `low_search` 기반 조회 |
 | 지원 | 테스트 검증 | - | 통계청 통계지리정보서비스 (`sgis`) | `boundary.emd` | 읍면동 행정구역 경계 | SGIS `consumer_key` + `consumer_secret` | [sgis.kostat.go.kr](https://sgis.kostat.go.kr/developer/html/main.html) | fixture/contract 검증 완료, 실API 검증은 후속 |
+| 지원 | 테스트 검증 | - | 소상공인시장진흥공단 (`semas`) | `zone_one` | 지정상권 조회 | [공공데이터포털](https://www.data.go.kr) 서비스키 | [data.go.kr](https://www.data.go.kr) | 상가(상권)정보 API / `storeZoneOne` |
+| 지원 | 테스트 검증 | - | 소상공인시장진흥공단 (`semas`) | `zone_radius` | 반경상권 조회 | [공공데이터포털](https://www.data.go.kr) 서비스키 | [data.go.kr](https://www.data.go.kr) | 상가(상권)정보 API / `storeZoneInRadius` |
+| 지원 | 테스트 검증 | - | 소상공인시장진흥공단 (`semas`) | `zone_rect` | 사각형상권 조회 | [공공데이터포털](https://www.data.go.kr) 서비스키 | [data.go.kr](https://www.data.go.kr) | 상가(상권)정보 API / `storeZoneInRectangle` |
+| 지원 | 테스트 검증 | - | 소상공인시장진흥공단 (`semas`) | `zone_admi` | 행정구역상권 조회 | [공공데이터포털](https://www.data.go.kr) 서비스키 | [data.go.kr](https://www.data.go.kr) | 상가(상권)정보 API / `storeZoneInAdmi` |
+| 지원 | 테스트 검증 | - | 소상공인시장진흥공단 (`semas`) | `store_one` | 단일상가 조회 | [공공데이터포털](https://www.data.go.kr) 서비스키 | [data.go.kr](https://www.data.go.kr) | 상가(상권)정보 API / `storeOne` |
+| 지원 | 테스트 검증 | - | 소상공인시장진흥공단 (`semas`) | `store_building` | 건물상가 조회 | [공공데이터포털](https://www.data.go.kr) 서비스키 | [data.go.kr](https://www.data.go.kr) | 상가(상권)정보 API / `storeListInBuilding` |
+| 지원 | 테스트 검증 | - | 소상공인시장진흥공단 (`semas`) | `store_pnu` | 지번상가 조회 | [공공데이터포털](https://www.data.go.kr) 서비스키 | [data.go.kr](https://www.data.go.kr) | 상가(상권)정보 API / `storeListInPnu` |
+| 지원 | 테스트 검증 | - | 소상공인시장진흥공단 (`semas`) | `store_dong` | 행정동상가 조회 | [공공데이터포털](https://www.data.go.kr) 서비스키 | [data.go.kr](https://www.data.go.kr) | 상가(상권)정보 API / `storeListInDong` |
+| 지원 | 테스트 검증 | - | 소상공인시장진흥공단 (`semas`) | `store_area` | 상권상가 조회 | [공공데이터포털](https://www.data.go.kr) 서비스키 | [data.go.kr](https://www.data.go.kr) | 상가(상권)정보 API / `storeListInArea` |
+| 지원 | 테스트 검증 | - | 소상공인시장진흥공단 (`semas`) | `store_radius` | 반경상가 조회 | [공공데이터포털](https://www.data.go.kr) 서비스키 | [data.go.kr](https://www.data.go.kr) | 상가(상권)정보 API / `storeListInRadius` |
+| 지원 | 테스트 검증 | - | 소상공인시장진흥공단 (`semas`) | `store_rect` | 사각형상가 조회 | [공공데이터포털](https://www.data.go.kr) 서비스키 | [data.go.kr](https://www.data.go.kr) | 상가(상권)정보 API / `storeListInRectangle` |
+| 지원 | 테스트 검증 | - | 소상공인시장진흥공단 (`semas`) | `store_polygon` | 다각형상가 조회 | [공공데이터포털](https://www.data.go.kr) 서비스키 | [data.go.kr](https://www.data.go.kr) | 상가(상권)정보 API / `storeListInPolygon` |
+| 지원 | 테스트 검증 | - | 소상공인시장진흥공단 (`semas`) | `store_upjong` | 업종별상가 조회 | [공공데이터포털](https://www.data.go.kr) 서비스키 | [data.go.kr](https://www.data.go.kr) | 상가(상권)정보 API / `storeListInUpjong` |
+| 지원 | 테스트 검증 | - | 소상공인시장진흥공단 (`semas`) | `store_date` | 수정일자상가 조회 | [공공데이터포털](https://www.data.go.kr) 서비스키 | [data.go.kr](https://www.data.go.kr) | 상가(상권)정보 API / `storeListByDate` |
+| 지원 | 테스트 검증 | - | 소상공인시장진흥공단 (`semas`) | `upjong_large` | 업종대분류 조회 | [공공데이터포털](https://www.data.go.kr) 서비스키 | [data.go.kr](https://www.data.go.kr) | 상가(상권)정보 API / `largeUpjongList` |
+| 지원 | 테스트 검증 | - | 소상공인시장진흥공단 (`semas`) | `upjong_middle` | 업종중분류 조회 | [공공데이터포털](https://www.data.go.kr) 서비스키 | [data.go.kr](https://www.data.go.kr) | 상가(상권)정보 API / `middleUpjongList` |
+| 지원 | 테스트 검증 | - | 소상공인시장진흥공단 (`semas`) | `upjong_small` | 업종소분류 조회 | [공공데이터포털](https://www.data.go.kr) 서비스키 | [data.go.kr](https://www.data.go.kr) | 상가(상권)정보 API / `smallUpjongList` |
 | 지원 | 테스트 검증 | - | 서울 열린데이터광장 (`seoul`) | `subway_realtime_arrival` | 서울시 지하철 실시간 도착정보 | [서울 열린데이터광장](https://data.seoul.go.kr/) 인증키 | [data.seoul.go.kr](https://data.seoul.go.kr/) | 경로 기반 인증키 + 서비스별 top-level envelope |
 | 지원 | 테스트 검증 | - | 서울 열린데이터광장 (`seoul`) | `bike_rent_month` | 서울시 공공자전거 이용정보(월별) | [서울 열린데이터광장](https://data.seoul.go.kr/) 인증키 | [data.seoul.go.kr](https://data.seoul.go.kr/) | 경로 기반 인증키 + 인덱스 페이지네이션 |
 | 지원 | 실API 검증 | 2025-04-15 | 한국은행 ECOS (`bok`) | `base_rate` | 한국은행 기준금리 | [ECOS](https://ecos.bok.or.kr/api/) 인증키 | [ecos.bok.or.kr](https://ecos.bok.or.kr/api/) | |

{kpubdata-0.3.0 → kpubdata-0.4.0}/docs/product-family-architecture.md

@@ -8,7 +8,7 @@ KPubData Product Family(Korea Public Data Product Family)는 한국 공공데이
 | :--- | :--- | :--- |
 | [kpubdata](https://github.com/yeongseon/kpubdata) | 공공데이터를 가져오고 표준화하는 코어 라이브러리 | Python 3.10+ |
 | [kpubdata-builder](https://github.com/yeongseon/kpubdata-builder) | 수집된 데이터를 다양한 형식으로 가공하는 빌드 파이프라인 | Python 3.10+ |
-| [kpubdata-studio](https://github.com/yeongseon/kpubdata-studio) | 빌드 과정을 시각적으로 관리하는 웹 대시보드 | Next.js 15 + TypeScript |
+| [kpubdata-studio](https://github.com/yeongseon/kpubdata-studio) | 빌드 과정을 시각적으로 관리하는 웹 대시보드 | Vite + React Router + TypeScript (SPA) |
 
 ---
 
@@ -52,7 +52,7 @@ graph TD
     U3([파이썬 개발자]) -->|Python SDK| Core
 
     subgraph "KPubData Product Family"
-        Studio["kpubdata-studio<br/>웹 대시보드<br/>(Next.js 15 + TypeScript)"]
+        Studio["kpubdata-studio<br/>웹 대시보드<br/>(Vite + React Router + TypeScript (SPA))"]
         Builder["kpubdata-builder<br/>데이터 빌드 파이프라인<br/>(Python 3.10+)"]
         Core["kpubdata<br/>데이터 접속 코어<br/>(Python 3.10+)"]
     end
@@ -180,9 +180,9 @@ graph LR
 | 항목 | kpubdata | kpubdata-builder | kpubdata-studio |
 | :--- | :--- | :--- | :--- |
 | **언어** | [Python](https://docs.python.org/ko/3/tutorial/) 3.10+ | [Python](https://docs.python.org/ko/3/tutorial/) 3.10+ | [TypeScript](https://www.typescriptlang.org/ko/docs/) 5 |
-| **프레임워크** | — (순수 라이브러리) | — (CLI + 라이브러리) | [Next.js](https://nextjs.org/docs) 15 |
+| **프레임워크** | — (순수 라이브러리) | — (CLI + 라이브러리) | [Vite](https://vite.dev/) + [React Router](https://reactrouter.com/) |
 | **UI** | 없음 (코드로만 사용) | CLI(명령줄 인터페이스) | 웹 브라우저 ([React](https://ko.react.dev/) + [Tailwind CSS](https://tailwindcss.com/docs)) |
-| **빌드 도구** | [hatchling](https://hatch.pypa.io/) | [hatchling](https://hatch.pypa.io/) | Next.js 내장 빌드 |
+| **빌드 도구** | [hatchling](https://hatch.pypa.io/) | [hatchling](https://hatch.pypa.io/) | Vite 내장 빌드 |
 | **패키지 관리** | [uv](https://github.com/astral-sh/uv) | [uv](https://github.com/astral-sh/uv) | [npm](https://docs.npmjs.com/about-npm) |
 | **타입 검사** | [mypy](https://mypy.readthedocs.io/) | [mypy](https://mypy.readthedocs.io/) | TypeScript 내장 (`tsc`) |
 | **린터** | [ruff](https://docs.astral.sh/ruff/) | [ruff](https://docs.astral.sh/ruff/) | [ESLint](https://eslint.org/) |
@@ -198,7 +198,7 @@ graph LR
 graph TD
     subgraph "사용자 환경 (브라우저)"
         direction TB
-        StudioUI["kpubdata-studio<br/>Next.js 웹 앱<br/>(사용자가 직접 보는 화면)"]
+        StudioUI["kpubdata-studio<br/>Vite SPA<br/>(사용자가 직접 보는 화면)"]
     end
 
     subgraph "서버 환경 (Python Runtime)"
@@ -223,7 +223,7 @@ graph TD
 
 | 환경 | 프로젝트 | 실행 방식 |
 | :--- | :--- | :--- |
-| **사용자 브라우저** | kpubdata-studio | `npm run dev` → [http://localhost:3000](http://localhost:3000) 접속 |
+| **사용자 브라우저** | kpubdata-studio | `npm run dev` → [http://localhost:5173](http://localhost:5173) 접속 |
 | **Python 서버/로컬** | kpubdata, kpubdata-builder | `pip install` 후 Python 코드에서 import 또는 CLI 실행 |
 | **외부** | 공공 데이터 API | 정부/기관에서 운영하는 서버 (우리가 제어할 수 없음) |
 
@@ -318,7 +318,7 @@ Studio (브라우저)                    Builder (서버)
 | :--- | :--- | :--- | :--- |
 | **v0.1** | 동기 코어, 주요 5개 API 어댑터, XML/JSON 지원 | BuildSpec 모델, Markdown 내보내기, Manifest 생성 | 정보 구조 설계, Draft 상태 관리, Builder API 연동 |
 | **v0.2** | 메타데이터 보강, Pandas 어댑터, 신규 기관 확대 | JSONL/Parquet 내보내기, HuggingFace 레이아웃 | 실시간 미리보기, 데이터 검증 뷰, 결과물 뷰어 |
-| **v0.3** | 경량 MCP 어댑터 지원 | Publish 훅, 빌드 이력 관리, CI/CD 연동 | Publish 워크플로우, 전체 대시보드 |
+| **v0.3** | Provider 확장 (datago 부동산, 관광, 지하철) | Publish 훅, 빌드 이력 관리, CI/CD 연동 | Publish 워크플로우, 전체 대시보드 |
 
 ---
 
@@ -331,7 +331,7 @@ A: 네. kpubdata는 독립적인 파이썬 라이브러리입니다. `pip instal
 A: 아니요. Studio는 Builder의 API를 호출하여 동작하므로, Builder가 반드시 실행되고 있어야 합니다. Studio는 "화면"이고, Builder가 실제 "엔진"입니다.
 
 **Q: 세 프로젝트를 한 컴퓨터에서 동시에 실행해야 하나요?**
-A: 개발 환경에서는 한 컴퓨터에서 모두 실행할 수 있습니다. 운영 환경에서는 Builder(Python 서버)와 Studio(Next.js 웹 서버)를 별도 서버에 배포하는 것이 일반적입니다.
+A: 개발 환경에서는 한 컴퓨터에서 모두 실행할 수 있습니다. 운영 환경에서는 Builder(Python 서버)와 Studio(Vite 웹 서버)를 별도 서버에 배포하는 것이 일반적입니다.
 
 **Q: 새로운 공공 API를 추가하려면 어디를 수정하나요?**
 A: kpubdata의 `providers/` 디렉토리에 새 어댑터를 추가합니다. Builder와 Studio는 수정할 필요 없이 자동으로 새 데이터셋을 사용할 수 있게 됩니다. 이것이 의존성이 한 방향인 것의 장점입니다.
@@ -366,4 +366,5 @@ A: kpubdata의 `providers/` 디렉토리에 새 어댑터를 추가합니다. Bu
 | YAML | 들여쓰기로 구조를 표현하는 설정 파일 형식 | [위키백과](https://ko.wikipedia.org/wiki/YAML) |
 | Python | 읽기 쉬운 범용 프로그래밍 언어 | [공식 튜토리얼 (한국어)](https://docs.python.org/ko/3/tutorial/) |
 | TypeScript | 자바스크립트에 타입을 추가한 언어 | [공식 문서 (한국어)](https://www.typescriptlang.org/ko/docs/) |
-| Next.js | React 기반 웹 애플리케이션 프레임워크 | [공식 문서](https://nextjs.org/docs) |
+| Vite | 빠른 프론트엔드 개발 서버 및 번들러 | [공식 문서](https://vite.dev/) |
+| React Router | SPA 라우팅 라이브러리 | [공식 문서](https://reactrouter.com/) |

{kpubdata-0.3.0 → kpubdata-0.4.0}/docs/providers/datago.md

@@ -35,7 +35,7 @@
 
 ### 3단계: 승인 대기
 
-- **자동 승인**: 기상청, 한국환경공단 등 대부분의 API는 신청 즉시 자동 승인됩니다.
+- **자동 승인**: 대부분의 API는 활용신청 후 약 1~5분 안에 자동 승인됩니다.
 - **심의 승인**: 국토교통부 아파트매매 실거래가 등 일부 API는 담당 기관의 심의 후 승인까지 1~2일이 소요될 수 있습니다.
 
 ### 4단계: 인증키 확인
@@ -52,16 +52,22 @@
 export KPUBDATA_DATAGO_API_KEY="발급받은-일반-인증키"
 ```
 
-### 6단계: 키 활성화 대기
+## API별 활용신청(활성화) requirement
 
-**중요: API 키는 발급 직후 바로 사용할 수 없습니다.**
+data.go.kr은 **계정용 공통 인증키 1개만 있으면 끝나는 구조가 아닙니다.** 호출하려는 Open API마다 상세 페이지에서 별도로 **활용신청**을 해야 합니다.
 
-- 발급 후 **1~2시간**의 활성화 대기 시간이 필요합니다.
-- 이 시간 동안 공공데이터포털 시스템이 각 API 제공기관의 서버와 인증키를 동기화합니다.
-- 동기화 완료 전에는 `SERVICE_KEY_IS_NOT_REGISTERED_ERROR` 또는 `401 Unauthorized` 에러가 발생합니다.
-- 동기화 시간은 제공기관에 따라 다를 수 있으며, 드물게 2시간 이상 걸리는 경우도 있습니다.
+- 같은 `KPUBDATA_DATAGO_API_KEY`를 쓰더라도 API별 활성화 상태는 서로 다를 수 있습니다.
+- 활용신청 후 대부분의 API는 약 **1~5분 안에 자동 승인/활성화**됩니다.
+- 활성화 전에는 KPubData 호출이 **HTTP 403**으로 실패할 수 있습니다.
+- 이 경우 해당 데이터셋의 data.go.kr 상세 페이지로 가서 **"활용신청"** 버튼을 눌렀는지 먼저 확인하세요.
 
-### 7단계: 활성화 확인
+예시:
+
+- `datago.village_fcst`를 쓰려면 단기예보 API 페이지에서 활용신청 필요
+- `datago.air_quality`를 쓰려면 대기오염정보 API 페이지에서 활용신청 필요
+- 둘은 같은 포털/같은 키를 써도 **각각 따로** 활성화해야 함
+
+### 6단계: 활성화 확인
 
 키가 활성화되었는지 확인하려면 다음과 같이 테스트합니다:
 
@@ -70,7 +76,7 @@ export KPUBDATA_DATAGO_API_KEY="발급받은-일반-인증키"
 curl "http://apis.data.go.kr/1360000/VilageFcstInfoService_2.0/getVilageFcst?serviceKey=YOUR_KEY&dataType=json&numOfRows=1&pageNo=1&base_date=20250401&base_time=0500&nx=55&ny=127"
 ```
 
-정상 응답이 오면 활성화가 완료된 것입니다. `SERVICE_KEY_IS_NOT_REGISTERED_ERROR` 에러가 나오면 조금 더 기다려야 합니다.
+정상 응답이 오면 활성화가 완료된 것입니다. `403 Forbidden`, `SERVICE_KEY_IS_NOT_REGISTERED_ERROR`, 또는 인증 관련 오류가 나오면 활용신청 여부와 승인 대기 시간을 다시 확인하세요.
 
 ## KPubData에서 신청해야 할 API 목록
 

{kpubdata-0.3.0 → kpubdata-0.4.0}/docs/quickstart.md

@@ -117,6 +117,12 @@ ProviderResponseError: BOK ECOS returned error
 ```
 → 날짜를 `"20240101"` 대신 `"202401"` (YYYYMM) 형식으로 입력했는지 확인하세요.
 
+### "data.go.kr에서 403이 나옵니다"
+```
+AuthError: data.go.kr returned 403...
+```
+→ data.go.kr은 공통 인증키만으로는 부족하고 **API별 활용신청**이 필요합니다. 사용하려는 API 상세 페이지에서 "활용신청"을 눌렀는지 확인하세요. 대부분 1~5분 안에 자동 승인되지만 일부 API는 더 오래 걸릴 수 있습니다.
+
 ## Step 7: 다른 데이터도 조회해보기
 
 ### 사용 가능한 전체 데이터셋 목록 보기
@@ -146,6 +152,8 @@ kosis.population_migration — 시도별 이동자수 (Population Migration)
 - 공공데이터포털(datago): [datago API 키 발급 가이드](./providers/datago.md)
 - 통계청 KOSIS: [KOSIS API 키 발급 가이드](./providers/kosis.md)
 
+> 참고: `datago`는 인증키 발급 후에도 **데이터셋별 활용신청**이 필요합니다. 활용신청 전에는 403이 발생할 수 있습니다.
+
 ## Step 8: 전체 페이지 자동 조회
 
 데이터가 많을 때 `list_all()`을 사용하면 모든 페이지를 자동으로 순회합니다.

{kpubdata-0.3.0 → kpubdata-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "kpubdata"
-version = "0.3.0"
+version = "0.4.0"
 description = "Dialect-inspired Python access framework for Korean public data"
 readme = "README.md"
 requires-python = ">=3.10"

{kpubdata-0.3.0 → kpubdata-0.4.0}/src/kpubdata/__init__.py

@@ -49,4 +49,6 @@ __all__ = [
     "ProviderNotRegisteredError",
 ]
 
-__version__ = "0.2.3"
+from importlib.metadata import version as _pkg_version
+
+__version__: str = _pkg_version("kpubdata")

{kpubdata-0.3.0 → kpubdata-0.4.0}/src/kpubdata/client.py

@@ -26,6 +26,7 @@ _BUILTIN_PROVIDERS: tuple[tuple[str, str, str], ...] = (
     ("kosis", "kpubdata.providers.kosis", "KosisAdapter"),
     ("lofin", "kpubdata.providers.lofin", "LofinAdapter"),
     ("localdata", "kpubdata.providers.localdata.adapter", "LocaldataAdapter"),
+    ("semas", "kpubdata.providers.semas.adapter", "SemasAdapter"),
 )
 
 

{kpubdata-0.3.0 → kpubdata-0.4.0}/src/kpubdata/config.py

@@ -4,6 +4,9 @@ Key lookup order for provider keys:
 1. Explicit `provider_keys` dict passed to constructor
 2. Environment variable: KPUBDATA_{PROVIDER}_API_KEY (uppercased)
 3. Environment variable: {PROVIDER}_API_KEY (uppercased, fallback)
+
+data.go.kr providers (localdata, lofin, semas) all use the "datago" key.
+Set KPUBDATA_DATAGO_API_KEY once for all data.go.kr-based providers.
 """
 
 from __future__ import annotations

{kpubdata-0.3.0 → kpubdata-0.4.0}/src/kpubdata/providers/datago/adapter.py

@@ -7,6 +7,8 @@ from collections.abc import Mapping, Sequence
 from typing import NoReturn, cast
 from urllib.parse import urlparse
 
+import httpx
+
 from kpubdata.config import KPubDataConfig
 from kpubdata.core.models import (
     DatasetRef,
@@ -22,6 +24,7 @@ from kpubdata.exceptions import (
     ProviderResponseError,
     RateLimitError,
     ServiceUnavailableError,
+    TransportError,
 )
 from kpubdata.providers._common import build_schema_from_metadata, coerce_int, load_catalogue
 from kpubdata.transport.decode import decode_json, decode_xml, detect_content_type
@@ -29,6 +32,12 @@ from kpubdata.transport.http import HttpTransport, TransportConfig
 
 logger = logging.getLogger("kpubdata.provider.datago")
 
+_DATAGO_403_HINT = (
+    "data.go.kr returned 403. This usually means the specific API has not been activated "
+    "(활용신청) for your key. Visit the dataset's page on https://www.data.go.kr and "
+    "click '활용신청'. Approval is usually automatic and becomes active within a few minutes."
+)
+
 
 def _is_success_code(code: str) -> bool:
     """Return True for any data.go.kr resultCode that signals success.
@@ -362,13 +371,23 @@ class DataGoAdapter:
         self, url: str, params: Mapping[str, object], dataset_id: str = ""
     ) -> dict[str, object]:
         string_params = {key: str(value) for key, value in params.items()}
-        response = self._transport.request(
-            "GET",
-            url,
-            params=string_params,
-            dataset_id=dataset_id,
-            provider="datago",
-        )
+        try:
+            response = self._transport.request(
+                "GET",
+                url,
+                params=string_params,
+                dataset_id=dataset_id,
+                provider="datago",
+            )
+        except TransportError as exc:
+            if self._is_http_403(exc):
+                raise AuthError(
+                    _DATAGO_403_HINT,
+                    provider="datago",
+                    dataset_id=dataset_id or None,
+                    status_code=403,
+                ) from exc
+            raise
 
         try:
             content_type = detect_content_type(response)
@@ -394,6 +413,11 @@ class DataGoAdapter:
         )
         raise ParseError("Decoded payload is not an object", provider="datago")
 
+    @staticmethod
+    def _is_http_403(exc: TransportError) -> bool:
+        cause = exc.__cause__
+        return isinstance(cause, httpx.HTTPStatusError) and cause.response.status_code == 403
+
     def _validate_envelope(
         self, payload: dict[str, object], dataset: DatasetRef | None = None
     ) -> tuple[dict[str, object], list[dict[str, object]]]:

{kpubdata-0.3.0 → kpubdata-0.4.0}/src/kpubdata/providers/localdata/adapter.py

@@ -160,7 +160,7 @@ class LocaldataAdapter:
         return payload
 
     def _require_api_key(self) -> str:
-        return self._config.require_provider_key("localdata")
+        return self._config.require_provider_key("datago")
 
     def _build_request_url(self, dataset: DatasetRef, operation: str | None = None) -> str:
         base_url_raw = dataset.raw_metadata.get("base_url")

{kpubdata-0.3.0 → kpubdata-0.4.0}/src/kpubdata/providers/lofin/adapter.py

@@ -164,7 +164,7 @@ class LofinAdapter:
         return payload
 
     def _require_api_key(self) -> str:
-        return self._config.require_provider_key("lofin")
+        return self._config.require_provider_key("datago")
 
     def _build_request_url(
         self,

kpubdata-0.4.0/src/kpubdata/providers/semas/__init__.py

@@ -0,0 +1,3 @@
+from __future__ import annotations
+
+__all__: list[str] = []