Company data#

This domain answers four kinds of questions. Lists — filter company subjects by registration country (the library spans 10+ countries and regions), or qualification rosters by type, region and year — roster filters take the controlled-vocabulary values verbatim (zh-CN roster scope). One company — its records and disclosures: qualification details, regulator disclosure documents, customer / supplier / subsidiary relationships. European registries — live lookups in the official company registers of Switzerland, Norway and Finland, or search the French national directory by company name, officer name or SIREN. US public companies — identify a registrant by number or name, find its parents, pull its federal contracts, and full-text-search SEC EDGAR filings from 2001 to today. Every result carries an evidence quote and an official source URL you can open.

Commands at a glance#

Every command in this domain — the two library queries plus every direct-lookup face; each has its own section below (what it answers / parameters / a real example / boundaries).

The ingested library: search & read#

search and read query the built library (available once access is opened) — it holds three record kinds: company (a company subject) / qualification (an official qualification award) / disclosure_document (a regulator disclosure document).

The examples below omit the leading executable name — prepend agentdata (or python -m agentdata ) for a full command.

search · filter a list#

**Answers:**first-pass screening needs a slice of US-registered company subjects — one command returns the rows, each with its inclusion reason, evidence quote and official source, plus counts per field.

$ company search --filter company_registration_country=US --facets company_registration_country --limit 5

Response shape (available once access is opened):

{ "domain": "company", "backend": "db", "coverage": "…",
  "rows": [ { "cursor": "company:123", "record_kind": "company",
              "entity": {"…": "…"}, "reason": "…",
              "evidence": [ { "anchor": "…", "quote": "…", "url": "…", "raw_path": "…", "sha256": "…" } ],
              "source": { "source": "…", "observed_at": "…" } } ],
  "facets": { "company_registration_country": [ { "value": "…", "count": 123 } ] },
  "total_matched": "…", "next_cursor": "company:456", "notes": ["…"] }

Reading the result：

• rows[].entity — the matched record itself (company / qualification / disclosure document)
• rows[].reason — why this row is in the result (the inclusion reason)
• rows[].evidence[] — the evidence: a quote from the original (quote), the official source URL (url), plus the raw file path and content hash (sha256)
• facets — counts per field you asked for (e.g. how many companies per province)
• total_matched / next_cursor — total hits and the next-page cursor (feed it back to page through)

Parameters：

Undeclared fields are a 400 error (a typo never returns a silent empty result). The Status column updates automatically with the fields actually open at the interface — fields marked Open are filterable; fields marked Not open cannot be filtered. kw keyword search is the disclosure-documents-only 4th dimension.

The qtype controlled vocabulary currently holds 42 values. Suggested facets (open fields): doc_class / doc_date(year) / qtype / province / company_registration_country / registration_status.

A misspelled filter field returns 400 undeclared_field — never a silent empty result.

read · pull one company's file#

**Answers:**a row from search caught your eye — read pulls that company's full file with one id, as deep as you ask.

$ company read --id 1476 --level tier2

Parameters：

Depth levels: tier1 the summary card, tier2 full details, tier3 the evidence pack. Every level carries its reasoning, evidence quote and source URL (semantics in the read-layers table above).

Live lookups against official sources#

The direct-lookup faces skip the library: install the package and they run, querying the official public sources on the spot and returning what those sources hold at that moment. Every result carries the official source URL so you can verify the original. No platform-side quota; each upstream's own limits apply, and repeats within a cache lifetime are served from your local cache without hitting it.

Examples below are real command output, excerpts only, unmodified — captured 2026-10-23–11-02 (recaptured in flat form 2026-10-27). Figures shift as upstreams update.

The examples below omit the leading executable name — prepend agentdata (or python -m agentdata ) for a full command.

company ch_zefix_firm#

ehraid → full Swiss registry record (purpose text, old names, M&A edges)

Parameters：

**Note:**Takes only the ehraid (search rows carry it); empty M&A arrays mean no declared edges — not missing data.

$ company ch_zefix_firm --ehraid 189146

{
  "reason": "Zefix 单档：Swatch AG（uid CHE103650519，EXISTIEREND，Biel/Bienne）；前继 2 / 后继 0 并购边——purpose/oldNames 全文带回",
  "result": {
    "ehraid": 189146, "name": "Swatch AG", "status": "EXISTIEREND", "legal_seat": "Biel/Bienne",
    "uid_formatted": "CHE-103.650.519", "chid_formatted": "CH-073-3002499-8", "shab_date": "2026-07-27",
    "purpose": "Herstellung von und Handel mit Uhren, Uhrenbestandteilen, Uhrwerken, Bijouterieartikeln, elektronischen Zeitmessgeräten und -anlagen und deren Komponenten, elek…",
    "old_names": [],
    "has_taken_over": [],
    "taken_over_by": []
  },
  "evidence": [
    { "quote": "purpose 德文全文照录（制造与贸易钟表、表件、机芯、饰物、电子计时器…）；前继 2 家",
      "url": "https://www.zefix.ch/ZefixREST/api/v1/firm/189146.json" }
  ]
}

Reading it:purpose is the registered-purpose text, verbatim in German / French / Italian; old_names is the renaming history; has_taken_over / taken_over_by are M&A edges — predecessors and successors each carry the other side's three keys, and neither renaming nor M&A breaks the ehraid.

company ch_zefix_firm_search#

Swiss company name → registry candidates (Zefix, triple key ehraid/uid/chid)

Parameters：

**Note:**Candidates are non-authoritative — confirm with the full ch_zefix_firm --ehraid record; the --offset walk cap is the upstream-echoed max_offset.

$ company ch_zefix_firm_search --name "Swatch AG"

{
  "reason": "Zefix 检索：1 候选，首选 Swatch AG（uid CHE103650519，EXISTIEREND，Biel/Bienne）——包含式匹配非权威归一，三键（ehraid/uid/chid）直出",
  "result": {
    "firms": [
      { "ehraid": 189146, "uid": "CHE103650519", "uid_formatted": "CHE-103.650.519",
        "chid": "CH07330024998", "chid_formatted": "CH-073-3002499-8",
        "name": "Swatch AG", "status": "EXISTIEREND", "legal_seat": "Biel/Bienne", "shab_date": "2026-07-27",
        "cantonal_excerpt_web": "https://be.chregister.ch/cr-portal/auszug/auszug.xhtml?uid=CHE-103.650.519" }
    ],
    "has_more": false,
    "max_offset": 1435992
  },
  "evidence": [
    { "quote": "Swatch AG（ehraid 189146，uid CHE103650519，EXISTIEREND，Biel/Bienne）",
      "url": "https://www.zefix.ch/ZefixREST/api/v1/firm/189146.json" }
  ]
}

**Reading it:**Contains-match hits historical names too. Each key has its use: ehraid unlocks the full record via ch_zefix_firm; uid_formatted (CHE-103.650.519) is the cross-database key for Swiss companies; status EXISTIEREND means active (German, verbatim). cantonal_excerpt_web links straight to the cantonal registry excerpt; shab_date is the latest Swiss Official Gazette of Commerce (SHAB) change.

company co_rues_companies#

Colombian company name / SoQL → chamber-of-commerce registry rows (RUES)

Parameters：

**Note:**Company (NIT) rows only — sole proprietors (registered under a personal id) are outside this query face; the master table has no address column (establishments live in a separate dataset); the legal representative comes as a name without an id number.

$ company co_rues_companies --where "razon_social like '%DIMPEL%'" --limit 3

{
  "reason": "CO RUES 登记主档：返回 1 行（offset=0 起；Socrata 无 total 回显）——matricula×NIT×CIIU（样例 DIMPEL SAS，NIT 900835212，SOCIEDADES POR ACCIONES SIMPLIFICADAS SAS）；基滤 clase_identificacion='NIT'（个体户生份号行不进面）、RL 号码列已剥离",
  "result": {
    "rows": [
      { "matricula": "2558821", "camara_comercio": "BOGOTA", "razon_social": "DIMPEL SAS",
        "clase_identificacion": "NIT", "numero_identificacion": "900835212", "digito_verificacion": "3",
        "organizacion_juridica": "SOCIEDADES POR ACCIONES SIMPLIFICADAS SAS",
        "cod_ciiu_act_econ_pri": "4741", "estado_matricula": "CANCELADA",
        "representante_legal": "PELAEZ VILLADA ALBERTO" }
    ],
    "count": 1, "limit_applied": 3
  },
  "evidence": [
    { "quote": "2558821 DIMPEL SAS — NIT 900835212-3（CANCELADA，CIIU 4741）",
      "url": "https://www.datos.gov.co/resource/c82u-588k.json" }
  ]
}

Reading it:matricula (registration number) is only unique together with camara_comercio — each chamber numbers its own; numero_identificacion + digito_verificacion form the NIT tax id with check digit; cod_ciiu_act_econ_pri is the primary industry code (4741=retail); estado_matricula is the registry status (ACTIVA=active / CANCELADA=cancelled — this sample row is a cancelled one; historical companies stay searchable); representante_legal is the legal representative's name (public officer information). --where takes a SoQL expression (e.g. razon_social like '%BANCOL%', estado_matricula='ACTIVA') and composes freely.

company fdic_institutions#

US bank registry search (FDIC)

Parameters：

**Note:**A CERT maps to exactly one institution; the institution name (brand wording) is never an identity key.

$ company fdic_institutions --filters "CERT:3510"

{
  "reason": "FDIC BankFind：命中 1 行，首选 3510 Bank of America, National Association（在业，Charlotte NC）",
  "result": {
    "cert": 3510,
    "name": "Bank of America, National Association",
    "city": "Charlotte",
    "state": "NC",
    "active": true,
    "established_date": "1904-10-17",
    "end_date": null,
    "report_date": "2026-06-30"
  },
  "evidence": [
    { "quote": "FDIC CERT 3510 = Bank of America, National Association（NC）",
      "url": "https://banks.data.fdic.gov/bankfind-suite/detail/institution/3510" }
  ]
}

Reading it:active: true = operating and insured. active: false is not "not found" — failed/surrendered/merged-out institutions stay in the registry, with end_date giving the insurance end date. report_date is the master-record reporting period; name is the full legal name (not the brand).

company fi_ytj_companies#

Finnish name / business-id → company record (YTJ v3)

Parameters：

**Note:**No paging channel for large result sets (the upstream ignores paging params); a business-id looks like 0205709-4.

$ company fi_ytj_companies --name "Nokia"

{
  "reason": "YTJ 名称检索：「Nokia」→ 991 家（返回 63 行——分页参上游无视，页大小恒 ~63），首选 Fysios Mehiläinen Oy（0194099-3，状态 2）——name 连历史名/分支名包含式匹配",
  "result": {
    "total_results": 991,
    "companies": [
      { "business_id": "0194099-3", "latest_name": "Fysios Mehiläinen Oy", "registration_date": "1975-01-10" },
      { "business_id": "0197067-4", "latest_name": "Tikkurila Oyj", "registration_date": "1917-07-26" }
    ]
  },
  "evidence": [
    { "quote": "「Nokia」991 家命中、返回恒 ~63 行；Tikkurila Oyj（0197067-4）这类远亲也被包含式带出",
      "url": "https://avoindata.prh.fi/opendata-ytj-api/v3/companies?name=Nokia" }
  ]
}

**Reading it:**Matching is substring-style and includes historical / branch names: "Nokia" drags in the Fysios physio chain and Tikkurila (a Nokia spin-off) — total_results is the true total (991 here); pin it down with the full name or a --business-id direct lookup. Paging params are silently ignored upstream — a fixed ~63-row page; narrow by a longer name instead.

company fr_recherche_search#

French company / officer name / SIREN → company record (annuaire)

Parameters：

Note:--q is required; officer-name search aggregates mandates across companies and namesakes are common — narrow and re-check by SIREN before persisting.

$ company fr_recherche_search --q "Dassault Aviation" --per-page 2

{
  "reason": "FR recherche：「Dassault Aviation」→ 69 家（页 1/35），首选 DASSAULT AVIATION（SIREN 712042456，A，dirigeants 13 行）——q 通吃名称/高管人名/SIREN",
  "result": {
    "total_results": 69, "total_pages": 35, "page": 1, "per_page": 2,
    "results": [
      { "siren": "712042456", "nom_complet": "DASSAULT AVIATION",
        "etat_administratif": "A", "date_creation": "1971-01-01",
        "categorie_entreprise": "GE", "tranche_effectif_salarie": "53", "tva": "FR73712042456",
        "dirigeants": [ { "type_dirigeant": "personne physique", "nom": "BOUMAZA", "prenoms": "BESMA",
          "date_de_naissance": "1976-07", "annee_de_naissance": 1976, "qualite": "Administrateur" } ],
        "siege": { "siret": "71204245600061", "est_siege": true,
          "adresse": "78 QUAI MARCEL DASSAULT 92210 SAINT-CLOUD", "code_postal": "92210" } }
    ]
  },
  "evidence": [
    { "quote": "DASSAULT AVIATION（SIREN 712042456，A，1971 年设立，GE 大企业档，dirigeants 13 行）",
      "url": "https://recherche-entreprises.api.gouv.fr/search?q=712042456" }
  ]
}

Reading it:siren is the French national key; tva is the VAT number (FR + check digits + SIREN); etat_administratif A=active / C=ceased (--etat-administratif filters for real — the upstream default does not); dirigeants is the directors/officers slot (individuals carry name + birth year-month, corporate ones a siren) — querying an officer's name as q searches these slots across companies; siege.siret is the head-office establishment key (SIREN + sequence); categorie_entreprise GE = large enterprise.

company gb_contracts_finder_published_notices#

UK sub-threshold contract notices (Contracts Finder)

Parameters：

**Note:**This complements Find a Tender, it does not replace it — above-threshold contracts are not on this face; notices published outside the window are not returned.

$ company gb_contracts_finder_published_notices --name "Suffolk" --limit 3

{
  "reason": "UK CF：「Suffolk」匹配 3 行 / 原页 100 行（buyer|suppliers contains，有下页可续走；窗 2026-10-19~2026-10-26）——门槛下面与 FTS 互补，supplier id 是 GB-COH/GB-CFS 注册键",
  "result": {
    "rows": [
      { "ocid": "ocds-b5fd17-070a79d6-…", "date": "2026-10-23T15:57:38+01:00", "tags": ["awardUpdate"],
        "buyer": "SUFFOLK COUNTY COUNCIL",
        "suppliers": ["Easy Cabs East Anglia Limited"],
        "supplier_ids": ["GB-CFS-339455"],
        "award_values": [ { "date": "2026-07-30T00:00:00+01:00", "amount": 198930, "currency": "GBP" } ],
        "tender_title": "QSB421 0900 2026-06-29 Mildenhall - Sendsory, Ipswich … - AWARD" }
    ],
    "has_more": true,
    "window": { "published_from": "2026-10-19", "published_to": "2026-10-26" },
    "matched_on": "buyer|suppliers contains"
  }
}

Reading it:award_values carries amount / currency / award date (198,930 GBP above); supplier_ids are GB-CFS registry keys (GB-COH company-number form also occurs); window echoes the publication window — the default is the last 7 days, and longer history needs explicit --published-from/--published-to ends. Same full-page-100-then-filter and cursor paging as FTS.

company gb_fts_release_packages#

UK above-threshold contract awards (Find a Tender)

Parameters：

**Note:**Contains-matching is the contract, not a defect — zero hits on the current page doesn't mean the base has none (keep paging with the cursor); --stages award|tender splits by stage, award by default.

$ company gb_fts_release_packages --name "NHS" --limit 3

{
  "reason": "UK FTS：「NHS」匹配 3 行 / 原页 100 行（buyer|suppliers contains，有下页可续走）——OCDS 面无名称检索参数，包含匹配是口径非缺陷",
  "result": {
    "rows": [
      { "ocid": "ocds-h6vhtk-04e32b", "date": "2026-10-26T09:34:13Z", "tags": ["award", "contract"],
        "buyer": "Velindre University NHS Trust",
        "suppliers": ["H Jenkinson & Co Ltd"],
        "supplier_ids": ["GB-FTS-187831"],
        "tender_title": "The procurement of office furniture for nVCC" }
    ],
    "next_cursor": "dXBkYXRlZFRvPTIw…",
    "has_more": true,
    "total_in_page": 100,
    "matched_on": "buyer|suppliers contains"
  }
}

**Reading it:**The upstream OCDS face has no name-search param — --name is a local contains filter: it fetches a full 100-row page first, then filters (total_in_page records the raw page size) and matched_on states whether the buyer or supplier name matched. supplier_ids are GB-FTS registry keys, ocid the OCDS global key; feed next_cursor back to page.

company gleif_direct_parent#

LEI → direct parent

Parameters：

**Note:**Only GLEIF-declared relationships count — with no declared parent (including self-reported "no parent"), the face honestly returns 404 "no parent"; no equity inference.

$ company gleif_direct_parent --lei "5493001KJTIIGC8Y1R12"

{
  "reason": "GLEIF 直接母公司：5493001KJTIIGC8Y1R12 → Bloomberg L.P.",
  "result": {
    "lei": "5493001KJTIIGC8Y1R12",
    "direct_parent": { "lei": "549300B56MD0ZC402L06", "legal_name": "Bloomberg L.P.", "entity_status": "ACTIVE", "jurisdiction": "US-DE" }
  },
  "evidence": [
    { "quote": "Bloomberg L.P.（LEI 549300B56MD0ZC402L06，ACTIVE）",
      "url": "https://api.gleif.org/api/v1/lei-records/549300B56MD0ZC402L06" }
  ]
}

Reading it:direct_parent is a complete identity card (legal name / LEI / status / jurisdiction) — no follow-up lookup needed. For the ultimate parent (top of the control chain), switch to gleif_ultimate_parent with the same LEI. The input is an LEI; if you don't have one, get it via gleif_lei_records_search first.

company gleif_lei_records#

LEI → company identity card

Parameters：

**Note:**Only a well-formed 20-character ISO 17442 LEI is accepted; malformed input exits 2 without calling upstream. The card reports the official registration only — no subject merging.

$ company gleif_lei_records --lei "5493001KJTIIGC8Y1R12"

{
  "reason": "GLEIF 归一：LEI 5493001KJTIIGC8Y1R12 → Bloomberg Finance L.P.（ACTIVE）",
  "result": {
    "lei": "5493001KJTIIGC8Y1R12",
    "legal_name": "Bloomberg Finance L.P.",
    "entity_status": "ACTIVE",
    "jurisdiction": "US-DE",
    "registration_country": "US",
    "hq_city": "New York",
    "bic": null,
    "mic": null,
    "legal_form": { "id": "T91T", "other": null },
    "creation_date": "2007-06-05",
    "expiration": { "date": null, "reason": null },
    "successor_entities": [],
    "registration": { "status": "ISSUED", "last_update": "2026-01-05T14:20:40Z", "next_renewal_date": "2027-01-25T16:50:02Z", "registered_as": "4348344" }
  },
  "evidence": [
    { "quote": "LEI 5493001KJTIIGC8Y1R12 = Bloomberg Finance L.P.（ACTIVE，US-DE）",
      "url": "https://api.gleif.org/api/v1/lei-records/5493001KJTIIGC8Y1R12" }
  ]
}

**Reading it:**The identity card as registered in GLEIF. entity_status is the company's operating status (ACTIVE = operating); registration.status is the status of the LEI itself (ISSUED = validly issued) — two different things, and a LAPSED registration on an operating company is a common combination. next_renewal_date is the next annual renewal; an overdue LEI loses reference value. registration.registered_as is the national-registry id join key (here the Delaware file number 4348344) — join across registries on it, not on names. bic/mic and legal_form.id (the GLEIF ELF code, T91T here) are slots only the LOU could have captured — null means not captured, not an error. successor_entities is the M&A successor LEI list — upstream names are null in practice, resolve each LEI via this same face (live anchor: Nestlé Canada's successor = 8945002SOXKVMWPWUH46).

company gleif_lei_records_search#

Company name → LEI candidates

Parameters：

**Note:**Candidates ≠ verdicts: zero hits is a legal answer (not an error); confirm with gleif_lei_records before persisting. --page-size caps at 200 rows per call. The jurisdiction param filters, it does not transform — a broad name plus a narrow jurisdiction is the intended use.

$ company gleif_lei_records_search --filter-entity-legal-name "Bloomberg Finance L.P." --filter-entity-jurisdiction US-DE --page-size 3

{
  "reason": "GLEIF 名称反查：2 候选（辖域 US-DE 过滤），首选 Bloomberg Finance L.P.（LEI 5493001KJTIIGC8Y1R12，ACTIVE）——法定名包含匹配非模糊容错，候选非权威归一，落库前以 gleif_lei_records 复核",
  "result": {
    "total": 2,
    "page": { "currentPage": 1, "perPage": 3, "from": 1, "to": 2, "total": 2, "lastPage": 1 },
    "candidates": [
      { "lei": "5493001KJTIIGC8Y1R12", "legal_name": "Bloomberg Finance L.P.", "entity_status": "ACTIVE", "jurisdiction": "US-DE", "registration_country": "US", "registered_as": null },
      { "lei": "254900JY1M565T6QM850", "legal_name": "Bloomberg Finance Singapore L.P.", "entity_status": "ACTIVE", "jurisdiction": "US-DE", "registration_country": "US", "registered_as": null }
    ],
    "limit_applied": 3
  }
}

**Reading it:**Matching is legal-name contains, not fuzzy tolerance — precise keywords beat exhaustive variants. total is the full match count, not the number returned. Narrow with --filter-entity-jurisdiction (ISO country or region code, e.g. CH, US-MO) or --filter-entity-status (ACTIVE/INACTIVE/NULL). Candidate rows carry registered_as, the national-registry id — present only when the LOU captured it (both examples above are null; live anchor: Nestlé Purina under US-MO = 00007498); join across registries on it, not on names; page.lastPage is the honest walk bound for --page-number.

company gleif_ultimate_parent#

LEI → ultimate controller

Parameters：

**Note:**Only GLEIF-declared relationships count — with no declared ultimate parent the face honestly returns 404; no equity inference.

$ company gleif_ultimate_parent --lei "5493001KJTIIGC8Y1R12"

{
  "reason": "GLEIF 终极母公司：5493001KJTIIGC8Y1R12 → Bloomberg Inc.",
  "result": {
    "lei": "5493001KJTIIGC8Y1R12",
    "ultimate_parent": { "lei": "549300RMUDWPHCUQNE66", "legal_name": "Bloomberg Inc.", "entity_status": "ACTIVE", "jurisdiction": "US-DE" }
  },
  "evidence": [
    { "quote": "Bloomberg Inc.（LEI 549300RMUDWPHCUQNE66，ACTIVE）",
      "url": "https://api.gleif.org/api/v1/lei-records/549300RMUDWPHCUQNE66" }
  ]
}

**Reading it:**Picking up from the previous face: Bloomberg Finance L.P.'s direct parent is Bloomberg L.P.; the ultimate parent is one level higher still, Bloomberg Inc. — the gap between the two faces is the depth of the control chain. The output is again a complete identity card (no follow-up needed); to walk the chain level by level yourself, call gleif_direct_parent repeatedly.

company kr_hometax_biz_status#

Korean business number → open / closed / unregistered (NTS)

Parameters：

**Note:**One number per call — batch checks go one by one (politeness rate limit); this is a status lookup, not a roster source ('list all companies' is not possible); unregistered means the number does not exist or is mistyped — a different thing from closed.

$ company kr_hometax_biz_status --biz-no 124-81-00998

{
  "reason": "KR hometax：1248100998 → 营业（부가가치세 일반과세자 입니다.）——未注册也是 result=S 合法答案（VIES INVALID 同族）；txprNm 匿名恒 null",
  "result": {
    "status": { "biz_no": "1248100998", "state": "active", "registered": true,
      "tax_type": "부가가치세 일반과세자 입니다.",
      "english_status": "The business registration number is registered" }
  },
  "evidence": [
    { "quote": "1248100998：부가가치세 일반과세자 입니다.｜英文：The business registration number is registered",
      "url": "https://hometax.go.kr/wqAction.do?actionId=ATTABZAA001R08" }
  ]
}

Reading it:state has four values: active (open, tax_type carries the tax-type text verbatim) / closed (deregistered, closed_date is the closure date) / unregistered (the NTS has no such number — a legal answer, not an error) / error (malformed upstream payload, passed through). The number may carry hyphens (124-81-00998) or be 10 bare digits. The lookup is anonymous — no owner name is disclosed.

company no_brreg_enheter#

Norwegian name / org number → master record (Brreg)

Parameters：

Note:--navn is the upstream's real param name (spelling it name gets a 400); with an org number, prefer the direct --organisasjonsnummer lookup; search paging is --page (0-based) and --size (cap 100).

$ company no_brreg_enheter --navn "Equinor" --size 3

{
  "reason": "Brreg 名称检索：命中 179 家，首选 EQUINOR ASA（923609016）——navn 是挪威语原名参数（?name= 400）",
  "result": {
    "enheter": [
      { "organisasjonsnummer": "923609016", "navn": "EQUINOR ASA",
        "organisasjonsform": { "kode": "ASA", "beskrivelse": "Allmennaksjeselskap" },
        "naeringskode1": { "kode": "06.100", "beskrivelse": "Utvinning av råolje" },
        "antall_ansatte": 21231,
        "konkurs": false, "under_avvikling": false,
        "registrert_i_foretaksregisteret": true, "registrert_i_mva_registeret": true }
    ]
  },
  "evidence": [
    { "quote": "EQUINOR ASA（923609016，ASA，雇员 21,231，行业 06.100 原油开采）",
      "url": "https://data.brreg.no/enhetsregisteret/api/enheter/923609016" }
  ]
}

Reading it:organisasjonsnummer is the Norwegian national key — feed it to no_brreg_roller for roles; naeringskode1 is the industry code; antall_ansatte the headcount; negative flags are independent (konkurs bankrupt / under_avvikling in liquidation); the two register bits say whether it is listed in the company register / the VAT register.

company no_brreg_roller#

org number → Norwegian role register (CEO / board / auditors, Brreg)

Parameters：

**Note:**Takes only the org number (enheter rows carry it); the STYR group shows 1 of the 13 seats captured — the real output is longer, excerpted here.

$ company no_brreg_roller --organisasjonsnummer 923609016

{
  "reason": "Brreg 角色面：923609016 → 3 组 15 席（Anders Opedal; Jarle Kjell Roth; Finn Bjørn Ruyter…）——人名+出生日期可收（公开面无人份证号）；avregistrert=true=已退任",
  "result": {
    "organisasjonsnummer": "923609016",
    "rollegrupper": [
      { "type_kode": "DAGL", "type_beskrivelse": "Daglig leder",
        "roller": [ { "kode": "DAGL", "person": { "navn": "Anders Opedal", "fodselsdato": "1968-05-04", "er_doed": false }, "avregistrert": false } ] },
      { "type_kode": "STYR",
        "roller": [ { "kode": "LEDE", "person": { "navn": "Jarle Kjell Roth", "fodselsdato": "1960-04-26" } } ] },
      { "type_kode": "REVI",
        "roller": [ { "kode": "REVI", "enhet_organisasjonsnummer": "976389387" } ] }
    ]
  },
  "evidence": [
    { "quote": "DAGL 1 席 Anders Opedal（1968-05-04）；STYR 13 席；REVI 1 席=法人审计（组织号 976389387）",
      "url": "https://data.brreg.no/enhetsregisteret/api/enheter/923609016/roller" }
  ]
}

**Reading it:**The result key is rollegrupper (grouped, not a flat roller list); person slots carry navn + fodselsdato (no national id on the public face — birth dates are for telling namesakes apart), corporate slots go by enhet_organisasjonsnummer — here the REVI group is an audit firm; avregistrert: true marks a relinquished role.

company nzco_companies#

New Zealand company name → register rows (company number + NZBN dual keys, Companies Office)

Parameters：

**Note:**The search surface is the register's UI (no published API contract) and rides a politeness rate; zero hits are not an error — an empty page comes back (count=0); for current directors feed the company number to nzco_directors.

$ company nzco_companies --q "air new zealand"

{
  "reason": "NZ Companies Office: 'air new zealand' → 15 companies (rows 1..15, 15/page, more pages)",
  "result": {
    "rows": [
      { "name": "AIR NEW ZEALAND HOLIDAYS LIMITED", "company_number": "116030", "nzbn": "9429032058956",
        "status": "Removed", "entity_type": "NZ Limited Company",
        "address": "Air New Zealand House, 185 Fanshawe Street, Auckland 1010, New Zealand" },
      { "name": "AIR NEW ZEALAND CONSULTING LIMITED", "company_number": "1837975", "nzbn": "9429034008171",
        "status": "Removed", "entity_type": "NZ Limited Company", "address": null },
      { "name": "AIR NEW ZEALAND ASSOCIATED COMPANIES LIMITED", "company_number": "102153", "nzbn": "9429040422305",
        "status": "Registered", "entity_type": "NZ Limited Company", "address": null }
    ],
    "count": 15, "start": 0, "limit": 15, "has_next": true
  },
  "evidence": [
    { "quote": "116030 AIR NEW ZEALAND HOLIDAYS LIMITED — NZBN 9429032058956 (Removed)",
      "url": "https://app.companiesoffice.govt.nz/companies/app/ui/pages/companies/search" }
  ]
}

Reading it:company_number and nzbn (the 16-digit New Zealand Business Number) are the dual official keys — the latter is the cross-government join key; status is the register's own word (Registered / Removed — there is no "Active", carried verbatim untranslated); has_next is derived from the pager's own offsets (no total echo upstream); --entity-types takes the filter form's own checkbox codes (LTD/UNLTD/COOP = NZ companies, ASIC/NON_ASIC = overseas); paging is --start row offset + --limit, with only 5 and 15 ever observed live — other sizes are unpinned upstream and refused.

company nzco_directors#

NZ company number → current-directors roster (statutory name / residential address / appointment date)

Parameters：

**Note:**The company number is digits only (104799 = Air New Zealand Limited — find it with nzco_companies first); an unknown number answers 404 (upstream_not_found); former directors are outside this face.

$ company nzco_directors --company-number 104799

{
  "reason": "NZ Companies Office: AIR NEW ZEALAND LIMITED (104799, Registered) → 8 current directors — names and residential addresses are the register's statutory public record",
  "result": {
    "company_name": "AIR NEW ZEALAND LIMITED", "company_number": "104799", "status": "Registered",
    "rows": [
      { "name": "Neal Anthony BARCLAY", "appointment_date": "01 May 2025",
        "address": "17 Bradey Road, Rd 1, Porirua, 5381, New Zealand" },
      { "name": "Claudia Isobel BATTEN", "appointment_date": "28 Oct 2021",
        "address": "1 Hadfield Road, Rd 1, Waikanae, 5391, New Zealand" },
      { "name": "Dean John BRACEWELL", "appointment_date": "20 Apr 2020",
        "address": "114 Lucerne Road, Remuera, Auckland, 1050, New Zealand" }
    ],
    "count": 8
  },
  "evidence": [
    { "quote": "Neal Anthony BARCLAY — appointed 01 May 2025, 17 Bradey Road, Rd 1, Porirua, 5381, New Zealand",
      "url": "https://app.companiesoffice.govt.nz/companies/app/ui/pages/companies/104799/directors" }
  ]
}

**Reading it:**The page H1 confirms company name + number + status together (a number mismatch refuses to emit rows — no cross-company attribution); only current directors return — the ceased/former section renders in different markup and never enters; appointment_date is the register's own wording ("01 May 2025", not ISO-normalized); the residential address is statutory-public in NZ and may arrive partially masked since the privacy-law change — carried verbatim, never reconstructed.

company ror_organizations#

Name / ROR id → research-organization record

Parameters：

**Note:**Candidates are non-authoritative — re-check with the exact --ror-id card before persisting; pages are fixed at 20 rows (--page); zero hits is a legal answer — retry with an alias.

$ company ror_organizations --query "Broad Institute"

{
  "reason": "ROR 名称检索：「Broad Institute」 → Broad Institute（United States，funder）——候选非权威归一（每页固定 20 条）",
  "result": {
    "candidates": [
      { "ror_id": "05a0ya142", "name": "Broad Institute",
        "aliases": ["Broad Institute of MIT and Harvard", "El Instituto Broad"],
        "type": "funder", "country": "United States", "country_code": "US", "status": "active",
        "established": 2004, "website": "http://www.broadinstitute.org/",
        "external_ids": { "fundref": "100013114", "grid": "grid.66859.34", "isni": "0000 0004 0546 1623", "wikidata": "Q4971893" } }
    ]
  }
}

Reading it:ror_id is the stable org key — grant and publication linking hang off it. type is the org type (funder here; also education / company / healthcare …); external_ids bridges libraries — fundref to grant databases, isni to bibliographic databases, grid the legacy id.

company sec_fulltext_search#

Full-text search across SEC filings (EDGAR)

Parameters：

**Note:**The body layer starts at 2001; earlier filings are outside full-text search.

$ company sec_fulltext_search --q "rare earth" --forms 10-K --limit 2

{
  "reason": "EDGAR FTS：3145 命中（2001+ 正文级），返回 2 行——adsh 与 sec 批线语料同键",
  "result": {
    "total": 3144,
    "total_relation": "eq",
    "hits": [
      { "adsh": "0001580695-19-000462", "cik": "0001445942",
        "company": "Texas Mineral Resources Corp.",
        "form_type": "10-K", "file_date": "2019-11-27",
        "doc_url": "https://www.sec.gov/Archives/edgar/data/1445942/000158069519000462/ex10-17.htm" },
      { "adsh": "0000950123-11-023641", "cik": "0001489137",
        "company": "Molycorp, Inc.",
        "form_type": "10-K", "file_date": "2011-03-09",
        "doc_url": "https://www.sec.gov/Archives/edgar/data/1489137/000095012311023641/d79946e10vk.htm" }
    ]
  }
}

Reading it:total is the hit count; total_relation: eq = exact, gte = over the count cap (at least this many). Each row's doc_url opens the source document; adsh is the filing accession key, the same key as the official SEC bulk archive. The Texas Mineral Resources Corp. hit above can be followed with sec_submissions --cik — the rename-history example on that face comes from exactly this row.

company sec_submissions#

CIK → SEC filer profile

Parameters：

**Note:**A CIK maps to exactly one registrant (10-digit zero-padded form as upstream serves it); an empty tickers array means no registered trading face, not missing data.

$ company sec_submissions --cik "0001445942"

{
  "reason": "SEC 归一：CIK 1445942 → DyTb, LLC（无 ticker——非上市或未登记交易面），Non-accelerated filer<br>Smaller reporting company",
  "result": {
    "cik": "0001445942",
    "name": "DyTb, LLC",
    "entity_type": "operating",
    "tickers": [],
    "exchanges": [],
    "ein": "870294969",
    "sic": { "code": "1040", "description": "Gold and Silver Ores" },
    "filer_category": "Non-accelerated filer<br>Smaller reporting company",
    "state_of_incorporation": "DE",
    "fiscal_year_end": "0831",
    "former_names": [
      { "name": "Texas Mineral Resources Corp.", "from": "2016-04-14", "to": "2026-07-28" },
      { "name": "Texas Rare Earth Resources Corp.", "from": "2011-02-08", "to": "2016-03-18" }
    ],
    "business_address": { "city": "STILLWATER", "state_or_country": "OK", "state_or_country_name": "OK", "country": null },
    "recent_filings_count": 558,
    "filings_total": 558,
    "last_filing_date": "2026-08-20"
  },
  "evidence": [
    { "quote": "CIK 0001445942 = DyTb, LLC（EIN 870294969，SIC 1040 Gold and Silver Ores）",
      "url": "https://data.sec.gov/submissions/CIK0001445942.json" }
  ]
}

**Reading it:**This example relays with the sec_fulltext_search face below: Texas Mineral Resources Corp., hit by the full-text search, turns out to have been renamed DyTb, LLC in 2026-07 — filing history spans the rename; CIK never breaks. former_names is the chain of former names (with from/to dates); filings_total is the total filing count (recent_filings_count is the recent window only); sic is the industry code; state_of_incorporation is the state of incorporation (DE = Delaware).

company ted_notices_search#

EU tender notice search (TED)

Parameters：

**Note:**Pages hold 1–250 notices (--limit); prefix names do not consolidate groups — narrow to the target subject by VAT/LEI before persisting.

$ company ted_notices_search --query "organisation-name-buyer=Siemens* AND organisation-country-buyer=DEU" --limit 3

{
  "reason": "TED v3：「organisation-name-buyer=Siemens* AND organisation-country-buyer=DEU」3 行（满页，可能还有）——名称前缀拼 buyer 面（尾通配），母子集团不合并，落库前以 VAT/LEI 收窄",
  "result": {
    "has_more": true,
    "notices": [
      { "publication_number": "671086-2023", "publication_date": "2023-11-03",
        "title": "Germany – Customer survey services – Befragungssoftware …",
        "notice_type": "cn-standard",
        "buyer": "SBK Siemens-Betriebskrankenkasse", "buyer_country": ["DEU"],
        "total_value": 661000,
        "xml_url": { "MUL": "https://ted.europa.eu/en/notice/671086-2023/xml" } }
    ]
  }
}

Reading it:--query passes the upstream expert syntax verbatim: organisation-name-buyer=Siemens* trailing wildcard = prefix match, AND-combines country (ISO-3) / CPV. publication_number is the stable key and xml_url points at the official source notice. has_more: true means more pages.

company usaspending_spending_by_award#

US federal contracts & grants (by recipient)

Parameters：

**Note:**One window end suffices (the other is auto-completed); give both when narrowing a history window. The default queries contract types A,B,C,D — grants need --award-type-codes 02,03…. Narrow to the target subject by CIK/UEI before persisting.

$ company usaspending_spending_by_award --recipient-search-text "Lockheed Martin" --start-date 2007-10-01 --end-date 2007-12-31 --limit 2

{
  "reason": "USAspending：「Lockheed Martin」A,B,C,D 型 2 行，受款时段 2007-10-01~2007-12-31（page_metadata.hasNext=还有更多，--page 续页）——名称拼接受款人，母子集团不合并，落库前以 CIK/UEI 收窄",
  "result": {
    "awards": [
      { "award_id": "Z201", "recipient_name": "LOCKHEED MARTIN INTEGRATED SYSTEMS, LLC",
        "award_amount": 1074770.37, "start_date": "2006-09-28", "end_date": "2011-09-27",
        "awarding_agency": "Department of Defense",
        "generated_internal_id": "CONT_AWD_Z201_9700_W91QUZ04D0004_9700" }
    ],
    "has_more": true,
    "date_range": { "startdt": "2007-10-01", "enddt": "2007-12-31" }
  }
}

**Reading it:**Each awards[] row is one award: amount, period, awarding agency (the Department of Defense above). Read the period semantics right: the window matches contracts whose span overlaps it (the long-term contract signed in 2006 therefore hits the 2007Q4 window), not awards starting inside it. has_more: true means more pages (--page walks them). Name matching does not consolidate groups — Lockheed Martin subsidiaries account separately; narrow to a specific subject by CIK/UEI.

company vies_vat#

EU VAT number official validation (VIES)

Parameters：

**Note:**The number must carry the member-state prefix (e.g. DE811907980); whether name/address are disclosed follows each member state's policy.

$ company vies_vat --vat DE811907980

{
  "reason": "VIES 校验：DE811907980 有效（DE，成员国遮蔽名址（--- → null，非缺数）)",
  "result": {
    "valid": true,
    "user_error": "VALID",
    "country_code": "DE",
    "vat_number": "DE811907980",
    "name": null,
    "address": null,
    "request_date": "2026-10-23T04:18:21.887Z",
    "approximate": { "name": "---", "matchName": 3 }
  }
}

Reading it:valid: true is the official confirmation; invalid is equally a legal answer (ok: true, valid: false) — not a query failure. null name/address is member-state privacy masking (the raw "---" mapped faithfully), not missing data; the approximate block is a fuzzy-match reference. request_date is there for audit trails.

The fine print#

• Country fields come in three forms: subject country values appear side by side as Chinese / ISO2 / English; cross-source merging keys on strong identifiers, and name matching carries a country constraint.
• Relationships = direct disclosure evidence: only relationships stated verbatim in announcements (customer / supplier / subsidiary) are recorded — no extrapolation into a complete supply chain; a relationship's effective period follows the disclosure period.
• Qualification history is never deleted: multiple batches and years of the same qualification coexist as rows; "active" = the most recent published status — verify expiry against new publications.
• Negative facts labeled independently: penalty / disqualification and other negative polarities never enter the "active" status.
• Securities keys are never merge keys: stock codes / tickers are resolved back to the subject via company_listing and never used to decide "same company".