@varve/worldbank-api

An isomorphic, Zod-validated TypeScript client for the World Bank Indicators API.

Works in Node.js 18+ and modern browsers. The client exposes countries, indicators, sources, topics, indicator observations, and graph-friendly metadata for natural-language query systems.

Installation

npm install @varve/worldbank-api zod

zod is a required peer dependency.

Quick start

import { WorldBankClient } from '@varve/worldbank-api';

const client = new WorldBankClient();

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

const graph = await client.getIndicatorGraphMetadata('SP.POP.TOTL', ['USA', 'CAN'], {
  date: '2020:2024',
});

console.log(population.items);
console.log(graph.indicator);
console.log(graph.countries);
console.log(graph.observations);

Configuration

const client = new WorldBankClient({
  baseUrl: 'https://api.worldbank.org/v2',
  maxRetries: 2, // accepted for compatibility; retries are handled by callers
  timeoutMs: 30_000,
});

The client performs one timeout-bound HTTP request per method call. Non-2xx responses expose status, and Retry-After is parsed as retryAfterMs when present.

API reference

Countries

const countries = await client.getCountries({ perPage: 100, page: 1 });
const usa = await client.getCountry('USA');
const allCountries = await client.getAllCountries();

Indicators

const indicators = await client.getIndicators({ perPage: 100, page: 1 });
const population = await client.getIndicator('SP.POP.TOTL');

// Filter indicator catalogue by source or topic
const wdiIndicators = await client.getIndicators({ source: 2, perPage: 100 });
const povertyIndicators = await client.getIndicators({ topic: 11, perPage: 100 });

Sources and topics

const sources = await client.getSources();
const topics = await client.getTopics();

Observations

const data = await client.getIndicatorData(['USA', 'CAN'], 'SP.POP.TOTL', {
  date: '2020:2024',
  perPage: 100,
});

Graph metadata

World Bank data naturally maps to an indicator -> country -> period graph.

const graph = await client.getIndicatorGraphMetadata('SP.POP.TOTL', ['USA', 'CAN'], {
  date: '2020:2024',
});

// Indicator node
graph.indicator;

// Country nodes
graph.countries;

// Observation edges/facts
graph.observations;

Example graph shape:

(:Indicator {id})-[:OBSERVED_IN]->(:Country {id})
(:Observation {period, value})-[:FOR_INDICATOR]->(:Indicator {id})
(:Observation {period, value})-[:FOR_COUNTRY]->(:Country {id})

Official docs

• Indicators API documentation: https://datahelpdesk.worldbank.org/knowledgebase/articles/889392
• Indicator API queries: https://datahelpdesk.worldbank.org/knowledgebase/articles/898599-indicator-api-queries
• API basic call structures: https://datahelpdesk.worldbank.org/knowledgebase/articles/898581-api-basic-call-structures

Error handling

All non-2xx responses throw a WorldBankApiError. World Bank JSON error payloads throw WorldBankResponseError.

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.retryAfterMs);
    console.error(err.url);
    console.error(err.body);
  }
}