nbb-client

A robust, type-safe Node.js client for the National Bank of Belgium (NBB) CBSO API.

It simplifies fetching financial data, parses complex XBRL deposits into usable JSON, and automatically calculates key financial ratios (ROE, Liquidity, Solvency, etc.) with multilingual labels (EN, FR, NL).

Features

• 🚀 Easy API: Simple getFinancials(enterpriseNumber) method.
• 📊 Automatic Ratios: Calculates Net Profit Margin, Current Ratio, Debt-to-Equity, and more.
• 🌍 Multilingual: Full support for English, French, and Dutch labels.
• ⚡ Built-in Caching: File-system caching to avoid redundant API calls and rate limits.
• 📅 Multi-Year Support: Fetch the latest year, last N years, or all available history.
• 💾 Raw Data Mode: Option to retrieve pure XBRL data without calculations.
• 🛠️ CLI Tool: Includes a command-line tool for quick lookups.
• 📦 Zero Runtime Dependencies: Lightweight and fast (uses native fetch).

Installation

npm install nbb-client

Usage

Basic Usage

import { NbbClient } from 'nbb-client';

const client = new NbbClient('YOUR_NBB_SUBSCRIPTION_KEY');

async function main() {
    try {
        // Fetch latest financials for a company (e.g., 0462.925.669)
        const data = await client.getFinancials('0462925669');

        console.log(`Year: ${data.year}`);
        console.log(`Revenue: ${data.ratios.revenue.value}`);
        console.log(`Net Profit Margin: ${data.ratios.net_profit_margin.value}`);
        
        // Access multilingual labels
        console.log(data.ratios.net_profit_margin.label_en); // "Net Profit Margin"
        console.log(data.ratios.net_profit_margin.label_fr); // "Marge bénéficiaire nette"

    } catch (err) {
        console.error(err);
    }
}

main();

Caching (Optional but Recommended)

To avoid hitting NBB rate limits and speed up repeated lookups, you can optionally provide a cache implementation. We provide a simple FileSystemCache, but you can implement the ICache interface for Redis, Memcached, etc.

import { NbbClient, FileSystemCache } from 'nbb-client';

// Without cache (default)
// const client = new NbbClient('YOUR_KEY');

// With file-system cache
const client = new NbbClient('YOUR_KEY', {
    cache: new FileSystemCache('./.nbb-cache')
});

Multi-Year Retrieval

// Fetch last 3 years
const history = await client.getFinancials('0462925669', { limit: 3 });

// Fetch ALL available years
const fullHistory = await client.getFinancials('0462925669', { all: true });

Raw Data Only

If you don't need the calculated ratios:

const raw = await client.getFinancials('0462925669', { includeRatios: false });
console.log(raw.raw['70']); // Access raw XBRL rubric 70 (Turnover)

CLI Usage

You can use the client directly from your terminal:

# Fetch latest data
npx nbb-client 0462925669 --key YOUR_KEY

# Fetch last 3 years
npx nbb-client 0462925669 --limit 3 --key YOUR_KEY

# Output raw JSON
npx nbb-client 0462925669 --json --key YOUR_KEY

License

MIT