titelia

Which funds hold a listed company, and what a fund holds.

Which funds hold a listed company, and what any fund holds - read from the filings funds make to their regulators (SEC, CVM, CNMV, Finansinspektionen, SEBI) and from the reports European funds publish themselves.

The half nobody else republishes is that second one: a fund that files nowhere in the United States still has to publish its portfolio, and those documents are read here.

No API key, no account, no quota to apply for. Every figure here was published by a public source; whoever republishes it should say so, and every answer carries the sentence to do it with.

• The API: https://titelia.com
• Human documentation: https://titelia.com/en/api
• The contract: openapi.json, also served live at https://titelia.com/api/openapi.json
• The site: https://titelia.com

Install

npm install titelia

import { company, companyHolders, fund, ApiError } from 'titelia';

// Air Liquide: the funds that hold it, and what share of the company they own.

Zero dependencies, ESM, Node 18 or newer. The client is a thin layer: it builds the addresses, reads refusals as problem documents, and follows pages. Nothing stops you from calling the API with curl.

Endpoints

| Address | Answers | | --- | --- | | GET /api/company/{isin} | Which funds hold one company | | GET /api/fund/{id} | What one fund holds | | GET /api/company/{isin}.csv | The same table, as a file | | GET /api/fund/{id}.csv | The same table, as a file | | GET /api/isins | Every company served: one ISIN and one address per line | | GET /api/openapi.json | The contract, generated from the constants the code serves | | GET /api | The human documentation, in three languages |

The conventions, which are the same across the fleet

This API answers by the same convention as its two siblings (auregistre, titelia, quivad). What holds for one holds for the three.

• No version in the address, and none in the body. The promise that replaces it is written in x-stability of the contract: a field may be added, none is removed or renamed under a caller, and an address does not move.
• Refusals are RFC 9457 problem documents, served as application/problem+json. type is a documentation anchor that opens in a browser; title, status and detail say the rest. An error is never an HTML page - a program that calls .json() on one gets a parse error and goes looking for the fault in the wrong place.
• Long collections are cut by limit and offset, never silently. The page block carries total, more, and the absolute address of the next and previous pages; the same two links travel in the Link header. An unreadable parameter falls back to the default rather than refusing, and an offset past the end is an empty list, not an error.
• Every address in an answer is absolute. A response stored on somebody's disk has to say which host it came from.
• source and served_by answer two different questions: who PRODUCED the figures, and who ANSWERED. Confusing them is how a republished figure gets credited to the wrong party.
• Every answer carries a weak ETag and honours If-None-Match: hand it back and get a 304 with no body.
• Discovery links on every answer (RFC 8631): service-desc points at the contract, service-doc at the human documentation. One answer in hand is enough to find the whole specification.
• Rate limited by address, on /api only, and a cached answer does not count. A 429 carries retry-after and says how long to wait in the body.

What the data does not say

• A position is the most recent declaration of a fund, never a sum. A line that was sold disappears from the next report, and therefore from the site.
• Only the equity pocket is covered on the regulator side: neither bonds, nor derivatives, nor cash. A fund read from its own report carries what the document carries.
• No amount is rewritten into another currency. The currency travels beside every figure; only a total that adds several of them is converted, and it says so.
• The number of shares outstanding exists for American companies alone, so the share of capital does too. capital is null elsewhere rather than zero.

Examples

Runnable, in examples/: curl.sh, node.mjs, python.py.

Licence

The client code in this repository is MIT (see LICENSE).

The data is not covered by that licence: Public filings of the fund regulators (SEC, CVM, CNMV, FI, SEBI) and published fund reports. Cite the source when you republish it - every answer carries the sentence to do it with.

Reporting something wrong

A wrong line is worth an issue: https://github.com/titelia/api/issues. Name the address you called and what you expected; the answer carries served_by, which is what says the figure came from here rather than from the register itself.