@varve/bis-stats-api

An isomorphic, Zod-validated TypeScript client for the BIS Stats SDMX API.

The BIS API implements a subset of SDMX REST v1.4. @varve/bis-stats-api wraps the data, data availability, and structure endpoints with typed request parameters while returning SDMX CSV, XML, EDI, or parsed SDMX JSON.

Installation

npm install @varve/bis-stats-api zod

Quick Start

import { BisStatsClient } from '@varve/bis-stats-api';

const client = new BisStatsClient();

const csv = await client.getDataCsv('WS_EER', {
  key: 'M.N.B.CH',
  lastNObservations: 12,
  detail: 'dataonly',
});

console.log(csv);

Data Queries

BIS data queries follow the SDMX v1.4 path shape /data/{flow}/{key}/all.

const csv = await client.getDataCsv('WS_EER', {
  key: 'M.N.B.CH',
  startPeriod: '2020-01',
  endPeriod: '2020-12',
});

const json = await client.getDataJson('BIS,WS_EER,1.0', {
  key: 'M.N+R.B.CH',
  lastNObservations: 2,
});

const xml = await client.getData('WS_EER', {
  key: 'M.N.B.CH',
  format: 'genericXml',
  lastNObservations: 1,
});

Availability Queries

Use availability constraints to discover valid dimension values for a flow and partial key.

const availability = await client.getAvailabilityJson('WS_EER', {
  key: 'M.N.B.',
  componentId: 'all',
  mode: 'available',
});

Structure Metadata

const flows = await client.listDataflows({ detail: 'allstubs' });
const eer = await client.getDataflow('WS_EER', { references: 'children' });
const codelists = await client.getCodelists({ resourceId: 'all', version: 'latest' });

The generic structure helper can access any structure resource exposed in the BIS OpenAPI document:

const categories = await client.getStructureResourceJson('categoryscheme', {
  agencyId: 'all',
  resourceId: 'all',
  version: 'latest',
});

Configuration

const client = new BisStatsClient({
  baseUrl: 'https://stats.bis.org/api/v1',
  timeoutMs: 30_000,
  userAgent: '@your/app',
});

Error Handling

import { BisStatsApiError, BisStatsResponseError } from '@varve/bis-stats-api';

try {
  await client.getDataJson('missing');
} catch (err) {
  if (err instanceof BisStatsApiError) {
    console.error(err.status, err.body, err.retryAfterMs);
  }
  if (err instanceof BisStatsResponseError) {
    console.error('Unexpected JSON payload:', err.body);
  }
}

Development

npm run test:unit -w @varve/bis-stats-api
npm run typecheck -w @varve/bis-stats-api
npm run build -w @varve/bis-stats-api

References

• BIS Stats API: https://stats.bis.org/api/v1
• SDMX REST v1.4: https://github.com/sdmx-twg/sdmx-rest/tree/v1.4.0