By the geoamcan data team · Reviewed 2026-10-26
Choose the geographic unit
A county, tract and block group describe different populations. Start with a published geography and keep its GEOID as a string so leading zeroes survive. The five-year ACS is a pooled estimate over five years, not a headcount on one date.
Keep the estimate and its uncertainty
Use the metrics object for estimates and margins_of_error for the corresponding published uncertainty. A missing or suppressed value is not zero. For comparisons, match the ACS release, table universe and geographic vintage.
Join without losing geography
Join your customer records to geography first, then attach demographic attributes. Do not assign a county estimate to a tract and relabel it as tract data. Record the source, period and geography alongside each feature.
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': 'acs', 'geo_type': 'block_group', 'geoid': '010010201001', 'metrics': 'B01001_001,B01001_002,B01001_003,B01001_004,B01001_005,B01001_006'},
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=acs&geo_type=block_group&geoid=010010201001&metrics=B01001_001%2CB01001_002%2CB01001_003%2CB01001_004%2CB01001_005%2CB01001_006" \
-H "Authorization: Bearer $GEOAMCAN_API_KEY"Saved response excerpt
{
"source_attribution": {},
"requested_area": {
"geographic_resolution": "block_group",
"geoid": "010010201001"
},
"data": [
{
"dataset": "acs",
"source": "Census Bureau",
"release": "2024",
"geographic_resolution": "block_group",
"geoid": "010010201001",
"geography_vintage": "2024",
"period": "2024",
"naics": "",
"component": "B01001",
"metrics": {
"B01001_001": 533,
"B01001_002": 307,
"B01001_003": 18,
"B01001_004": 21,
"B01001_005": 25,
"B01001_006": 0
},
"margins_of_error": {
"B01001_001": 164,
"B01001_002": 116,
"B01001_003": 21,
"B01001_004": 25,
"B01001_005": 35,
"B01001_006": 13
},
"flags": {}
}
],
"availability": {
"acs": "available"
},
"next_offset": 1,
"returned_count": 1,
"complete": false,
"snapshot": {
"acs": {
"release_id": 2,
"release": "2024",
"fingerprint": "4e0530dd28d83c72004143ce661b560b"
},
"tiger": {
"release_id": 1,
"release": "2026 + native 2024/2020",
"fingerprint": "691a2a52904e5004411aae3fa3f499eb"
}
},
"metric_definitions": {
"acs": {
"B01001_001": {
"label": "Total:",
"unit": "count; see source universe",
"universe": "Total population",
"source_definition": {
"Line": "1.0",
"Type": "int",
"Label": "Total:",
"Title": "Sex by Age",
"Indent": "0",
"Table ID": "B01001",
"Universe": "Total population",
"Unique ID": "B01001_001"
}
},
"B01001_002": {
"label": "Male:",
"unit": "count; see source universe",
"universe": "Total population",
"source_definition": {
"Line": "2.0",
"Type": "int",
"Label": "Male:",
"Title": "Sex by Age",
"Indent": "1",
"Table ID": "B01001",
"Universe": "Total population",
"Unique ID": "B01001_002"
}
},
"B01001_003": {
"label": "Under 5 years",
"unit": "count; see source universe",
"universe": "Total population",
"source_definition": {
"Line": "3.0",
"Type": "int",
"Label": "Under 5 years",
"Title": "Sex by Age",
"Indent": "2",
"Table ID": "B01001",
"Universe": "Total population",
"Unique ID": "B01001_003"
}
},
"B01001_004": {
"label": "5 to 9 years",
"unit": "count; see source universe",
"universe": "Total population",
"source_definition": {
"Line": "4.0",
"Type": "int",
"Label": "5 to 9 years",
"Title": "Sex by Age",
"Indent": "2",
"Table ID": "B01001",
"Universe": "Total population",
"Unique ID": "B01001_004"
}
},
"B01001_005": {
"label": "10 to 14 years",
"unit": "count; see source universe",
"universe": "Total population",
"source_definition": {
"Line": "5.0",
"Type": "int",
"Label": "10 to 14 years",
"Title": "Sex by Age",
"Indent": "2",
"Table ID": "B01001",
"Universe": "Total population",
"Unique ID": "B01001_005"
}
},
"B01001_006": {
"label": "15 to 17 years",
"unit": "count; see source universe",
"universe": "Total population",
"source_definition": {
"Line": "6.0",
"Type": "int",
"Label": "15 to 17 years",
"Title": "Sex by Age",
"Indent": "2",
"Table ID": "B01001",
"Universe": "Total population",
"Unique ID": "B01001_006"
}
}
}
},
"coverage_limitations": {
"acs": [],
"tiger": []
},
"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.