Korea Data Suite

Korea Data Suite

英語 | 한국어

韓国の公共データを扱う、使いやすく開発者に優しい REST API です。 韓国政府のオープンデータは強力ですが、韓国語のみのドキュメント、XML レスポンス、 レガシーな認証方式など、利用が困難です。このスイートは、データをシンプルな JSON API に正規化します。

▶ RapidAPI で試す — 無料プラン、セットアップ不要。 ホスティングされ、自動更新されます。このリポジトリと同じコードを使用しています。AI エージェント向けには、MCP Registry に登録されています — uvx korea-data-mcp。

API

API	状態	説明
祝日・営業日	✅ v1	韓国の祝日（振替休日・臨時休日を含む）と営業日の計算
不動産取引	✅ v1	正規化された MOLIT の実取引価格（アパート・オフィステル・土地、売買・賃貸）— 全国（261 の市郡区）
住所ツールキット	🚧 計画中	道路名住所・地番住所の変換、ローマ字表記
事業者登録	🚧 計画中	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	全国の全 261 市郡区	同期する LAWD コード（カンマ区切り。対象を指定する場合）
KDS_RE_DATASETS	すべて	データセットキー（カンマ区切り。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 は uvicorn を --workers ${KDS_WORKERS:-2} および KDS_ENABLE_SCHEDULER=false で実行します。各ワーカーは独立したプロセス（個別の GIL）です。WAL により、すべてのワーカーが同時に読み取れます。コア数に合わせて読み取りをスケールするには、KDS_WORKERS の値を増やしてください。
• 日次の取り込みは独立したプロセスとして実行します（com.choiyounggi.kds-sync、04:00）。scripts/sync.py を通じて実行するため、API サーバー内では動作しません。そのため、数千行に及ぶバッチがリクエスト処理と GIL を奪い合うことはありません。
• エッジキャッシュ（任意）：セキュリティのため、レスポンスには Cache-Control: no-store が設定されています。不動産データは公開情報で、更新は最大でも 1 日に 1 回です。オリジンサーバーの負荷が増加した場合は、短い 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 マーケティングサイト（プログラム生成）

静的な SEO 最適化マーケティングサイトは、scripts/gen_site.py によってライブ DB から生成されます。実際の取引データがあるすべての地域について、韓国語のランディングページを生成します（ユーザーが実際に検索する「강남구 아파트 실거래가 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 の掲載ページ）
KDS_SITE_DIR	アプリが配信する出力ディレクトリ（デフォルトは site/dist）

配信 — API アプリがサイトを配信します

FastAPI アプリは、site/dist をすべての非 API パスで配信します（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 のルートドメインで公開したい場合は、そのホスト名を同じ http://127.0.0.1:8642 に向けるイングレスルールを追加し、DNS を設定して、KDS_SITE_URL をその URL に切り替えてください。必須ではありません。SEO 対策には現在の API ホストで十分です。

初回の実行には履歴データが必要です。日次同期で取り込まれるのは当月分だけです。ページに十分な情報を掲載するため、次のコマンドで一度だけバックフィルしてください。 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 は、scripts/publish_site.sh を使用して、毎日 04:30（04:00 の同期直後）にサイトを再生成します。アプリはディスクから配信するため、ページはすぐに更新されます。再起動も外部デプロイも不要です。

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 での可用性はマシンの稼働状況に左右されます。配信中はスリープさせないでください（API と同様に pmset が必要です）。後で常時稼働のホスティングが必要になった場合は、同じ site/dist を Cloudflare Pages にプッシュできます。

MCP サーバー（AI エージェントからのアクセス）

API はスタンドアロンの Model Context Protocol サーバーとしてもパッケージ化されています — packages/korea-data-mcp/ — これにより、AI エージェント（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

ツール、クライアント設定、および PyPI 公開後の uvx korea-data-mcp については、packages/korea-data-mcp/README.md をご覧ください。

ライセンス

MIT © choiyounggi