@varve/worldbank-api

The World Bank Indicators API publishes country-level development indicators across population, poverty, health, education, climate, economy, and public finance. @varve/worldbank-api wraps the API in an isomorphic, Zod-validated TypeScript client.

npm install @varve/worldbank-api zod

import { WorldBankClient, WorldBankApiError } from '@varve/worldbank-api';
 
const client = new WorldBankClient();

When to use this package

Use @varve/worldbank-api when your data model is naturally country, indicator, and year.

It is a good fit for:

• country-level macro and development dashboards
• indicator lookup and metadata search
• source and topic browsing
• year range pulls for one or more countries
• graph metadata for indicator-country-period observations

Data model

Indicator is the measured concept, such as total population (SP.POP.TOTL).

Country is the reporting economy or region, such as USA, CAN, or WLD.

Observation is an indicator value for a country and period.

World Bank endpoints are paginated. Methods return both pagination and items unless they fetch a single object or a helper aggregates pages.

Quick start

const population = await client.getIndicatorData('USA', 'SP.POP.TOTL', {
  date: '2020:2024',
});
 
console.log(population.items);

Common workflows

Configuration

const client = new WorldBankClient({
  baseUrl: 'https://api.worldbank.org/v2',
  maxRetries: 2,
  timeoutMs: 30_000,
});

The client retries 429 and 5xx responses.

Error handling

World Bank can return JSON error payloads even when the transport shape is valid. The package separates HTTP failures from provider response errors.

import { WorldBankApiError, WorldBankResponseError } from '@varve/worldbank-api';
 
try {
  await client.getIndicator('missing');
} catch (err) {
  if (err instanceof WorldBankApiError || err instanceof WorldBankResponseError) {
    console.error(err.status);
    console.error(err.url);
    console.error(err.body);
  }
}

Official references

• Indicators API documentation
• Indicator API queries
• API basic call structures