# Taiwan Company Registry & KYB Lookup: UBN, Supplier Search (`giggling_persimmon/taiwan-company-exporter-directory`) Actor Taiwan company registry KYB: bulk-verify 10,000 統一編號 (UBN) per run, find export-qualified manufacturers & suppliers. Official MOF + trade open data, English, daily. From $0.002/company. - **URL**: https://apify.com/giggling_persimmon/taiwan-company-exporter-directory.md - **Developed by:** [Stanley Chiang](https://apify.com/giggling_persimmon) (community) - **Categories:** Lead generation, Business - **Security:** Limited permissions - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $2.00 / 1,000 business records This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event ## What's an Apify Actor? An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md. ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run. For examples already wired to this Actor's own input schema, see the [API](#api) section below. Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`). # README ## Taiwan Company Registry & KYB Lookup: Bulk UBN (統一編號) Check and Supplier Search **Verify up to 10,000 Taiwan companies per run for about $20–40, against roughly €25 for one Taiwan KYC report.** Built for KYB and compliance analysts, sourcing managers and data teams, using official Taiwan government open data in English and refreshed daily. - **KYB and compliance analysts:** bulk 統一編號 / UBN lookup gives checksum validity, active tax registration, official English name and address (for registered importers/exporters), industry, and import/export qualification. Invalid and not-found numbers are free. - **Sourcing and procurement managers:** find export-qualified Taiwan manufacturers and suppliers by industry, city, capital and founding date, e.g. "IC manufacturers in Hsinchu that can export" (50 records ≈ $0.21). - **Data and RevOps developers:** JSON/CSV/API output, incremental runs (new or changed companies only), and market-size counts for $0.02 per report. No scraping, no login, 1.7M active businesses. Pricing: $0.002 per registry record, $0.004 per trade-enriched record, $0.005 per run. Unofficial; data from the Ministry of Finance and the International Trade Administration (MOEA) under the Open Government Data License v1.0. | Option | What you get | Cost | |---|---|---| | **This Actor** | Bulk: up to 10,000 UBNs per run, English names, export flags, filters, CSV/JSON/API | $0.002–0.004 per company + $0.005 per run | | FindBiz (MOEA company registry) | One company at a time in the web UI, no export flag | Free, manual | | Taiwantrade | Supplier profiles that companies chose to publish (70k+) | Free, manual | | KYC report vendors | Analyst report per company | e.g. INFOPROFF Taiwan KYC report €25.20; D\&B Taiwan report NT$9,450 | Competitor prices as published on the vendors' pricing pages, checked 2026-10-29. > **Unofficial.** Not affiliated with or endorsed by the Ministry of Finance (Fiscal Information Agency), the International Trade Administration, MOEA, the Taiwan Food and Drug Administration (衛福部食品藥物管理署) or the National Communications Commission (國家通訊傳播委員會). Data: government open data under the Open Government Data License v1.0 (see *Attribution and licence*). **Try it:** the prefilled input looks up TSMC (22099131), Hon Hai/Foxconn (04541302) and MediaTek (84149961). That is 3 trade-enriched records, about $0.017 in total. #### Sources and English names - Two official open-data files, published daily: - Ministry of Finance (FIA) business-tax register (data.gov.tw dataset 9400) - International Trade Administration (BOFT) importer/exporter register (data.gov.tw dataset 79641) - **Official English** company names and addresses come from BOFT. English industry names are our own unofficial translations of the MOF classification, labelled as such. - **English district names** come from Chunghwa Post's official bilingual township table. - **Privacy by default.** Sole proprietorships are excluded, representative names are never output, and personal mobile numbers are dropped (details below). ### What you can do | Mode | Use it for | Charged per | |---|---|---| | `search` (default when `mode` is omitted) | Lists of companies, e.g. "IC manufacturers in Hsinchu City that can export", or "software companies founded in Taipei in 2026" | record | | `lookup` | KYC / supplier verification: check up to 10,000 統一編號 at once (checksum, active status, English name, address, trade qualification) | found record. Invalid and not-found numbers are **free** | | `marketSize` | Counts only, no rows: number of businesses, traders and exporters by city, district and industry division | report | ### Input examples ```json { "mode": "search", "cities": ["Hsinchu City"], "industryCodes": ["2611"], "exportQualified": true, "maxResults": 50 } ``` ```json { "mode": "lookup", "ubns": ["22099131", "04541302", "84149961", "130"] } ``` If you leave out `mode`, a run that has `ubns` is treated as a lookup, so `{ "ubns": ["22099131", "04541302"] }` works too (this is what the Store's API, CLI and MCP snippets send). Without `ubns` the default is `search`. ```json { "mode": "marketSize", "industryCodes": ["26"] } ``` #### Main filters - `industryCodes` takes MOF tax-industry codes or prefixes: - `2611` is semiconductors, `62` is computer programming. - A section letter `A`–`S` selects a whole section. - `industryKeyword` (zh or en) and `primaryIndustryOnly` narrow the match further. - `cities` / `districts` accept Chinese or English, and 台/臺 spellings are equivalent: `台中市` = `臺中市` = `Taichung City`. - `orgTypes` filters by organisation type. The default covers limited companies, companies limited by shares, and domestic/foreign branches. - Other filters: `includeBranches`, `minCapitalTwd` / `maxCapitalTwd`, `foundedAfter` / `foundedBefore`, `usesEInvoice`, and `nameKeyword` (Chinese name, or the English name for traders). - Trade filters: `tradersOnly`, `exportQualified`, `importQualified`. - `firstSeenAfter` returns only businesses that first appeared in the register after a date (see *New-company tracking*). - `incrementalMode` (+ `stateKey`) returns only businesses that are new or changed since your last run with the same filters. - `outputLanguage` is `both` (default), `en` or `zh`. `maxResults` defaults to 100 (prefill 10) and can go up to 200,000. ### Output (one item per business) ```json { "ubn": "22099131", "ubnValid": true, "found": true, "activeInFia": true, "headquartersUbn": null, "isBranch": false, "nameZh": "台灣積體電路製造股份有限公司", "nameEn": "TAIWAN SEMICONDUCTOR MANUFACTURING COMPANY LIMITED", "orgTypeZh": "股份有限公司", "orgTypeEn": "Company limited by shares", "orgCategory": "company", "capitalTwd": 259323700670, "capitalApplicable": true, "foundedDate": "1987-03-21", "foundedDateRoc": "0760321", "addressZh": "新竹市東區科園里科學園區力行六路8號", "addressEn": "No. 8, Lixing 6th Rd., East Dist., Hsinchu City 30078, Taiwan (R.O.C.)", "postalCode": "30078", "city": "新竹市", "cityEn": "Hsinchu City", "district": "東區", "districtEn": "East District", "postalCode3": "300", "usesEInvoice": true, "primaryIndustryCode": "261199", "primaryIndustryEn": "Semiconductor manufacturing", "industries": [ { "code": "261199", "codeFormatted": "2611-99", "nameZh": "其他積體電路製造", "nameEn": "Semiconductor manufacturing", "nameEnSource": "unofficial-group-3", "sectionCode": "C", "sectionEn": "Manufacturing", "isPrimary": true } ], "trade": { "isRegisteredTrader": true, "canImport": true, "canExport": true, "traderRegisteredDate": "1987-03-24", "traderIssuedDate": "2024-06-21", "phone": "03-5636688", "phoneExt": null, "fax": null }, "firstSeenDate": "2026-10-28", "snapshotDate": "2026-10-28", "tradeSnapshotDate": "2026-10-27", "sources": ["FIA BGMOPEN1", "BOFT companyData"], "license": "Open Government Data License, version 1.0", "attribution": "…" } ``` Real output samples (first 20 records, JSON + CSV) are in [`samples/`](samples/). The run summary goes to the key-value store record `OUTPUT`. It includes rows scanned, matched and output, snapshot dates, the charges, runtime, peak memory and the attribution text. ### Optional: market-access licence counts (TFDA / NCC) Set `"includeMarketAccessLicences": true` (off by default) to add a `marketAccessLicences` block to every record, **at no extra charge**. The record price does not change. The block holds **counts only**; no licence-holder, applicant or person names are output: ```json "marketAccessLicences": { "tfdaMedicalDevices": {"active": 0, "total": 0, "latestIssueDate": null}, "tfdaDrugs": {"active": 0, "total": 0, "latestIssueDate": null}, "nccTelecomApprovals": {"valid": 132, "total": 132, "latestApprovalDate": "2025-07-24", "matchedBy": "exact company name (NCC has no UBN)"}, "sources": [{"source": "…", "sourceUrl": "https://data.gov.tw/dataset/5996", "licence": "Open Government Data License, version 1.0", "retrievedDate": "2026-10-29"}] } ``` - **TFDA medical-device (data.gov.tw 9576) and drug (9122) licences** are joined by the holder's 統一編號. `active` means the licence is not cancelled and is not past its expiry date. `total` counts unique licence numbers. TFDA masks some holders' numbers (`********`); those rows are **never** guessed or back-filled, and neither are short or blank numbers. They only appear as counts in the run summary. - **NCC telecom-equipment type approvals (data.gov.tw 5996)** carry no UBN, so they are joined by **exact company name**. Only names containing 公司 are used: Taiwan's Company Act makes these names unique nationwide. Sole proprietorships and individual-looking applicants never match. `valid` uses NCC's "still valid" flag. Blank and placeholder dates (for example `19000105`) become `null`. A brand that files under a different legal entity will not be counted. - If a source can't be downloaded or parsed, its counts are `null` (not 0) and the run summary (`OUTPUT`) explains why. The other sources still work. - `marketSize` mode ignores this option. Incremental runs (`onlyNew`/`onlyChanged`) do not treat a change in licence counts as a change. - Each source is released under the Open Government Data License v1.0 (data.gov.tw/license). NCC site content is released under OGDL v1 per NCC's 政府網站資料開放宣告; counts are matched by exact company name, so verify on the official NCC search. - With this option on, each item's `attribution` text and the `OUTPUT` record also name TFDA datasets 9576 and 9122 and NCC dataset 5996, each with the OGDL v1 line. ### Optional: sanctions / export-control screening flags (possible matches) > **Possible match only, not a legal determination; absence of a flag is not clearance.** Always verify against the official list (and, for US lists, the Federal Register) and do your own due diligence. If a customer is on the Taiwan list, an export permit for strategic high-tech commodities is needed before export; ask 國際貿易署 貿易安全管理辦公室. > > This product uses the International Trade Administration's Data API but is not endorsed or certified by the International Trade Administration. Set `"screening": true` (off by default) to screen each company's **English and Chinese name** against two lists, **at no extra charge**. The record price does not change. 1. **US Consolidated Screening List** (CSL: SDN, Entity List, Denied Persons, MEU, CMIC and others). This is the ITA bulk file (public-domain US Government work). `listDate` is the date the file was last updated. 2. **Taiwan 國際貿易署 我國戰略性高科技貨品出口實體管理名單** (strategic high-tech commodities entity list), data.gov.tw dataset 102368, Open Government Data License v1.0. The file carries no update date (its `createdate` changes every day), so `listDate` is the date this run fetched it. The run summary records a content hash for change detection. Each flag carries only these fields (other list columns are not republished, and there is no numeric score): ```json "screening": { "screeningHits": [ {"flag": "possible match: on 國際貿易署 entity list (data.gov.tw 102368); not a legal determination", "matchType": "exact", "matchedEntityName": "…name exactly as written on the list…", "listName": "國際貿易署 entity list (data.gov.tw 102368)", "listDate": "2026-10-29", "officialLink": "https://data.gov.tw/dataset/102368"} ], "listsChecked": [{"listName": "US Consolidated Screening List", "listDate": "2026-10-29", "officialLink": "https://www.trade.gov/consolidated-screening-list", "checked": true}, {"listName": "國際貿易署 entity list (data.gov.tw 102368)", "listDate": "2026-10-29", "officialLink": "https://data.gov.tw/dataset/102368", "checked": true}], "disclaimer": "possible match only, not a legal determination; absence of a flag is not clearance. …", "notice": "This product uses the International Trade Administration's Data API but is not endorsed or certified by the International Trade Administration." } ``` - **`matchType`:** - `exact`: the same name or listed alias, ignoring case, width, punctuation and spelling of legal forms (Co., Ltd. = CO LTD = Company Limited). - `normalized`: the same name once legal forms, "Taiwan", spacing and hyphens are removed (HON HAI = HONHAI). - `fuzzy`: a near-miss you should review. It covers word order, Wade-Giles vs Pinyin spellings of one syllable (HSIN = XIN, CHANG = ZHANG, KUO = GUO) and one-letter typos in long words. - **What is not flagged:** very short or generic names, such as a one-word name under 6 letters ("ATLAS"), one-letter aliases, or names made only of generic words ("Semiconductor Manufacturing"). - **Personal data:** the lists include natural persons. Their entries are dropped when the list is loaded: CSL rows typed Individual, and any entry with no company or organisation marker. Date-of-birth, nationality, passport/ID and address columns are never read. Only company names from this directory are screened; you cannot screen a person's name. Some organisations listed without any company marker are therefore not screened. - **Coverage:** English names come from the 國際貿易署 importer/exporter registry. Companies without a registered English name are screened by Chinese name only, and most CSL names are in Latin script. A failed list download shows `"checked": false` for that list, and `screeningHits` is `null` if neither list could be checked. - `marketSize` mode ignores this option. ### Pricing (pay per event) | Event | Price | When | |---|---|---| | `apify-actor-start` | $0.005 | once per run (charged automatically by Apify) | | `result` | $0.002 | business record from the tax register only (no trade data) | | `trade-enriched-record` | $0.004 | record joined with the importer/exporter register (English name/address, import/export flags, business phone) | | `market-size-report` | $0.02 | one aggregate report in `marketSize` mode | Invalid and not-found lookups are free. The run stops cleanly when your **maximum charge per run** is reached; records that are not delivered are never charged. Prices are in `pricing.json`; the live prices are set in Apify Console. Examples from the real data (2026-10-28 snapshot): - 50 Hsinchu IC exporters cost $0.205. - 177 Taipei software companies founded in 2026 cost $0.467. - A market-size report for division 26 costs $0.025. - 1,000 records cost $2.005 (all tax-register only) to $4.005 (all trade-enriched), so **about $3 for a typical 50/50 mix**. ### New-company tracking and incremental runs - **`firstSeenDate` / `firstSeenAfter`:** every run updates a compact index (named key-value store `taiwan-directory-index`) that records when each UBN first appeared in the official file. - On the first run every business gets that day's snapshot date as its baseline. - From then on, newly registered businesses get the date of the snapshot in which they first appeared. - `firstSeenAfter: "2026-10-28"` returns only businesses that appeared after that snapshot. - The index is kept in **your** account's storage, so tracking starts from your first run. - **`incrementalMode`:** a fingerprint snapshot is kept for each filter set, in the named store `taiwan-company-exporter-state` under `stateKey` or a hash of the filters. - Later runs output only `new` or `changed` businesses, marked in the `changeType` field. - Only delivered (charged) records are remembered, so anything cut off by a limit is delivered next time. - Businesses that drop out of the filter are counted in `OUTPUT.incremental.noLongerMatching`. - Use `incrementalFirstRun: "baselineOnly"` to record a baseline without paying for output. ### How it works - Each run downloads both files, or revalidates them with `If-None-Match` / `If-Modified-Since`. An unchanged file returns HTTP 304 and is not downloaded again. - **FIA file:** a 66 MB zip containing a 322 MB CSV. It is streamed and filtered row by row. - **BOFT file:** a 103 MB CSV. It is indexed into a compact table (sorted UBNs and file offsets), and full rows are read from disk only for matched companies. - A full scan of 1,715,118 rows takes about 10 s with cached files. - **Memory:** the default 1 GB is enough for every mode, including a 10,000-number lookup with both `screening` and `includeMarketAccessLicences` on. The process peak is about 200 MB; Apify's memory chart also counts file cache. **For very large runs with both add-ons on (10,000 numbers or a full-register scan), 2 GB is recommended for extra headroom.** Peak memory per stage is in `OUTPUT.memoryMb`. - **Downloads:** retried 3× with backoff. If a server is down, the last cached copy is used, with a warning. - **Data checks:** the column headers are checked exactly against the expected schema, and row counts are sanity-checked (FIA 1.5–1.9 M, BOFT 300–450 k). If either check fails, the run **fails loudly** (`Actor.fail`) instead of producing wrong data, and the first-seen index is left untouched. - **Planned (not in this version):** a developer-run daily refresh would pre-split the register into compact per-city/industry shards. Runs would then load only the shards they need, and a single shared first-seen history would cover all users. ### Data notes / FAQ - **Why does `foundedDate` differ from the company registry (GCIS)?** FIA records the tax-registration (設立) date, while MOEA/GCIS records the company-incorporation date. For example, TSMC is `0760321` in FIA and `0760221` in GCIS. Both are correct for their own agency, and this Actor does not "fix" either one. - **Branches.** Branches (`isBranch: true`) have their own UBN and a `headquartersUbn`. Their capital is usually 0 in the register: `capitalTwd: 0` with `capitalApplicable: false`. Use the headquarters record for capital. - **Active businesses only.** The FIA file contains only active tax registrations. A UBN missing from it may have ceased trading, never existed, or not be tax-registered. `lookup` returns `found: false` with a reason, free of charge. - **Registered traders without an active tax registration** (about 54 k BOFT rows) are returned in `lookup` with `activeInFia: false`. They are not included in `search`. - **UBN checksum.** Numbers are checked with the current MOF rule (2023+): weights 1,2,1,2,1,2,4,1, sum of digits divisible by **5**, with the 7th-digit-7 special case. - All 1,715,118 UBNs in the register pass this rule. - The old divide-by-10 rule would wrongly reject 199,455 of them. - **English names.** - Company names and addresses use the official English names registered with BOFT. Only registered traders have them (about 321 k joined companies). Other businesses have `nameEn: null`; there is no machine translation. - Industry names: `nameZh` is the official Chinese name from the MOF classification (OGDL dataset 28483). `nameEn` is an **unofficial English translation written by this Actor** at the 3-digit group level (for example 261199 其他積體電路製造 → "Semiconductor manufacturing"). It is not the Ministry of Finance's own wording. `nameEnSource` says which level was used: `unofficial-group-3`, `unofficial-group-2` (division), `unofficial-section`, or `unlisted-code-group-N` for codes that are not in any MOF revision. Each run's OUTPUT has an `industryNames` block describing this. - Measured on the 2026-10-28 file: 3,179,532 of 3,179,539 industry references (99.998 %) have an English name: 3,179,405 at group level, 2 at division level, and 125 unlisted codes mapped to their group or division. Seven malformed codes have none. - Why unofficial: MOF's English names are only in an internal file of its English inquiry website (WEBDATA_en.zip). Its reuse licence could not be confirmed, so the Actor does not use it (see `research/webdata-en-licence.md` in the project workspace). - **Districts.** English district names come from Chunghwa Post's bilingual township table, which has 370 entries. 1,715,087 of 1,715,118 addresses (99.998 %) resolve to a district; the remainder are malformed source addresses. For traders, the English address is used as a fallback. - **Snapshot dates.** `snapshotDate` is the date inside the FIA file. `tradeSnapshotDate` is the BOFT file's Last-Modified date in Taiwan time. BOFT is served through a CDN, so different edges can briefly serve different days. ### Privacy (Taiwan Personal Data Protection Act, PDPA) and anti-spam - **Sole proprietorships** (獨資) and **partnerships** (合夥) are usually natural persons, so they are **excluded by default**. To include them, set both `includeSoleProprietorships` and `lawfulPurposeAcknowledged` (for example for KYC or supplier verification). `lookup` of an explicitly given UBN still returns the business, but never phone numbers for these types unless you opt in. - **Representative / director names** (代表人) are **never output**. They are not even read into memory. - **Mobile numbers** (09xx, about 52 k BOFT rows) are usually personal and are **dropped**. They are included only when you set both `includeMobileNumbers` and `lawfulPurposeAcknowledged`. - **Business landlines and fax** are output by default (`includeContactNumbers`). - **Your use is your responsibility.** Use the data only for lawful purposes, respect the PDPA's purpose-limitation rules, and do not use it for unsolicited bulk marketing (spam) or telemarketing to individuals. ### Attribution and licence Both datasets are published under the **Open Government Data License, version 1.0** (政府資料開放授權條款－第1版). Every dataset item and the `OUTPUT` record carries this attribution, with the actual snapshot dates: > 財政部財政資訊中心 2026 全國營業(稅籍)登記資料集（資料日期 2026-10-28）；經濟部國際貿易署 2026 出進口廠商登記資料（資料日期 2026-10-27）。此開放資料依政府資料開放授權條款 (Open Government Data License) 進行公眾釋出，使用者於遵守本條款各項規定之前提下，得利用之。政府資料開放授權條款：https://data.gov.tw/license > > Fiscal Information Agency, Ministry of Finance, 2026, National Business (Tax) Registration Dataset, snapshot 2026-10-28; International Trade Administration, MOEA, 2026, Importer/Exporter Registration Data, snapshot 2026-10-27. Made available under the Open Government Data License: https://data.gov.tw/license. > > Unofficial. Not affiliated with or endorsed by the Ministry of Finance (Fiscal Information Agency), the International Trade Administration, MOEA, the Taiwan Food and Drug Administration (衛福部食品藥物管理署) or the National Communications Commission (國家通訊傳播委員會). | Dataset | Provider | data.gov.tw | File | |---|---|---|---| | 全國營業(稅籍)登記資料集 | 財政部財政資訊中心 (Fiscal Information Agency, MOF) | [9400](https://data.gov.tw/dataset/9400) | https://eip.fia.gov.tw/data/BGMOPEN1.zip | | 出進口廠商登記資料 | 經濟部國際貿易署 (International Trade Administration, MOEA) | [79641](https://data.gov.tw/dataset/79641) | https://fbfh.trade.gov.tw/opendata/companyData.csv | | 稅務行業標準分類 (industry codes and Chinese names) | 財政部統計處 (Department of Statistics, MOF) | [28483](https://data.gov.tw/dataset/28483) | bundled in `data/industry_codes.json` | | English industry names | this Actor (unofficial translations, not MOF wording) | – | `data/sources/industry_en_unofficial.tsv` | | 縣市鄉鎮中英對照檔 (districts) | 中華郵政 (Chunghwa Post) | [5949](https://data.gov.tw/dataset/5949) | bundled in `data/districts.json` | **Withdrawal caveat (OGDL §5):** a provider may stop publishing or withdraw a dataset at any time. If a source disappears or changes its format, the Actor fails loudly rather than serving stale or wrong data, and it may be paused or withdrawn. Data is provided "as is", without any warranty of accuracy or completeness. Always confirm critical facts with the issuing agency. Optional add-ons, when switched on, also credit their sources in each record and in `OUTPUT`: - TFDA datasets 9576 and 9122 and NCC dataset 5996 (data.gov.tw, OGDL v1), named in each item's `attribution` and in `OUTPUT`. NCC site content is released under OGDL v1 per NCC's 政府網站資料開放宣告. - 經濟部國際貿易署, 2026, 我國戰略性高科技貨品出口實體管理名單 (data.gov.tw dataset 102368), OGDL v1. - US Consolidated Screening List: *This product uses the International Trade Administration's Data API but is not endorsed or certified by the International Trade Administration.* List content is shown as published; the matching is ours. ### Run locally (developers) ```bash python3 -m venv .venv && .venv/bin/pip install -r requirements-dev.txt ./run_local.sh inputs/hsinchu-ic-exporters.json # free local run (no Apify account) ./run_local.sh --ppe --max-usd 0.05 inputs/lookup-spec.json # simulate pay-per-event and a spending limit .venv/bin/python -m pytest -q # 121 tests, offline (fixtures are real-file excerpts) .venv/bin/python scripts/build_reference_data.py # rebuild data/industry_codes.json + data/districts.json .venv/bin/python scripts/coverage_report.py # coverage stats on the real file -> samples/coverage.json ``` # Actor input Schema ## `mode` (type: `string`): If left empty: lookup when "ubns" is given, otherwise search. search = filtered company list; lookup = verify/enrich a list of 統一編號; marketSize = one aggregate report (counts by city, district and industry division), charged once. The prefilled example is a quick lookup of TSMC, Hon Hai (Foxconn) and MediaTek. ## `ubns` (type: `array`): Up to 10,000 Unified Business Numbers (統一編號). Leading zeros optional. Invalid and not-found numbers are returned free of charge. ## `industryCodes` (type: `array`): MOF tax industry codes or prefixes (2-6 digits, e.g. '2611' = semiconductors, '62' = computer programming), or section letters A-S. ## `industryKeyword` (type: `string`): Matches the official Chinese industry name or our unofficial English group name, e.g. 'semiconductor' or '半導體'. ## `primaryIndustryOnly` (type: `boolean`): Off = a business matches if any of its (up to 4) registered industries matches. ## `nameKeyword` (type: `string`): Chinese name, or English name for registered traders. ## `cities` (type: `array`): Chinese or English, e.g. '臺北市', '台北市', 'Taipei City', 'Taichung'. ## `districts` (type: `array`): e.g. '信義區' or 'Xinyi District'. Combine with cities when a name is ambiguous. ## `orgTypes` (type: `array`): Default: limited companies, companies limited by shares, and branches. Sole proprietorships/partnerships are controlled by the switch below. ## `includeSoleProprietorships` (type: `boolean`): PRIVACY (Taiwan PDPA): sole proprietorships and partnerships are usually individuals. Only enable this if you have a lawful purpose (e.g. KYC/supplier verification), and also set lawfulPurposeAcknowledged. Do not use for unsolicited marketing. ## `lawfulPurposeAcknowledged` (type: `boolean`): Required to include sole proprietorships or mobile phone numbers. I confirm I have a lawful purpose under Taiwan's Personal Data Protection Act and will not use the data for unsolicited marketing. ## `includeBranches` (type: `boolean`): Branches have their own UBN and headquartersUbn; their capital is reported as not applicable. ## `minCapitalTwd` (type: `integer`): Only businesses with registered capital of at least this amount (New Taiwan dollars). ## `maxCapitalTwd` (type: `integer`): Only businesses with registered capital of at most this amount (New Taiwan dollars). ## `foundedAfter` (type: `string`): YYYY-MM-DD (FIA tax-registration date; may differ from the MOEA company-registry date). ## `foundedBefore` (type: `string`): YYYY-MM-DD (FIA tax-registration date). ## `firstSeenAfter` (type: `string`): Only businesses that first appeared in the official file after this date (needs earlier runs; see README). ## `usesEInvoice` (type: `boolean`): Leave empty for either. ## `tradersOnly` (type: `boolean`): Only businesses that appear in the BOFT importer/exporter register. ## `exportQualified` (type: `boolean`): Leave empty for either. ## `importQualified` (type: `boolean`): Leave empty for either. ## `includeContactNumbers` (type: `boolean`): Landline business numbers from the BOFT register. Mobile (09xx) numbers are always dropped unless the next option is on. ## `includeMobileNumbers` (type: `boolean`): Mobile numbers usually belong to a person (PDPA personal data). Requires lawfulPurposeAcknowledged. ## `outputLanguage` (type: `string`): both = Chinese and English fields; en = English only; zh = Chinese only. ## `includeMarketAccessLicences` (type: `boolean`): Adds a marketAccessLicences block to each company: number of active and total TFDA medical-device licences and drug licences (joined by 統一編號) and NCC telecom-equipment approvals (joined by exact company name, because the NCC file has no 統一編號). Off by default; adds about 50 MB of downloads and about a minute per run. No extra charge. Source: TFDA and NCC open data (OGDL v1). For very large runs with both screening and includeMarketAccessLicences on (e.g. 10,000 numbers or a full scan), 2 GB memory is recommended; 1 GB works. ## `screening` (type: `boolean`): Screens each company's English and Chinese name against the US Consolidated Screening List (ITA bulk file) and Taiwan 國際貿易署 strategic high-tech commodities entity list (data.gov.tw 102368), and adds screeningHits with exact / normalized / fuzzy matches. Only company entries on the lists are used. POSSIBLE MATCH ONLY, NOT A LEGAL DETERMINATION; absence of a flag is not clearance. Verify against the official list. Off by default. No extra charge. This product uses the International Trade Administration's Data API but is not endorsed or certified by the International Trade Administration. For very large runs with both screening and includeMarketAccessLicences on (e.g. 10,000 numbers or a full scan), 2 GB memory is recommended; 1 GB works. ## `maxResults` (type: `integer`): Hard cap. The run also stops when your maximum charge per run is reached. ## `incrementalMode` (type: `boolean`): Remember what was delivered for these filters and only output new or changed businesses next time. ## `stateKey` (type: `string`): Name for the incremental state (default: a hash of the filters). ## `incrementalFirstRun` (type: `string`): What to do on the first incremental run for these filters, when there is no saved state yet. ## Actor input object example ```json { "mode": "lookup", "ubns": [ "22099131", "04541302", "84149961" ], "primaryIndustryOnly": false, "orgTypes": [ "有限公司", "股份有限公司", "本國公司設立之分公司", "外國公司在台之分公司" ], "includeSoleProprietorships": false, "lawfulPurposeAcknowledged": false, "includeBranches": true, "tradersOnly": false, "includeContactNumbers": true, "includeMobileNumbers": false, "outputLanguage": "both", "includeMarketAccessLicences": false, "screening": false, "maxResults": 10, "incrementalMode": false, "incrementalFirstRun": "emitAll" } ``` # Actor output Schema ## `results` (type: `string`): One item per business (search/lookup; invalid or not-found UBNs appear as free status rows) or one marketSizeReport item (marketSize mode). ## `summary` (type: `string`): JSON summary: rows scanned/matched/output, snapshot dates, source files, charged events, licence and attribution text. # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "mode": "lookup", "ubns": [ "22099131", "04541302", "84149961" ], "maxResults": 10 }; // Run the Actor and wait for it to finish const run = await client.actor("giggling_persimmon/taiwan-company-exporter-directory").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "mode": "lookup", "ubns": [ "22099131", "04541302", "84149961", ], "maxResults": 10, } # Run the Actor and wait for it to finish run = client.actor("giggling_persimmon/taiwan-company-exporter-directory").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}") for item in client.dataset(run.default_dataset_id).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "mode": "lookup", "ubns": [ "22099131", "04541302", "84149961" ], "maxResults": 10 }' | apify call giggling_persimmon/taiwan-company-exporter-directory --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "type": "http", "url": "https://mcp.apify.com/?tools=fetch-actor-details,giggling_persimmon/taiwan-company-exporter-directory" } } } ``` The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer ` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations). ## OpenAPI specification Download the OpenAPI definition: https://api.apify.com/v2/actors/Z0JaditAqtOoGD8v5/builds/h3KeM9MiZuSpVzmmt/openapi.json