🇨🇦 API Canada / Québec

💡 Déploiement automatique actif : cette documentation est mise à jour à chaque git push.

API géographique du Canada avec couverture complète du Québec. Structure hiérarchique miroir de l'administration territoriale :

texte

Canada (pays)
└── Province / Territoire (/ca/provinces/:code)   ← 13 entrées
    └── Région administrative (17 pour le Québec)
        └── MRC ou territoire équivalent (90)
            └── Municipalité (1 281 au Québec)
                └── Arrondissement (41, dont 19 à Montréal)

Sources officielles : Répertoire des municipalités (MAMH), licence CC-BY 4.0 — donneesquebec.ca

Niveau pays : Provinces

`GET /ca/provinces`

Liste des 10 provinces + 3 territoires canadiens.

Paramètre	Type	Description
`supportee`	bool	`true` = provinces avec données complètes
`type`	string	`Province` ou `Territoire`

bash

curl "http://localhost:3001/ca/provinces?supportee=true"

`GET /ca/provinces/:code`

Fiche d'une province (QC, ON, BC...).

bash

curl "http://localhost:3001/ca/provinces/qc"
# → { code: "QC", nom: "Québec", regionsCount: 17, municipalitesCount: 1281, ... }

⚠️ v1 : seule la province QC expose les sous-ressources. Les autres renvoient un 501.

Régions administratives (Québec)

`GET /ca/provinces/qc/regions`

Les 17 régions administratives, codes officiels 01→17.

Paramètre	Type	Description
`nom`	string	Filtre par nom (insensible à la casse)
`limit`	int	Limite de résultats

bash

curl "http://localhost:3001/ca/provinces/qc/regions"

Régions principales :

Code	Nom	Population
`06`	Montréal	2 170 228
`16`	Montérégie	1 524 072
`13`	Laval	459 650
`03`	Capitale-Nationale	816 887
`15`	Laurentides	679 637

`GET /ca/provinces/qc/regions/:code`

Fiche d'une région.

bash

curl "http://localhost:3001/ca/provinces/qc/regions/06"

`GET /ca/provinces/qc/regions/:code/mrcs`

MRC et territoires équivalents d'une région.

bash

curl "http://localhost:3001/ca/provinces/qc/regions/06/municipalites"

`GET /ca/provinces/qc/regions/:code/municipalites`

Municipalités d'une région (paginé).

Paramètre	Type	Défaut
`limit`	int	100 (max 1300)
`page`	int	1

bash

curl "http://localhost:3001/ca/provinces/qc/regions/06/municipalites?limit=5"
# → { total: 16, page: 1, results: [...] }

MRC

`GET /ca/provinces/qc/mrcs`

Paramètre	Type	Description
`nom`	string	Filtre par nom
`region`	string	Code région (ex: `06`)
`type`	string	Ex: `MRC`, `Agglomération`

bash

curl "http://localhost:3001/ca/provinces/qc/mrcs?region=16"

`GET /ca/provinces/qc/mrcs/:code`

Fiche MRC (codes officiels ARxxx).

`GET /ca/provinces/qc/mrcs/:code/municipalites`

Municipalités de la MRC.

bash

curl "http://localhost:3001/ca/provinces/qc/mrcs/AR020/municipalites"

ℹ️ Les 131 municipalités d'agglomération (Montréal, Laval, Québec...) n'appartiennent pas à une MRC : leur champ mrcCode est null. Utiliser la région administrative dans ce cas.

Municipalités

`GET /ca/provinces/qc/municipalites`

Paramètre	Type	Description
`nom`	string	Recherche partielle insensible à la casse
`region`	string	Code région administrative
`mrc`	string	Code MRC
`populationMin`	int	Population minimum
`limit` / `page`	int	Pagination

bash

curl "http://localhost:3001/ca/provinces/qc/municipalites?nom=montr&limit=10"

`GET /ca/provinces/qc/municipalites/:code`

Fiche complète par code géographique officiel (5 chiffres).

bash

curl "http://localhost:3001/ca/provinces/qc/municipalites/66023"
# → Montréal : population 1 913 561, CP H2Y1C6, région 06, 19 arrondissements

Codes utiles :

Code	Municipalité
`66023`	Montréal
`65005`	Laval
`25042`	Québec
`43027`	Sherbrooke
`25213`	Lévis

`GET /ca/provinces/qc/municipalites/:code/arrondissements`

Arrondissements de la ville (si elle en a).

bash

curl "http://localhost:3001/ca/provinces/qc/municipalites/66023/arrondissements"
# → les 19 arrondissements de Montréal

Arrondissements

`GET /ca/provinces/qc/arrondissements`

Paramètre	Type	Description
`ville`	string	Code municipalité (ex: `66023`)
`region`	string	Code région
`nom`	string	Filtre par nom
`limit`	int	Défaut 200

bash

curl "http://localhost:3001/ca/provinces/qc/arrondissements?ville=66023"

`GET /ca/provinces/qc/arrondissements/:code`

Fiche d'un arrondissement par code (REM19, REM23, etc.).

bash

curl "http://localhost:3001/ca/provinces/qc/arrondissements/REM19"

Utilitaires ⭐

`GET /ca/search?q=`

Recherche globale sur tous les niveaux (régions + MRC + municipalités + arrondissements). Minimum 2 caractères.

bash

curl "http://localhost:3001/ca/search?q=laval"
# → { query: "laval", total: 5, regions: [...], mrcs: [...], municipalites: [...], ... }

`GET /ca/postal/:cp`

Résolution code postal → municipalité / région.

Formats acceptés : H2Y1C6, h2y1c6, H2Y 1C6 (normalisation automatique).

Stratégie v1 :

Correspondance exacte sur les codes postaux officiels des hôtels de ville
Sinon, correspondance par préfixe FSA (les 3 premiers caractères, ex: H2Y)

bash

curl "http://localhost:3001/ca/postal/H2Y1C6"
# → { type: "municipalité", results: [{ nom: "Montréal", regionCode: "06", ... }] }

⚠️ Limite connue : la source officielle ne fournit qu'un seul code postal par municipalité (celui de l'hôtel de ville). Pour un mapping complet des ~800 000 codes postaux, intégrer ultérieurement « CP Territoires » (ISQ).

Codes de retour

Code	Signification
`200`	Succès
`400`	Paramètre invalide (ex: format CP incorrect)
`404`	Ressource non trouvée
`501`	Province non supportée en v1 (hors QC)

Maintenance

Ré-importer les données à jour :

bash

npm run import:canada:all          # tout le Canada/Québec
npm run import:canada:provinces    # provinces seules
npm run import:quebec:regions      # régions seules
npm run import:quebec:mrcs         # MRC seules
npm run import:quebec:municipalites # municipalités seules
npm run import:quebec:arrondissements # arrondissements seuls

Les CSV sources sont dans data/quebec/ (téléchargeables depuis données ouvertes Québec).