@varve/cmhc-api

TypeScript client for CSV exports from CMHC's Housing Market Information Portal (HMIP).

This package follows the same shape as the other Varve agency SDKs: a small isomorphic fetch client, typed request objects, Zod-validated normalized results, and direct access to the raw provider surface when needed.

Install

npm install @varve/cmhc-api zod

Usage

import { CmhcClient } from '@varve/cmhc-api';

const cmhc = new CmhcClient();

const rows = await cmhc.getCmhc({
  survey: 'Rms',
  series: 'Vacancy Rate',
  dimension: 'Bedroom Type',
  breakdown: 'Historical Time Periods',
  region: {
    geographyId: '2410',
    geographyTypeId: '3',
    geoUid: '59933',
  },
  filters: {
    season: 'October',
  },
});

Configuration

const cmhc = new CmhcClient({
  baseUrl: 'https://www03.cmhc-schl.gc.ca/hmip-pimh/en/TableMapChart',
  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. A narrow Node HTTP fallback is used only when native fetch cannot parse CMHC's response transport.

CMHC's export endpoint uses CMHC geography identifiers, not plain Census GeoUIDs. Pass region.geographyId and region.geographyTypeId from your own lookup layer. geoUid is retained on normalized rows when you have it.

For planner-driven NLQ flows that already know the portal table id, call the lower-level export method:

const csv = await cmhc.exportTableCsv({
  tableId: '2.2.1',
  region: { geographyId: '2410', geographyTypeId: '3' },
  filters: { season: 'October' },
});

Discovery

cmhc.listSurveys();
cmhc.listSeries('Rms');
cmhc.listDimensions({ survey: 'Rms', series: 'Vacancy Rate' });
cmhc.listBreakdowns({ survey: 'Rms', series: 'Vacancy Rate', dimension: 'Bedroom Type' });
cmhc.listFilters({
  survey: 'Rms',
  series: 'Vacancy Rate',
  dimension: 'Bedroom Type',
  breakdown: 'Historical Time Periods',
});

The bundled metadata currently covers common NLQ targets for starts, completions, under construction, vacancy, availability, rent, and rental universe tables. Pass tableCode for supported CMHC portal tables that are not yet bundled.

Verification

Current local checks:

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

The initial suite has 6 unit tests covering discovery metadata, export form parameters, CSV parsing, table fetch normalization, filter validation, and HTTP error handling.

Attribution

CMHC data products have attribution requirements. Include the appropriate CMHC source notice when reproducing or adapting CMHC data.