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

> Access numerous Korean government data APIs like AirKorea, KMA weather, and NTS business registry through k-skill-proxy. This guide details unified API access for developers.

- Repository: [NomaDamas/k-skill](https://github.com/NomaDamas/k-skill)
- Tags: api-reference
- Published: 2026-08-03

---

**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](https://github.com/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`](https://github.com/NomaDamas/k-skill/blob/main/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`](https://github.com/NomaDamas/k-skill/blob/main/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`](https://github.com/NomaDamas/k-skill/blob/main/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`](https://github.com/NomaDamas/k-skill/blob/main/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`](https://github.com/NomaDamas/k-skill/blob/main/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`](https://github.com/NomaDamas/k-skill/blob/main/packages/k-skill-proxy/src/server.js), a **router table** maps each incoming path to a specific handler module (e.g., [`src/molit.js`](https://github.com/NomaDamas/k-skill/blob/main/src/molit.js), [`src/nts-business.js`](https://github.com/NomaDamas/k-skill/blob/main/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

```bash
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

```bash
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

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

```

Requires: `KEDU_INFO_KEY`

### NTS Business Registration Status

```bash
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

```bash
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)

```bash
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`](https://github.com/NomaDamas/k-skill/blob/main/packages/k-skill-proxy/src/server.js) | Fastify server initialization, route registration, and health-check logic |
| [`packages/k-skill-proxy/src/molit.js`](https://github.com/NomaDamas/k-skill/blob/main/packages/k-skill-proxy/src/molit.js) | Ministry of Land, Infrastructure & Transport real-estate API wrappers |
| [`packages/k-skill-proxy/src/nts-business.js`](https://github.com/NomaDamas/k-skill/blob/main/packages/k-skill-proxy/src/nts-business.js) | National Tax Service business registration validation |
| [`packages/k-skill-proxy/src/kosis.js`](https://github.com/NomaDamas/k-skill/blob/main/packages/k-skill-proxy/src/kosis.js) | KOSIS statistical data façade |
| [`packages/k-skill-proxy/src/airkorea.js`](https://github.com/NomaDamas/k-skill/blob/main/packages/k-skill-proxy/src/airkorea.js) | AirKorea air quality endpoints |
| [`packages/k-skill-proxy/src/neis/school-search.js`](https://github.com/NomaDamas/k-skill/blob/main/packages/k-skill-proxy/src/neis/school-search.js) | NEIS education information service |
| [`packages/k-skill-proxy/README.md`](https://github.com/NomaDamas/k-skill/blob/main/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`](https://github.com/NomaDamas/k-skill/blob/main/src/molit.js) and [`src/nts-business.js`](https://github.com/NomaDamas/k-skill/blob/main/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`](https://github.com/NomaDamas/k-skill/blob/main/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`](https://github.com/NomaDamas/k-skill/blob/main/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.