# canada-api

> Cross platform API to fetch data from canada.ca

Latest version **5.1.7** (published 2026-05-29) · MIT license · 0 weekly downloads

## Install

```sh
npm install canada-api
pnpm add canada-api
yarn add canada-api
bun add canada-api
```

## Health

**Score 55/100 (C)** — status: active.

Positive: esm support; no vulnerabilities; high maintenance score.

Warnings: low downloads; no types.

## Facts

| | |
|---|---|
| Version | 5.1.7 |
| Published | 2026-05-29 |
| First published | 2022-04-26 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Node | >=18 |
| Dependencies | 0 |
| Unpacked size | 22.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 2 |
| Author | National Defence |
| Maintainers | bsoicher |
| Keywords | canada, api, fetch |

## Links

- npm: https://www.npmjs.com/package/canada-api
- Repository: https://github.com/dnd-mdn/canada-api
- Homepage: https://github.com/dnd-mdn/canada-api#readme
- Issues: https://github.com/dnd-mdn/canada-api/issues
- npm.io page: https://npm.io/package/canada-api

## Alternatives

- [launchdarkly-js-client-sdk](https://npm.io/package/launchdarkly-js-client-sdk.md) — 2.5M weekly downloads
- [@elastic/elasticsearch](https://npm.io/package/@elastic/elasticsearch.md) — 2.1M weekly downloads
- [@c8y/client](https://npm.io/package/@c8y/client.md) — 15.3K weekly downloads
- [@signaldb/maverickjs](https://npm.io/package/@signaldb/maverickjs.md) — 1.7K weekly downloads
- [@bbc/http-transport-cache](https://npm.io/package/@bbc/http-transport-cache.md) — 1.2K weekly downloads

## Recent versions

- 5.1.7 (latest) — 2026-05-29
- 5.1.6 — 2026-05-29
- 5.1.5 — 2026-05-06
- 5.1.4 — 2026-04-28
- 5.1.3 — 2026-04-21
- 5.1.2 — 2026-04-20
- 5.1.1 — 2026-04-20
- 5.1.0 — 2026-04-16
- 5.0.1 — 2026-04-15
- 5.0.0 — 2026-03-18
- 4.0.5 — 2026-02-25
- 4.0.4 — 2026-02-25
- 4.0.3 — 2026-02-25
- 4.0.2 — 2025-09-25
- 4.0.1 — 2025-08-05
- … 20 more at https://npm.io/package/canada-api/versions

## README

([Français](#canada-api-1))

# canada-api

[![NPM Version](https://img.shields.io/npm/v/canada-api?branch=main)](https://www.npmjs.com/package/canada-api) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/dnd-mdn/canada-api/blob/main/LICENSE.md)

Cross platform API for fetching public data from [canada.ca](https://www.canada.ca).

## Browser

```html
<script src="https://cdn.jsdelivr.net/npm/canada-api@5.1.7"></script>
```

## Node 18+

### Install

```shell
npm install canada-api
```

### Usage

```js
import ca from 'canada-api'
```

## Testing

```shell
npm test
```

Tests use the built-in Node.js test runner (`node:test`) and require Node 18 or later.

## API

### `ca.normalize(url)`

- `url` {string|URL} - Full URL or relative path (e.g. `'/en/page'` or `'https://www.canada.ca/en/page'`)
- Returns: {URL} Normalized URL object with cleaned pathname

Validates and normalizes a canada.ca URL. Strips the `/content/canadasite` prefix, file extensions, and trailing slashes.

Throws {TypeError} if `url` is not a string or URL object.
Throws {Error} if the URL is not on canada.ca or the path does not start with `/en/` or `/fr/`.

### `ca.children(url)`

- `url` {string|URL} - Absolute or relative URL
- Returns: {Promise} Fulfills with a response whose `data` is an array of sitemap entries

Fetches and parses the sitemap for the given page, returning its child pages. Entries without a `<loc>` element are skipped.

```json
{
  "data": [
    {
      "path": "/en/department-national-defence/maple-leaf",
      "lastmod": "2022-09-20T00:00:00.000Z"
    }
  ],
  "status": 200,
  "statusText": "OK",
  "headers": {
    "content-type": "text/xml"
  }
}
```

### `ca.content(url)`

- `url` {string|URL} - Absolute or relative URL
- Returns: {Promise} Fulfills with a response whose `data` is the raw HTML string, or parsed JSON for DAM asset URLs

Retrieves the HTML content of the page. DAM asset URLs under `/content/dam/` are passed through without forcing a `.html` suffix.

```json
{
  "data": "<!DOCTYPE html>...",
  "status": 200,
  "statusText": "OK",
  "headers": {
    "content-type": "text/html"
  }
}
```

### `ca.meta(url)`

- `url` {string|URL} - Absolute or relative URL
- Returns: {Promise} Fulfills with a response whose `data` is a formatted metadata object, or parsed JSON for DAM asset URLs

Fetches JCR metadata for the given page. For DAM asset URLs under `/content/dam/`, the asset JSON response is returned. The following transformations are applied to page metadata:

- String `"true"` / `"false"` values are converted to booleans
- `@TypeHint` properties are removed
- Empty arrays are removed
- Date strings are converted to ISO 8601
- Keys are sorted alphabetically
- A normalized `peer` field is added when `gcAltLanguagePeer` is present

```json
{
  "data": {
    "cq:lastModified": "2022-10-25T19:16:28.000Z",
    "fluidWidth": false,
    "peer": "/fr/ministere-defense-nationale/feuille-erable"
  },
  "status": 200,
  "statusText": "OK",
  "headers": {
    "content-type": "application/json"
  }
}
```

### `ca.request`

- `url` {string|URL} - Absolute or relative URL
- `options` {RequestInit} - Optional fetch options
- Returns: {Promise} Fulfills with a response object

Raw HTTP client with `https://www.canada.ca` as the base URL. Use this for any requests not covered by the methods above. No URL transformation is applied. Response bodies with a `application/json` content type are automatically parsed.

```js
const response = await ca.request('/en/department-national-defence.html');
```

All methods return the same response shape:

```json
{
  "data": "...",
  "status": 200,
  "statusText": "OK",
  "headers": {
    "content-type": "text/html"
  }
}
```

---

# canada-api

[![NPM Version](https://img.shields.io/npm/v/canada-api?branch=main)](https://www.npmjs.com/package/canada-api) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/dnd-mdn/canada-api/blob/main/LICENSE.md)

API multiplateforme pour récupérer des données publiques de [canada.ca](https://www.canada.ca).

## Navigateur

```html
<script src="https://cdn.jsdelivr.net/npm/canada-api@5.1.7"></script>
```

## Node 18+

### Installation

```shell
npm install canada-api
```

### Utilisation

```js
import ca from 'canada-api'
```

## API

### `ca.normalize(url)`

- `url` {string|URL} - URL complète ou chemin relatif (p. ex. `'/fr/page'` ou `'https://www.canada.ca/fr/page'`)
- Retourne: {URL} Objet URL normalisé avec un chemin nettoyé

Valide et normalise une URL de canada.ca. Supprime le préfixe `/content/canadasite`, les extensions de fichier et les barres obliques finales.

Lève {TypeError} si `url` n'est pas une chaîne ou un objet URL.
Lève {Error} si l'URL n'est pas sur canada.ca ou si le chemin ne commence pas par `/en/` ou `/fr/`.

### `ca.children(url)`

- `url` {string|URL} - URL absolue ou relative
- Retourne: {Promise} Résout avec une réponse dont `data` est un tableau d'entrées du plan de site

Récupère et analyse le plan de site de la page donnée, retournant ses pages enfants. Les entrées sans élément `<loc>` sont ignorées.

```json
{
  "data": [
    {
      "path": "/fr/ministere-defense-nationale/feuille-erable",
      "lastmod": "2022-09-20T00:00:00.000Z"
    }
  ],
  "status": 200,
  "statusText": "OK",
  "headers": {
    "content-type": "text/xml"
  }
}
```

### `ca.content(url)`

- `url` {string|URL} - URL absolue ou relative
- Retourne: {Promise} Résout avec une réponse dont `data` est la chaîne HTML brute, ou le JSON analysé pour les URL d'actifs DAM

Récupère le contenu HTML de la page. Les URL d'actifs DAM sous `/content/dam/` sont transmises sans forcer le suffixe `.html`.

```json
{
  "data": "<!DOCTYPE html>...",
  "status": 200,
  "statusText": "OK",
  "headers": {
    "content-type": "text/html"
  }
}
```

### `ca.meta(url)`

- `url` {string|URL} - URL absolue ou relative
- Retourne: {Promise} Résout avec une réponse dont `data` est un objet de métadonnées formaté, ou le JSON analysé pour les URL d'actifs DAM

Récupère les métadonnées JCR de la page donnée. Pour les URL d'actifs DAM sous `/content/dam/`, la réponse JSON de l'actif est retournée. Les transformations suivantes sont appliquées aux métadonnées de page :

- Les valeurs `"true"` / `"false"` sont converties en booléens
- Les propriétés `@TypeHint` sont supprimées
- Les tableaux vides sont supprimés
- Les chaînes de date sont converties en ISO 8601
- Les clés sont triées alphabétiquement
- Un champ `peer` normalisé est ajouté lorsque `gcAltLanguagePeer` est présent

```json
{
  "data": {
    "cq:lastModified": "2022-10-25T19:16:28.000Z",
    "fluidWidth": false,
    "peer": "/en/department-national-defence/maple-leaf"
  },
  "status": 200,
  "statusText": "OK",
  "headers": {
    "content-type": "application/json"
  }
}
```

### `ca.request`

- `url` {string|URL} - URL absolue ou relative
- `options` {RequestInit} - Options fetch optionnelles
- Retourne: {Promise} Résout avec un objet réponse

Client HTTP brut avec `https://www.canada.ca` comme URL de base. Utilisez-le pour toute requête non couverte par les méthodes ci-dessus. Aucune transformation d'URL n'est appliquée. Les corps de réponse avec un type de contenu `application/json` sont automatiquement analysés.

```js
const response = await ca.request('/fr/ministere-defense-nationale.html');
```

Toutes les méthodes retournent la même structure de réponse :

```json
{
  "data": "...",
  "status": 200,
  "statusText": "OK",
  "headers": {
    "content-type": "text/html"
  }
}
```

---
_Source: https://npm.io/package/canada-api · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._