By the geoamcan data team · Reviewed 2026-10-26
Discover identifiers first
Use /v1/canada/geographies to find a named geography and its DGUID. Use /v1/canada/metrics to discover product IDs, characteristic codes, labels and units. A Canadian identifier cannot be substituted into a US GEOID parameter.
Separate population from profile coverage
The population dataset supports published municipal records. The restored census profile currently covers national and provincial geography; it does not provide a municipal profile for every Canadian city. Check dataset coverage before promising a city-level feature.
Preserve source dimensions
Keep product_id, characteristic and period with each observation. Match denominators and universes before calculating rates. Forward sortation areas are three-character postal areas, not precise six-character postal codes.
Start with a verified dataset request
Install the Python requests package in your application environment, then set GEOAMCAN_API_KEY on the server. This bounded example demonstrates retrieval; the sections above describe how to extend the workflow.
import os
import requests
response = requests.get(
'https://api.geoamcan.com/v1/canada/data',
params={'limit': 1, 'dataset': 'ca-population'},
headers={"Authorization": "Bearer " + os.environ["GEOAMCAN_API_KEY"]},
timeout=30,
)
response.raise_for_status()
result = response.json()
print(result)curl --fail --get "https://api.geoamcan.com/v1/canada/data?limit=1&dataset=ca-population" \
-H "Authorization: Bearer $GEOAMCAN_API_KEY"Saved response excerpt
{
"country": "CA",
"dataset": "ca-population",
"records": [
{
"dguid": "2021A000011124",
"geo_type": "national",
"geo_uid": "11124",
"vintage": "2021",
"name": "Canada",
"product_id": "98100002",
"characteristic": "1",
"label": "Population, 2021",
"unit": "count",
"universe": "All persons, 2021 and 2016 censuses – 100% data",
"period": "2021",
"dimensions": {}
}
],
"returned_count": 1,
"complete": false,
"snapshot": {
"ca-population": {
"release_id": 45,
"release": "2021 Census population revision fd5565bab6cf",
"fingerprint": "97771ec7b844424b68937ebaf6d6a8c6"
}
},
"source_attribution": "Statistics Canada, published product and reference period; reproduced under the Statistics Canada Open Licence.",
"coverage_limitations": [
"Census reference vintage is 2021; comparator columns retain their published reference labels."
],
"next_offset": 1
}Captured 2026-10-26. Excerpt omits pagination credentials and may shorten nested records. Download verified source responses.
Production checklist
- Keep the bearer key out of browser code and logs.
- Preserve source, release, period, geographic vintage and units.
- Handle 401, 422, 429 and temporary server failures explicitly; respect Retry-After.
- Validate coverage and empty results before generating conclusions.
- Use documented pagination and checkpoint contracts for larger workloads.