API & MCP

One base URL, one API key, five endpoints. The MCP server is the same surface wrapped for agents.

https://notonlystock.com/korea/api/v0

v0 is unstable. Paths, parameters and field names can change without notice until v1. Pin nothing you cannot change.

Authentication

Authorization: Bearer kcid_...

Create a key on the account page. Keys are stored hashed — the plaintext is shown once, at creation. Each key has a daily call cap; exceeding it returns 429 daily_cap. Revoking a key takes effect on the next call.

Endpoints

Nothing is charged for nothing. A lookup that finds no company, a search that matches no rows, and any error response all cost 0.

Look up one company

curl -H "Authorization: Bearer $KCID_KEY" \
  "https://notonlystock.com/korea/api/v0/companies/1248100998"

The number is a 10-digit business registration number (사업자등록번호), digits only. Field meanings →

Search

curl -H "Authorization: Bearer $KCID_KEY" \
  ".../search?industry=26®ion=수원시&size=1000%2B&limit=3"

{
  "returned": 3,
  "results": [
    { "brn": "1248100998",
      "name_en": "SAMSUNG ELECTRONICS CO,.LTD",
      "name_ko": "삼성전자(주)",
      "ksic_code": "26519",
      "ksic_name_en": "Manufacture of video and other visual equipment",
      "address_en": "129, Samseong-ro, Yeongtong-gu, Suwon-si, Gyeonggi-do",
      "ei_workers": 160917,
      "nps_latest": 125592, "nps_period": "2026-07", ... },
    ...
  ],
  "credits_spent": 3,
  "credits_remaining": 47
}

Search returns full company records — the same shape as /companies/{brn}. There is no second call to fetch details.

Filters

Filters combine with AND. Results are ordered by employees, largest first, so a narrow limit gives you the companies most people mean.

An unknown value is an error, not an empty result. size=big returns 400 bad_query naming the accepted values — a typo should not look like "no such companies".

Count before you pull

curl -H "Authorization: Bearer $KCID_KEY" \
  ".../search?industry=26&count_only=true"

{ "total": 3152, "credits_spent": 1, "credits_remaining": 49 }

Narrowing filters is cheap: 1 credit per count, regardless of how many match. Row responses do not carry a total — counting every match on every search would cost you nothing and cost us everything, so it is its own call.

Employment history

curl -H "Authorization: Bearer $KCID_KEY" \
  ".../companies/1248100998/employment"

{
  "brn": "1248100998",
  "source": "National Pension Service",
  "unit": "subscribers",
  "observed_periods": 36,
  "series": [
    { "period": "2026-07", "subscribers": 125592,
      "new_acquisitions": 1103, "separations": 894,
      "worksites_matched": 1, "worksites_total": 6,
      "aggregation_quality": "clean" }
  ]
}

worksites_matched against worksites_total tells you how much of the company the number covers. Read it before you trust the level — when the two differ, the month-to-month change holds up better than the absolute level.

Worksites

{ "brn": "1248100998",
  "source": "Korea Workers' Compensation & Welfare Service",
  "as_of": "2025-12-31",
  "worksites": { "total": 14, "sites": [ { "name": "…", "address_ko": "…",
                                          "employees": 128093, "industry": "…",
                                          "postal_code": "16677" } ] } }

total is how many worksites the company has; sites is what we return. They differ for a handful of companies with very long lists — the largest has over 1,300 worksites — where we return the biggest ones by headcount. When the list is cut, the count still tells you so.

Errors

{ "error": { "code": "insufficient_credits",
             "message": "10 credits required for 10 rows, 2 available. Lower `limit`." } }

MCP server

KCID_API_KEY=kcid_... npx korea-data-mcp

Or in an MCP client's config:

{
  "mcpServers": {
    "korea-company-data": {
      "command": "npx",
      "args": ["-y", "korea-data-mcp"],
      "env": { "KCID_API_KEY": "kcid_..." }
    }
  }
}

Every tool description states its own cost, so an agent can budget before calling.

Command line

npx korea-data 124-81-00998
KCID_API_KEY=kcid_... npx korea-data "samsung electronics"

Get a key — 50 free credits What is in the data