# Taiwan Company Data API

Clean, English-keyed JSON for every business registered in Taiwan: about 2 million companies, sole proprietorships and branches, their directors, supervisors and managers, setup and change filings, and the links between people and companies.

- Base URL: `https://api.easylifehub.net/tw`
- Format: JSON over HTTPS, no SDK needed. OpenAPI: `https://api.easylifehub.net/tw/openapi.json`
- Source: Taiwan government open data (Ministry of Economic Affairs company registry, Ministry of Finance business tax registry, and Taiwan Stock Exchange and Taipei Exchange disclosures for listed companies), refreshed monthly. License: Open Government Data License, version 1.0.
- Data as of: see `GET /v1/status`.

## 1. Quick start (no key needed)

```bash
curl "https://api.easylifehub.net/tw/v1/search?q=台灣積體電路"
curl "https://api.easylifehub.net/tw/v1/companies/22099131"
```

Anonymous use allows 50 requests per day per address. For more, get a free key in one call:

```bash
curl -X POST "https://api.easylifehub.net/tw/v1/keys" -H "content-type: application/json" -d '{"label":"my-agent"}'
# → {"api_key":"tw_...","plan":"free","monthly_quota":1000, ...}
```

Send the key as `x-api-key: tw_...` (or `Authorization: Bearer tw_...`). The key is shown once.

## 2. What each ID means

- `ban`: the 8-digit 統一編號 (Business Administration Number). Every company, sole proprietorship and branch has one. It is the primary key everywhere in this API.
- Names are in Traditional Chinese exactly as registered. Search accepts any part of a name (3+ characters uses the full-text index; 1 to 2 characters uses a slower substring match) or an 8-digit ban.

## 3. Endpoints

| Method | Path | What it returns |
|---|---|---|
| GET | `/v1/search?q=&city=&org_type=&active=true&limit=&offset=` | Matching companies, best matches first |
| GET | `/v1/companies/{ban}` | Profile: name, address, capital, setup date, industries, registry presence, officers (current and former), managers, filings, detected changes |
| GET | `/v1/companies/{ban}/officers?include_former=true` | Directors, supervisors and other officers, with the legal entity each one represents |
| GET | `/v1/companies/{ban}/related?min_confidence=0.4` | Companies linked by shared officer names (with confidence), board seats held by legal entities, same address, headquarters and branches |
| GET | `/v1/companies/{ban}/graph?depth=1&min_confidence=0.5` | Nodes and edges for a person/company relationship graph (depth 2 needs a key) |
| GET | `/v1/companies/{ban}/report?lang=en\|zh` | A printable due-diligence report (HTML; use the browser's print to save as PDF) combining the profile, signals, officers, related companies with a graph, filings and changes |
| GET | `/v1/companies/{ban}/financials` | Listed companies only (TWSE, TPEx): monthly revenue with YoY, year-to-date, annual revenue, quarterly statements with margins, dividends, insider holdings and pledges |
| GET | `/v1/companies/{ban}/group` | Inferred corporate group (top appointing company and members, from legal-entity board appointments), branches with addresses and city counts, the split of shares declared by directors, and overseas links (countries read from legal name prefixes such as 日商 = Japan) |
| GET | `/v1/companies/{ban}/web` | Official website and social links. Listed companies use the exchange filing; others are found by search and accepted when the site shows the company's 8-digit ID (`verified_ban`) or full name (`name_match`). Lookups need an API key; anonymous calls read the cache |
| GET | `/v1/companies/{ban}/announcements?limit=` | Material announcements (listed companies), newest first, archived daily |
| GET | `/v1/companies/{ban}/history` | Registered capital, representatives and names over time from setup/change filings, plus current and former officers |
| GET | `/v1/companies/{ban}/signals` | Neutral checks worth a second look: no active tax record, young company, high-density address, capital decrease, frequent filings |
| GET | `/v1/people?name=` | Every company role held by people registered under this exact name, grouped into likely-same-person clusters |
| GET | `/v1/filings/setup?from=&to=&city=&min_capital=` | Newly approved companies (format=csv on pro plans) |
| GET | `/v1/filings/change?from=&to=&city=` | Approved change filings |
| GET | `/v1/changes?since=YYYY-MM&ban=&field=` | Month-over-month differences we detected (name, address, capital, officers joined or left, share counts) |
| POST | `/v1/watches` | Watch companies; changes are posted to your webhook each month (key required) |
| GET | `/v1/watches`, `/v1/watches/events?since=` | Your watches and their detected changes |
| DELETE | `/v1/watches/{ban}` | Stop watching |
| POST | `/v1/keys` | Get a free API key |
| GET | `/v1/status` | Data month, counts, plans |

Dates are ISO `YYYY-MM-DD`. Money is integer New Taiwan dollars (`capital_twd`). Pagination: pass `offset` from `next_offset` until it is `null`.

## 4. How to read same-name links

Taiwan's registry lists officers by name only, with no personal ID. Two records with the same name may be one person or two different people. This API never merges them silently:

- Solid edges (`basis: "registry"`) are facts from government filings.
- Dashed edges (`basis: "same_name_inference"`) carry a `confidence` from 0 to 0.97, a `label` (`likely_same_person` at 0.7 or above, `possibly_same_person` at 0.4 or above, otherwise `uncertain`) and the `reasons`, such as how many companies use the name, a shared uncommon co-officer, the same registered address, or a board link between the two companies.

Treat inferences as leads. Confirm anything important against the official registry before acting on it, and do not use this data to make decisions about individuals.

## 5. Example: due-diligence check in one script

```python
import requests
BASE = "https://api.easylifehub.net/tw"
H = {"x-api-key": "tw_..."}          # optional for light use

hit = requests.get(f"{BASE}/v1/search", params={"q": "鴻海精密工業"}, headers=H).json()["results"][0]
ban = hit["ban"]
profile = requests.get(f"{BASE}/v1/companies/{ban}", headers=H).json()
signals = requests.get(f"{BASE}/v1/companies/{ban}/signals", headers=H).json()["signals"]
related = requests.get(f"{BASE}/v1/companies/{ban}/related", params={"min_confidence": 0.7}, headers=H).json()

print(profile["name"], profile["capital_twd"], profile["registry_presence"]["note"])
for s in signals:
    print("signal:", s["code"], s["text"])
for r in related["via_shared_officer_names"][:10]:
    print("linked:", r["name"], r["via_names"], r["confidence"], r["label"])
```

```ts
const BASE = "https://api.easylifehub.net/tw";
const get = (p: string) => fetch(BASE + p, { headers: { "x-api-key": process.env.TW_KEY ?? "" } }).then((r) => r.json());
const { results } = await get("/v1/search?q=" + encodeURIComponent("台灣積體電路"));
const graph = await get(`/v1/companies/${results[0].ban}/graph?depth=1`);
console.log(graph.nodes.length, "nodes", graph.edges.length, "edges");
```

## 6. Monitoring with webhooks

```bash
curl -X POST "https://api.easylifehub.net/tw/v1/watches" -H "x-api-key: tw_..." -H "content-type: application/json" \
  -d '{"bans":["22099131","04541302"],"webhook_url":"https://example.com/hooks/twdata"}'
```

After each monthly update we POST `{"type":"twdata.changes","month":"YYYY-MM","changes":[...]}` to your HTTPS URL. Verify it: the `x-twdata-signature` header is `sha256=` + HMAC-SHA256 of `"{x-twdata-timestamp}.{raw body}"` using the `webhook_secret` you received with your key. No webhook? Poll `GET /v1/watches/events?since=YYYY-MM`.

## 7. Errors and limits

Errors look like `{"error":{"code":"...","message":"..."}}`.

| HTTP | code | What to do |
|---|---|---|
| 400 | `invalid_ban`, `invalid_parameter`, `missing_query` | Fix the request |
| 401 | `invalid_api_key`, `api_key_required` | Check the key, or get one with `POST /v1/keys` |
| 403 | `plan_required`, `watch_limit` | Upgrade the plan |
| 404 | `not_found` | No such company in the current data |
| 429 | `rate_limited`, `quota_exceeded` | Wait `Retry-After` seconds |

Every response carries `x-plan`, `x-quota-limit` and `x-quota-remaining`. Requests are safe to retry.

## 8. Plans

| Plan | Quota | Watches | CSV export | Price |
|---|---|---|---|---|
| Anonymous | 50 per day | none | no | free |
| Free key | 1,000 per month | 5 | no | free |
| Starter | 20,000 per month | 100 | no | see marketplace listing |
| Pro | 200,000 per month | 1,000 | yes | see marketplace listing |
| Business | 2,000,000 per month | 10,000 | yes | contact |

Paid plans are sold through the API marketplace listing linked from this page.

## 9. What this API does not include

No court judgments or litigation, no personal addresses or ID numbers, and no shareholder registers beyond the share counts that directors and supervisors must file. The data describes registrations, not the quality or honesty of any business.

## 10. MCP

AI agents that speak the Model Context Protocol can use the tools `tw_search_companies`, `tw_get_company`, `tw_related_companies`, `tw_company_graph`, `tw_company_signals` and `tw_people_roles`. See the repository README for the server command.
