Korea Data Suite

韩国数据套件

English | 한국어

面向开发者的韩国公共数据 REST API，简洁易用。 韩国政府开放数据功能强大，但难以使用：文档只有韩文、响应为 XML、身份验证方式陈旧。本套件将其规范化为简单的 JSON API。

▶ 在 RapidAPI 上试用 — 免费套餐，无需设置。 托管并自动更新；使用的代码与本仓库相同。AI Agent 可在 MCP Registry 上使用：uvx korea-data-mcp。

API

API	状态	说明
节假日与工作日	✅ v1	韩国公共假日（包括替代假日和临时假日）以及工作日计算
房地产交易	✅ v1	规范化的 MOLIT 实际交易价格（公寓／办公住宅／土地，买卖与租赁）——覆盖全国（261 个 sigungu）
地址工具包	🚧 planned	道路地址／地块地址转换、罗马化
企业注册	🚧 planned	企业注册号（BRN）验证与补充信息

快速开始

托管服务（推荐） — 由我们维护的实例，提供免费套餐，无需设置：

→ 在 RapidAPI 上订阅，获取密钥并调用任意端点。RapidAPI 会自动注入密钥 — 从其 Code Snippets 面板复制即用代码片段即可。

	RapidAPI（托管）	自托管
设置	几秒内获取 API 密钥	data.go.kr 密钥 + 服务 + cron
数据刷新	自动（由我们运行同步）	由你管理调度程序
费用	免费套餐，之后收费	免费（使用你自己的基础设施）

两者运行的都是完全相同的代码（本仓库）。如果你不想运维数据管道，请选择 RapidAPI；如果你希望完全掌控，请选择自托管。

自托管

uv sync
uv run uvicorn app.main:app --port 8642
curl "http://127.0.0.1:8642/v1/health"

节假日与工作日 API

# All holidays in a year (or a month)
curl "http://127.0.0.1:8642/v1/holidays?year=2026" -H "X-API-Key: <key>"

# Is a given date a holiday / business day?
curl "http://127.0.0.1:8642/v1/holidays/check?date=2026-03-02" -H "X-API-Key: <key>"

# Add N business days (skips weekends & holidays)
curl "http://127.0.0.1:8642/v1/business-days/add?date=2026-12-31&days=1" -H "X-API-Key: <key>"

# Count business days in a range (inclusive)
curl "http://127.0.0.1:8642/v1/business-days/count?start=2026-09-21&end=2026-09-27" -H "X-API-Key: <key>"

涵盖法定公共假日、替代假日（대체공휴일）、 临时假日（임시공휴일）和选举日 — 这些正是大多数 全球节假日 API 在处理韩国数据时容易出错的情况。

房地产交易 API

规范化的 MOLIT（土地部）实际交易价格 — 包括公寓、 办公住宅和土地；买卖、全租和月租 — 以简洁的英文 JSON 格式提供， 并支持游标分页。

# Real transaction prices (apartment sales in Gangnam-gu)
curl "http://127.0.0.1:8642/v1/realestate/transactions?region=11680&property_type=apartment&trade_type=sale" -H "X-API-Key: <key>"

# Filter by date range + paginate with the returned cursor
curl "http://127.0.0.1:8642/v1/realestate/transactions?region=11680&date_from=2026-01-01&limit=50&cursor=<next_cursor>" -H "X-API-Key: <key>"

# Region codes (LAWD 5-digit)
curl "http://127.0.0.1:8642/v1/realestate/regions" -H "X-API-Key: <key>"

每日同步会导入当前月和上个月的数据；如需历史数据，请使用回填 CLI：

uv run python scripts/backfill.py --from 2025-01 --to 2025-12 --regions 11680,11650

配置

环境变量（前缀为 KDS_，支持 .env）：

变量	默认值	说明
KDS_DEV_MODE	false	跳过 API 密钥验证（本地开发）
KDS_API_KEYS	—	以逗号分隔的受认可 API 密钥
KDS_PROXY_SECRETS	—	以逗号分隔的市场代理密钥
KDS_DB_PATH	data/kds.db	SQLite 路径
KDS_DATA_GO_KR_KEY	—	data.go.kr 服务密钥（可选；启用节假日与房地产数据同步）
KDS_ENABLE_SCHEDULER	true	节假日（每周）+ 房地产（每日）同步调度程序
KDS_RE_REGIONS	all 261 nationwide sigungu	以逗号分隔的 LAWD 代码，用于同步（覆盖子集）
KDS_RE_DATASETS	all	以逗号分隔的数据集键（apt_trade、apt_rent、offi_trade、offi_rent、land_trade）

数据来源与署名

• 节假日数据：KASI 特殊日信息（한국천문연구원 특일정보）， 通过 韩国公共数据门户（data.go.kr） 获取 — KOGL Type 1。 附带捆绑种子数据（2025–2027）；配置服务密钥后每周刷新。
• 实际交易数据：MOLIT 实际交易价格公开系统（국토교통부）， 通过 韩国公共数据门户（data.go.kr） 获取 — KOGL Type 1。

在 macOS 上作为守护进程运行

# Install & start (auto-restart on crash, start at login)
./scripts/install-daemon.sh

# With Cloudflare Tunnel (after one-time `cloudflared tunnel login/create`)
./scripts/install-daemon.sh --with-tunnel

# Logs
tail -f ~/Library/Logs/kds/api.out.log

# Uninstall
launchctl bootout "gui/$(id -u)" ~/Library/LaunchAgents/com.choiyounggi.kds-api.plist
rm ~/Library/LaunchAgents/com.choiyounggi.kds-api.plist

如需在提供服务期间保持机器唤醒，请禁用系统睡眠 （sudo pmset -a sleep 0），或使用专用的常开设备。 如需通过 Cloudflare Tunnel 暴露 API 而不开放端口，请参阅 deploy/cloudflared.example.yml。

处理并发流量

读路径和写路径相互分离，因此流量可以独立扩展：

• 采用 WAL 模式的 SQLite（初始化时设置一次）+ busy_timeout — 读操作不会阻塞每日写入，反之亦然；多个读取工作进程也可以并发运行。
• API 进程只读，支持多工作进程。 scripts/run.sh 使用 --workers ${KDS_WORKERS:-2} 和 KDS_ENABLE_SCHEDULER=false 运行 uvicorn。每个工作进程都是独立的进程（拥有独立的 GIL）；WAL 让它们可以同时读取。提高 KDS_WORKERS 的值即可利用更多核心扩展读取能力。
• 每日数据导入作为独立进程运行，由 scripts/sync.py 在 04:00 通过 com.choiyounggi.kds-sync 执行 — 不会在 API 服务内运行，因此数千行数据的批量处理不会与请求处理争用 GIL。
• 边缘缓存（可选）：响应中包含 Cache-Control: no-store，以确保安全。房地产数据是公开的，且每天最多更新一次 — 如果源站负载增加，可使用较短的 Cache-Control: public, max-age=... 提供数据，并让 CDN 承担读取流量。

对外开放前的安全检查清单

应用在代码层面已加固（API 密钥认证默认拒绝、参数化 SQL、严格的输入验证、每个响应都包含安全标头，包括 5xx 响应、默认关闭文档和架构、错误信息经过清理）。以下是开放隧道前必须落实的边缘／部署职责：

• 切勿在生产环境中设置 KDS_DEV_MODE=true — 这会禁用所有身份验证。如果启用，应用会在启动时记录警告。
• 在隧道主机名上配置 Cloudflare 速率限制 + WAF — 按设计，应用没有应用层速率限制（这属于边缘职责）。
• HSTS + TLS 在 Cloudflare 边缘终止；请确认已在那里启用 HSTS（源站仅在 127.0.0.1 上提供纯 HTTP）。
• 生产环境中保持 KDS_ENABLE_DOCS 未设置（或设为 false）；仅在需要由源站提供 /docs /openapi.json 时设为 true。

SEO 营销网站（程序化生成）

scripts/gen_site.py 会根据实时数据库生成一个静态、经过 SEO 优化的营销网站。对于每个包含真实交易数据的地区，都会生成一个韩语落地页（用户实际会搜索的查询词——“강남구 아파트 실거래가 API”——页面内容由真实的 MOLIT 统计数据、可运行的 curl 示例和注册 CTA 支撑），此外还会生成一个节假日主题页、一个首页、sitemap.xml 和 robots.txt。

**质量门槛（重要）：**只有公寓销售记录至少达到 MIN_SALE_ROWS（30）行的地区才会发布。数据不足的地区会被跳过 — 这是为了避免内容单薄或仅用于引流的页面，以免受到搜索引擎惩罚。

# generate into site/dist (reads data/kds.db)
uv run python scripts/gen_site.py --out site/dist

配置由环境变量驱动，因此同一个生成器可用于任何域名（将以下变量放在 deploy/site.env 中，此文件已加入 gitignore — 可从 deploy/site.env.example 复制）：

环境变量	含义
KDS_SITE_URL	规范 URL／站点地图基址，例如 https://korea-data.cloud
KDS_API_ORIGIN	页面上 curl 示例中显示的源站，例如 https://api.korea-data.cloud
KDS_CTA_URL	注册行动号召链接（RapidAPI / Zyla / Postman listing）
KDS_SITE_DIR	应用提供服务的输出目录（默认 site/dist）

服务 — API 应用提供服务

FastAPI 应用在所有非 API 路径上提供 site/dist（app.mount("/")）， 而 /v1/* 仍作为 JSON API。两者的响应标头不同：API 保留锁定严格的 default-src 'none' CSP 和 no-store；网站使用可渲染 HTML 的 CSP（script-src 'none'，允许内联样式）和 public 缓存。 每次请求都会从磁盘读取文件，因此重新生成网站后会立即生效，无需重启应用——只有代码变更才需要重启。

网站与 API 托管在同一主机（api.korea-data.cloud）——API 位于 /v1 下， 网站则位于其他所有路径——因此无需新增隧道主机名或 DNS。只需在服务主机上执行一次：

cp deploy/site.env.example deploy/site.env    # KDS_SITE_URL == KDS_API_ORIGIN == https://api.korea-data.cloud
uv run python scripts/gen_site.py --out site/dist   # generate once
# restart the API app so this integration (new code) takes effect — the site is
# then live at https://api.korea-data.cloud/ , /holidays/ , /realestate/... .

在 Google Search Console 中提交一次 https://api.korea-data.cloud/sitemap.xml。

之后想把网站放在纯域名 korea-data.cloud / www 上？添加一条 ingress 规则， 将该主机名指向同一个 http://127.0.0.1:8642，配置其 DNS，然后将 KDS_SITE_URL 改为该地址。不是必需的——目前使用 API 主机也能满足 SEO 需求。

首次运行需要历史数据：每日同步只会导入当月数据。若要让页面拥有足够的历史深度， 请先回填一次数据—— uv run python scripts/backfill.py --from 2025-07 --to 2026-06 --regions <codes> --datasets apt_trade,apt_rent。

自动化（macOS 守护进程）

deploy/com.choiyounggi.kds-site.plist 会在每天 04:30（紧接 04:00 的同步之后）通过 scripts/publish_site.sh 重新生成网站。由于应用直接从磁盘提供服务， 更新后的页面会立即生效——无需重启，也无需外部部署：

cp deploy/com.choiyounggi.kds-site.plist ~/Library/LaunchAgents/
launchctl bootstrap "gui/$(id -u)" ~/Library/LaunchAgents/com.choiyounggi.kds-site.plist
tail -f ~/Library/Logs/kds/site.out.log

可用性提示：由于网站由本地应用提供服务（而非 CDN），其 SEO 可用性取决于运行主机—— 请保持主机唤醒以提供服务（使用 pmset，API 已有此要求）。如果之后需要始终在线的托管， 也可以将同一个 site/dist 推送到 Cloudflare Pages。

MCP 服务（AI Agent 访问）

API 也打包成独立的 Model Context Protocol 服务——packages/korea-data-mcp/——让 AI Agent （Claude Desktop/Code、Cursor 等）可以直接发现并调用各个端点。它是独立的精简软件包（依赖：mcp、httpx）， 也是发布到 PyPI / 收录到 MCP Registry 的软件包。

快速添加（发布到 PyPI 之前，直接使用此代码库——用户自行提供密钥）：

claude mcp add korea-data-suite --env KDS_API_KEY=<key> \
  -- uvx --from "git+https://github.com/choiyounggi/korea-data-suite#subdirectory=packages/korea-data-mcp" korea-data-mcp

工具、客户端配置以及 uvx korea-data-mcp（发布到 PyPI 后）的相关信息，请参阅 packages/korea-data-mcp/README.md。

许可证

MIT © choiyounggi