SDKs & widgets

Install

Three official packages: a JavaScript / TypeScript client, a Python client and React widgets that render a fund response as charts and tiles. Source for all three is on GitHub.

npm install @fundfactsapi/sdk       # JavaScript / TypeScript
npm install @fundfactsapi/widgets   # React widgets
pip install git+https://github.com/fundfactsapi/fundfactsapi-python   # Python (installs from GitHub until the package is on PyPI)

The Python package is not on PyPI yet; pip installs it from the GitHub repository. It needs Python 3.9 or later and has no third-party dependency.

JavaScript / TypeScript

new FundFacts(options) reads the key from apiKey or FUNDFACTS_API_KEY; options also take baseUrl, timeoutMs (300 000 by default, because a cold fund can take up to 300 seconds), a custom fetch and cache (true by default). Every method returns the parsed JSON body with the same shape as the REST endpoint; types are exported for every response.

ts
import { FundFacts, FundFactsError } from "@fundfactsapi/sdk";
​
const ff = new FundFacts({ apiKey: process.env.FUNDFACTS_API_KEY });
const fund = await ff.getFund("IE00B4L5Y983");
console.log(fund.name, fund.data.headlineMetrics.ter, fund.data.profile.category);
​
const batch = await ff.getFunds(["IE00B4L5Y983", "IE00B3RBWM25"]);
const hits = await ff.search("world equity", 5);

Python

FundFacts(api_key=None, base_url=…, timeout=300.0, cache=True, retry_on_burst=True) reads the key from api_key or FUNDFACTS_API_KEY. Every method returns the parsed JSON body as a dict and raises FundFactsError on a non-2xx status. With retry_on_burst a 429 whose reason is the per-minute burst limit is retried once after Retry-After.

python
from fundfacts import FundFacts, FundFactsError
​
ff = FundFacts()  # reads FUNDFACTS_API_KEY
fund = ff.get_fund("IE00B4L5Y983")
print(fund["name"], fund["data"]["headlineMetrics"]["ter"], fund["data"]["profile"]["category"])
​
try:
    look = ff.portfolio([{"isin": "IE00B4L5Y983", "weight": 60}, {"isin": "IE00B3RBWM25", "weight": 40}])
except FundFactsError as e:
    print(e.status, e.code, e.message, e.retry_after)

React widgets

@fundfactsapi/widgets takes the envelope returned by GET /funds/{isin} (or the demo endpoint) and renders it; React 18 or later, no CSS to import. Fetch on the server with the SDK and pass the result down: the API key never reaches the browser.

tsx
import { FundFacts } from "@fundfactsapi/sdk";
import { FundFactsheet } from "@fundfactsapi/widgets";
​
const fund = await new FundFacts({ apiKey: process.env.FUNDFACTS_API_KEY }).getFund("IE00B4L5Y983");
export default function Page() {
  return <FundFactsheet fund={fund} />;
}

Errors and cache

Both clients throw or raise FundFactsError on any non-2xx status, with status, the API's code and message (see errors), retryAfter / retry_after from the Retry-After header when there is one, and the parsed body. Both keep an in-memory cache of getFund / get_fund responses until their expiresAt, so repeating a lookup within 24 hours costs no request; pass cache: false / cache=False to disable it.

Links