Government Data Sources Accessible via k-skill-proxy: Complete API Guide

k-skill-proxy provides unified access to over a dozen Korean government open-data APIs—including AirKorea, KMA weather, Seoul Open Data, NEIS, NTS business registry, and KOSIS statistics—through a single Fastify-based proxy that handles authentication, caching, and rate-limiting automatically.

The k-skill-proxy package in the NomaDamas/k-skill repository acts as a credential-aware façade for Korean public-sector datasets. Written in Fastify, it forwards requests to upstream government portals like data.go.kr while injecting service keys, enforcing 20-second timeouts, and standardizing JSON responses.

Supported Government Data Portals

The proxy exposes REST endpoints that map directly to specific government agencies. Each route is implemented in a dedicated handler module under packages/k-skill-proxy/src/.

Environmental and Weather Data

• AirKorea (대기질): Access fine-dust reports via GET /v1/fine-dust/report. This wraps the AirKorea Open API and requires the AIR_KOREA_OPEN_API_KEY environment variable. Implementation resides in src/airkorea.js.

• KMA (Korea Meteorological Administration): Retrieve short-term weather forecasts through GET /v1/korea-weather/forecast. This endpoint proxies the KMA Open API using the KMA_OPEN_API_KEY.

Seoul Metropolitan Data

• Seoul Open Data Plaza: Three distinct endpoint groups provide real-time city data:

  • Bike sharing: GET /v1/seoul-bike/*
  • Population density: GET /v1/seoul-density/*
  • Subway arrival times: GET /v1/seoul-subway/arrival

  All Seoul endpoints require SEOUL_OPEN_API_KEY and forward to the Seoul Open Data APIs.

• Han River Flood Control Office (한강홍수통제소): Check water levels at GET /v1/han-river/water-level using HRFCO_OPEN_API_KEY.

Education and Administrative Data

• NEIS (National Education Information Service):

  • Search schools: GET /v1/neis/school-search
  • Query meal information: GET /v1/neis/school-meal

  Requires KEDU_INFO_KEY. The school search logic is implemented in src/neis/school-search.js.

• NTS (National Tax Service): Validate business registration numbers via:

  • POST /v1/nts-business/status
  • POST /v1/nts-business/validate

  These endpoints proxy https://api.odcloud.kr/api/nts-businessman/v1 and use DATA_GO_KR_API_KEY. Source code is in src/nts-business.js.

Statistical and Financial Data

• Data.go.kr (공공데이터포털): Multiple datasets unified under various paths:

  • Household waste: GET /v1/household-waste/info
  • Parking lots: GET /v1/parking-lots/search
  • EV chargers: GET /v1/ev-charger/*
  • Building registry: GET /v1/building-register/title
  • MFDS (food/drug): GET /v1/mfds/*
  • LH notices: GET /v1/lh-notice/*
  • NHIS (insurance): GET /v1/nhis/*

  Requires DATA_GO_KR_API_KEY (and optionally FOODSAFETYKOREA_API_KEY for food safety data). Real-estate wrappers are handled in src/molit.js.

• KOSIS (Korea Statistical Information Service): Access statistical tables through GET /v1/kosis/* (supporting search, metadata, data retrieval, and indicator endpoints). Accepts either KOSIS_API_KEY or KSKILL_KOSIS_API_KEY. Implementation is in src/kosis.js.

• KRX (Korea Exchange): Query Korean stock information via GET /v1/korean-stock/* (search, base-info, trade-info) using KRX_API_KEY.

Network and Geographic Information

• KISA WHOIS: Perform domain, IP, and AS lookups via GET /v1/kr-whois/*. Requires DATA_GO_KR_API_KEY.

• VWorld: Access geographic and official land price data through GET /v1/vworld/*. Unlike other endpoints, VWorld uses delegated credentials—callers must provide their own key in the x-k-skill-vworld-api-key header. No environment variable is required on the proxy side.

Library Data

• Data4Library (도서관 정보나루): Query library systems via GET /v1/data4library/* using DATA4LIBRARY_AUTH_KEY.

Proxy Architecture and Request Flow

In packages/k-skill-proxy/src/server.js, a router table maps each incoming path to a specific handler module (e.g., src/molit.js, src/nts-business.js). The architecture follows a consistent pattern:

1. Request Validation: Each handler validates query parameters against the upstream API requirements.
2. Credential Injection: The proxy retrieves service keys from environment variables and injects them into the upstream request.
3. Upstream Fetch: All requests enforce a 20-second timeout to prevent hanging connections.
4. Response Standardization: Results are JSON-ified and returned to the client with consistent error handling.

The health-check endpoint (GET /health) reports per-route configuration flags (e.g., naverSearchApiConfigured, vworldRelayAvailable), allowing downstream applications to programmatically discover which government data sources are currently operational.

Practical Usage Examples

The following curl commands demonstrate how to retrieve data from several government sources via the proxy. Replace LOCAL_PROXY_BASE_URL with your local instance (http://localhost:3000) or the production endpoint.

AirKorea Fine-Dust Report

curl -fsS "${LOCAL_PROXY_BASE_URL}/v1/fine-dust/report" \
  -G --data-urlencode "searchDate=2024-09-01" \
  -d "itemCode=PM10"

Requires: AIR_KOREA_OPEN_API_KEY

Seoul Bike Stations Nearby

curl -fsS "${LOCAL_PROXY_BASE_URL}/v1/seoul-bike/nearby" \
  -G --data-urlencode "lat=37.5717" \
  -d "lon=126.9763" \
  -d "radius_m=500"

Requires: SEOUL_OPEN_API_KEY

NEIS School Search

curl -fsS "${LOCAL_PROXY_BASE_URL}/v1/neis/school-search" \
  -G --data-urlencode "educationOffice=서울특별시교육청" \
  -d "schoolName=미래초등학교"

Requires: KEDU_INFO_KEY

NTS Business Registration Status

curl -fsS -X POST "${LOCAL_PROXY_BASE_URL}/v1/nts-business/status" \
  -H "Content-Type: application/json" \
  -d '{"b_no":["123-45-67890"]}'

Requires: DATA_GO_KR_API_KEY

KOSIS Statistical Metadata

curl -fsS "${LOCAL_PROXY_BASE_URL}/v1/kosis/meta" \
  -G --data-urlencode "tableId=DT_1JC1501" \
  -d "metaType=ITM"

Requires: KOSIS_API_KEY or KSKILL_KOSIS_API_KEY

VWorld Apartment Prices (Delegated Auth)

curl -fsS "${LOCAL_PROXY_BASE_URL}/v1/vworld/apartment-prices" \
  -H "x-k-skill-vworld-api-key: ${VWORLD_API_KEY}" \
  -G --data-urlencode "pnu=1150010400104480001" \
  -d "stdrYear=2026"

Requires: Client-provided x-k-skill-vworld-api-key header (no proxy-side env var).

Key Implementation Files

File	Purpose
packages/k-skill-proxy/src/server.js	Fastify server initialization, route registration, and health-check logic
packages/k-skill-proxy/src/molit.js	Ministry of Land, Infrastructure & Transport real-estate API wrappers
packages/k-skill-proxy/src/nts-business.js	National Tax Service business registration validation
packages/k-skill-proxy/src/kosis.js	KOSIS statistical data façade
packages/k-skill-proxy/src/airkorea.js	AirKorea air quality endpoints
packages/k-skill-proxy/src/neis/school-search.js	NEIS education information service
packages/k-skill-proxy/README.md	Complete endpoint documentation and secret requirements

Summary

• k-skill-proxy unifies access to Korean government open-data APIs under a single Fastify HTTP proxy.
• Environment variables handle service keys for AirKorea (AIR_KOREA_OPEN_API_KEY), Seoul (SEOUL_OPEN_API_KEY), NTS (DATA_GO_KR_API_KEY), and others, while VWorld requires caller-provided credentials.
• Handler modules like src/molit.js and src/nts-business.js isolate agency-specific logic and enforce 20-second timeouts.
• Health checks at GET /health expose upstream availability for programmatic service discovery.
• All endpoints return standardized JSON, abstracting the complexity of the underlying data.go.kr and other government portals.

Frequently Asked Questions

How do I configure API keys for k-skill-proxy?

Set the required environment variables before starting the proxy. For example, AIR_KOREA_OPEN_API_KEY for fine-dust data, DATA_GO_KR_API_KEY for tax and WHOIS lookups, and SEOUL_OPEN_API_KEY for city data. The full list is documented in packages/k-skill-proxy/README.md. The proxy reads these at startup and injects them into upstream requests automatically.

Does k-skill-proxy cache government API responses?

Yes, the proxy implements caching and rate-limiting to prevent hitting upstream government API limits. According to the implementation in src/server.js and handler modules, requests are forwarded with credential handling and timeout protection (20 seconds), though specific cache TTL values depend on the endpoint configuration in your deployment.

Can I use my own VWorld API key instead of the proxy's?

Yes. VWorld endpoints (/v1/vworld/*) support delegated credential handling. Unlike other endpoints that use environment variables, VWorld requires you to pass your personal API key in the x-k-skill-vworld-api-key request header. This allows multiple consumers to use the same proxy instance with different VWorld credentials.

What is the timeout for government API requests through the proxy?

All upstream requests enforce a 20-second timeout. If the Korean government API (such as data.go.kr or AirKorea) does not respond within this window, the proxy returns an error, preventing your application from hanging indefinitely on slow government servers.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}