By the geoamcan data team · Reviewed 2026-10-26
Choose a bounded export
POST /v1/export accepts dataset selectors and supported geographic filters. Use the documented view for observations, flows, geographies or features. Confirm support before including a dataset; Canadian data uses its dedicated retrieval routes.
Process the stream incrementally
Read NDJSON one line at a time. Handle metadata, record, checkpoint, heartbeat, error and complete events explicitly. A closed HTTP stream alone does not prove completion: require a complete event.
Make model inputs reproducible
Keep snapshot and release metadata alongside exported records. Persist checkpoints only after corresponding records are committed. Match training and evaluation periods to avoid information leakage, and request high-volume access for sustained bulk workloads.
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/demographics',
params={'limit': 1, 'dataset': 'population', 'geo_type': 'county', 'geoid': '01001', 'metrics': 'births,deaths,netmig,npopchg,popestimate'},
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/demographics?limit=1&dataset=population&geo_type=county&geoid=01001&metrics=births%2Cdeaths%2Cnetmig%2Cnpopchg%2Cpopestimate" \
-H "Authorization: Bearer $GEOAMCAN_API_KEY"Saved response excerpt
{
"source_attribution": {},
"requested_area": {
"geographic_resolution": "county",
"geoid": "01001"
},
"data": [
{
"dataset": "population",
"source": "Census Bureau",
"release": "Vintage 2025",
"geographic_resolution": "county",
"geoid": "01001",
"geography_vintage": "2025",
"period": "2025",
"naics": "",
"component": "",
"metrics": {
"births": 730,
"deaths": 599,
"netmig": 311,
"npopchg": 444,
"popestimate": 61920
},
"margins_of_error": {},
"flags": {}
}
],
"availability": {
"population": "available"
},
"next_offset": 1,
"returned_count": 1,
"complete": false,
"snapshot": {
"population": {
"release_id": 4,
"release": "Vintage 2025",
"fingerprint": "a5c417070688ce1c6f89436a68a05b23"
}
},
"metric_definitions": {},
"coverage_limitations": {
"population": []
},
"native_area_contexts": {},
"commuting_flows": []
}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.