Getting Started

Prerequisites

• Node.js 18 or later, or any runtime with the standard fetch API
• TypeScript recommended
• zod installed as a peer dependency

Install one package

Each SDK is independent. Install the provider you need:

npm install @varve/statcan-wds zod

Install more than one when your application crosses sources:

npm install @varve/statcan-wds @varve/worldbank-api @varve/fred-api zod

Make a first request

This example fetches the latest 12 observations for a Statistics Canada vector.

import { StatCanClient } from '@varve/statcan-wds';
 
const client = new StatCanClient();
 
const result = await client.getDataFromVectorsAndLatestNPeriods([
  { vectorId: 41690973, latestN: 12 },
]);
 
const series = result[0].object;
 
if (series) {
  for (const point of series.vectorDataPoint) {
    console.log(point.refPer, point.value);
  }
}

If the response returns, it has passed the SDK's Zod validation boundary.

Choose the right client

Not sure which package you need? Use Choosing a Provider.

Common starting points:

Configuration

Clients accept small configuration objects. The most common options are baseUrl, maxRetries, and, where supported, timeoutMs.

const client = new StatCanClient({
  baseUrl: 'https://www150.statcan.gc.ca/t1/wds/rest',
  maxRetries: 3,
});

Providers that require credentials expose explicit configuration. FRED requires an API key:

import { FredClient } from '@varve/fred-api';
 
const fred = new FredClient({
  apiKey: process.env.FRED_API_KEY,
});

Keep API keys on the server. For browser apps, proxy keyed requests through your backend.

Handle errors

Every package exports typed errors for failed requests. Error objects include enough context to debug the upstream call.

import { StatCanApiError } from '@varve/statcan-wds';
 
try {
  await client.getCubeMetadata([99999999]);
} catch (err) {
  if (err instanceof StatCanApiError) {
    console.error(err.status);
    console.error(err.url);
    console.error(err.body);
  }
}

Some packages expose more specific errors for known provider behavior. For example, @varve/statcan-wds separates invalid coordinates, suppressed data, agency internal failures, and malformed responses.

Next steps