API REFERENCE

From first request
to production.

Authentication, working examples, endpoint parameters and analysis metrics. All generated from the published API contract and registries.

Download OpenAPI ↓Browse datasets ↗

GET STARTED

Make your first calls.

Request access, then send your service token in the Authorization: Bearer header. Keep credentials on your server.

GET /v1/capabilitiesDiscover your credential limits and readiness.
GET /v1/datasetsChoose a source, release and geography.
GET /v1/demographicsRequest the records your application needs.

Use your existing stack.

Call the API from Python, JavaScript, a data pipeline or a server-side AI tool. Follow each endpoint’s pagination and reported credential limits.

In the examples, $GEOAMCAN_API_KEY is your local environment variable for the issued token.

Request API access ↗

All data operations require a service bearer token. /catalog.json is public. Identifiers such as cbp, lodes and tiger select datasets; they are not standalone endpoint paths.

REQUEST → RESPONSE

Working examples.

Copy a request and inspect the corresponding response excerpt. These are verified saved examples, not live queries.

Los Angeles County, California

Read a demographic record.

9,808,667

residents

Select a dataset and county GEOID. Read the estimate and its published margin of error from the response.

ACS 2024 five-year estimate · Table B01001

API IN ACTION

curl "https://api.geoamcan.com/v1/demographics?geo_type=county&geoid=06037&dataset=acs&limit=1" \
  -H "Authorization: Bearer $GEOAMCAN_API_KEY"

200 OK RESPONSE EXCERPT · VERIFIED SNAPSHOT

{
  "dataset": "acs",
  "source": "Census Bureau",
  "period": "2024",
  "geoid": "06037",
  "metrics": {
    "B01001_001": 9808667
  },
  "margins_of_error": {
    "B01001_001": null
  }
}

Cook County, Illinois · Chicago region

Query employment and wages.

$2,015

average weekly wage

Request county employment data with the bls dataset selector. Preserve the published period when joining wage and employment series.

BLS QCEW · 2026 Q1 · All industries & ownerships

API IN ACTION

curl "https://api.geoamcan.com/v1/employment?geo_type=county&geoid=17031&dataset=bls&limit=1" \
  -H "Authorization: Bearer $GEOAMCAN_API_KEY"

200 OK RESPONSE EXCERPT · VERIFIED SNAPSHOT

{
  "dataset": "bls",
  "source": "Bureau of Labor Statistics",
  "period": "2026-Q1",
  "geoid": "17031",
  "metrics": {
    "avg_wkly_wage": 2015,
    "month3_emplvl": 2569918,
    "qtrly_estabs": 139775
  }
}

Miami-Dade County, Florida

Retrieve published hazard indicators.

$824.7M

published expected annual loss

Compare published hazard context with population and housing exposure. This is a county-level source estimate, not a property loss forecast.

FEMA National Risk Index · December 2025 v1.20.0

API IN ACTION

curl "https://api.geoamcan.com/v1/environment?geo_type=county&geoid=12086&dataset=fema&limit=1" \
  -H "Authorization: Bearer $GEOAMCAN_API_KEY"

200 OK RESPONSE EXCERPT · VERIFIED SNAPSHOT

{
  "dataset": "fema",
  "source": "FEMA",
  "release": "December 2025 v1.20.0",
  "geoid": "12086",
  "metrics": {
    "EAL_VALT": 824686737.261532
  }
}

Ontario, Canada

Use the Canadian data routes.

14,223,942

residents

Start with provincial population, then explore Canadian business counts and available census characteristics using dedicated Canadian routes.

Statistics Canada · 2021 Census · Province 35

API IN ACTION

curl "https://api.geoamcan.com/v1/canada/data?dataset=ca-population&geo_type=province&geo_uid=35&limit=1" \
  -H "Authorization: Bearer $GEOAMCAN_API_KEY"

200 OK RESPONSE EXCERPT · VERIFIED SNAPSHOT

{
  "geo_type": "province",
  "geo_uid": "35",
  "name": "Ontario",
  "label": "Population, 2021",
  "period": "2021",
  "value": 14223942
}

Captured October 25, 2026. Download source responses ↗

API operations

Find an endpoint

30 operations. Expand an endpoint for its parameters. Request bodies and complete response schemas are in the OpenAPI contract.

GET/healthHealthBearer token

Private database-backed service health. Excluded from usage and rate limits.

GET/v1/capabilitiesEffective credential policy and retrieval contractBearer token

Effective credential policy and retrieval contract. Request and response formats are defined in the downloadable OpenAPI contract.

GET/v1/datasetsInstalled datasets and verified readinessBearer token

Installed datasets and verified readiness. Request and response formats are defined in the downloadable OpenAPI contract.

GET/v1/geography/lookupLocate native census geographies by coordinatesBearer token

Locate native census geographies by coordinates. Request and response formats are defined in the downloadable OpenAPI contract.

Request parameters
Name	Location	Description
`lat` required	query	number
`lon` required	query	number

GET/v1/geography/placesDiscover published city and Census-designated place identifiersBearer token

Discover published city and Census-designated place identifiers. Request and response formats are defined in the downloadable OpenAPI contract.

Request parameters
Name	Location	Description
`q`	query	See schema
`state`	query	See schema
`vintage`	query	string
`offset`	query	integer
`limit`	query	integer
`cursor`	query	See schema

GET/v1/demographicsPopulation, housing, affordability and demographicsBearer token

Population, housing, affordability and demographics. Request and response formats are defined in the downloadable OpenAPI contract.

Request parameters
Name	Location	Description
`geo_type` required	query	string
`geoid` required	query	string
`offset`	query	integer
`limit`	query	integer
`dataset`	query	See schema
`cursor`	query	See schema
`vintage`	query	See schema
`metrics`	query	See schema

GET/v1/business-densityPublished industry establishments, employment and payrollBearer token

Published industry establishments, employment and payroll. Request and response formats are defined in the downloadable OpenAPI contract.

Request parameters
Name	Location	Description
`geo_type` required	query	string
`geoid` required	query	string
`naics`	query	See schema
`offset`	query	integer
`limit`	query	integer
`dataset`	query	See schema
`cursor`	query	See schema
`vintage`	query	See schema
`metrics`	query	See schema

GET/v1/employmentWorkplace, resident employment, wages and commutingBearer token

Workplace, resident employment, wages and commuting. Request and response formats are defined in the downloadable OpenAPI contract.

Request parameters
Name	Location	Description
`geo_type` required	query	string
`geoid` required	query	string
`naics`	query	See schema
`offset`	query	integer
`limit`	query	integer
`view`	query	string
`flow_direction`	query	string
`dataset`	query	See schema
`cursor`	query	See schema
`vintage`	query	See schema
`metrics`	query	See schema

GET/v1/economyRegional GDP, income and building permitsBearer token

Regional GDP, income and building permits. Request and response formats are defined in the downloadable OpenAPI contract.

Request parameters
Name	Location	Description
`geo_type` required	query	string
`geoid` required	query	string
`offset`	query	integer
`limit`	query	integer
`dataset`	query	See schema
`cursor`	query	See schema
`vintage`	query	See schema
`metrics`	query	See schema

GET/v1/environmentPublished hazard, monitored air-quality and release indicatorsBearer token

Published hazard, monitored air-quality and release indicators. Request and response formats are defined in the downloadable OpenAPI contract.

Request parameters
Name	Location	Description
`geo_type` required	query	string
`geoid` required	query	string
`offset`	query	integer
`limit`	query	integer
`dataset`	query	See schema
`cursor`	query	See schema
`vintage`	query	See schema
`metrics`	query	See schema

POST/v1/market-profileCombine available native-resolution geographic intelligenceBearer token

Combine available native-resolution geographic intelligence. Request and response formats are defined in the downloadable OpenAPI contract.

JSON request body: ProfileInput. Required fields and response schemas are included in the OpenAPI contract.

GET/v1/geography/areasDiscover native townships, metropolitan areas, and other published boundariesBearer token

Discover native townships, metropolitan areas, and other published boundaries. Request and response formats are defined in the downloadable OpenAPI contract.

Request parameters
Name	Location	Description
`geo_type`	query	See schema
`q`	query	See schema
`state`	query	See schema
`vintage`	query	See schema
`dataset`	query	See schema
`limit`	query	integer
`offset`	query	integer
`cursor`	query	See schema

GET/v1/business-locationsPublished business and POI locations, categories, source confidence and attributionBearer token

Published business and POI locations, categories, source confidence and attribution. Request and response formats are defined in the downloadable OpenAPI contract.

Request parameters
Name	Location	Description
`bbox`	query	See schema
`lat`	query	See schema
`lon`	query	See schema
`radius_m`	query	See schema
`geo_type`	query	See schema
`geoid`	query	See schema
`category`	query	See schema
`min_confidence`	query	See schema
`limit`	query	integer
`offset`	query	integer
`cursor`	query	See schema

GET/v1/roadsPublished road segments, connectors and source routing restrictionsBearer token

Published road segments, connectors and source routing restrictions. Request and response formats are defined in the downloadable OpenAPI contract.

Request parameters
Name	Location	Description
`bbox`	query	See schema
`lat`	query	See schema
`lon`	query	See schema
`radius_m`	query	See schema
`geo_type`	query	See schema
`geoid`	query	See schema
`feature_type`	query	See schema
`limit`	query	integer
`offset`	query	integer
`cursor`	query	See schema

GET/v1/spending/groupsDiscover the native published Consumer Expenditure groupsBearer token

Discover the native published Consumer Expenditure groups. Request and response formats are defined in the downloadable OpenAPI contract.

Request parameters
Name	Location	Description
`limit`	query	integer
`offset`	query	integer
`cursor`	query	See schema

POST/v1/geo/analyzeCalculate published or spatially estimated ACS intelligence for an area or overlapping selectionBearer token

Calculate published or spatially estimated ACS intelligence for an area or overlapping selection. Request and response formats are defined in the downloadable OpenAPI contract.

JSON request body: AnalysisInput. Required fields and response schemas are included in the OpenAPI contract.

GET/v1/geo/boundariesSearch boundary names or GEOIDs and discover boundaries intersecting a viewportBearer token

Search boundary names or GEOIDs and discover boundaries intersecting a viewport. Request and response formats are defined in the downloadable OpenAPI contract.

Request parameters
Name	Location	Description
`boundary_type`	query	See schema
`q`	query	See schema
`bbox`	query	See schema
`vintage`	query	See schema
`limit`	query	integer
`cursor`	query	See schema

GET/v1/geo/boundaries/{boundary_type}/{geoid}Retrieve bounded simplified GeoJSON for map renderingBearer token

Retrieve bounded simplified GeoJSON for map rendering. Request and response formats are defined in the downloadable OpenAPI contract.

Request parameters
Name	Location	Description
`boundary_type` required	path	string
`geoid` required	path	string
`zoom`	query	integer
`vintage`	query	See schema

POST/v1/exportComplete resumable nationwide or selected-area NDJSON exportBearer token

Each newline-delimited JSON object is an export event. Save checkpoints only after committing preceding records. Resume with the last committed cursor. A 200 HTTP status does not imply completion: require a complete event; an error event means the stream was interrupted. Heartbeats contain no records.

JSON request body: ExportInput. Required fields and response schemas are included in the OpenAPI contract.

GET/v1/search/metricsDiscover reviewed market metrics and geography compatibilityBearer token

Discover reviewed market metrics and geography compatibility. Request and response formats are defined in the downloadable OpenAPI contract.

POST/v1/search/validateValidate portable manual or model-generated search criteriaBearer token

Validate portable manual or model-generated search criteria. Request and response formats are defined in the downloadable OpenAPI contract.

JSON request body: SearchInput. Required fields and response schemas are included in the OpenAPI contract.

POST/v1/search/areasFind and rank published markets nationwide or in a working regionBearer token

Find and rank published markets nationwide or in a working region. Request and response formats are defined in the downloadable OpenAPI contract.

JSON request body: SearchInput. Required fields and response schemas are included in the OpenAPI contract.

POST/v1/markets/compareCompare up to five published markets with explicit county contextBearer token

Compare up to five published markets with explicit county context. Request and response formats are defined in the downloadable OpenAPI contract.

JSON request body: CompareInput. Required fields and response schemas are included in the OpenAPI contract.

POST/v1/markets/trendsCompare published historical observations without silently mixing vintagesBearer token

Compare published historical observations without silently mixing vintages. Request and response formats are defined in the downloadable OpenAPI contract.

JSON request body: TrendsInput. Required fields and response schemas are included in the OpenAPI contract.

GET/v1/search/business-categoriesDiscover published POI categories and reviewed business-brief mappingsBearer token

Discover published POI categories and reviewed business-brief mappings. Request and response formats are defined in the downloadable OpenAPI contract.

Request parameters
Name	Location	Description
`q`	query	See schema
`limit`	query	integer
`cursor`	query	See schema

POST/v1/search/businessesSearch published business locations with full-result counts and spatial filtersBearer token

Search published business locations with full-result counts and spatial filters. Request and response formats are defined in the downloadable OpenAPI contract.

JSON request body: BusinessInput. Required fields and response schemas are included in the OpenAPI contract.

GET/v1/canada/geographiesDiscover Canadian native census identifiers and namesBearer token

Discover Canadian native census identifiers and names. Request and response formats are defined in the downloadable OpenAPI contract.

Request parameters
Name	Location	Description
`dataset`	query	string
`q`	query	See schema
`geo_type`	query	See schema
`geo_uid`	query	See schema
`dguid`	query	See schema
`limit`	query	integer
`cursor`	query	See schema

GET/v1/canada/metricsDiscover Canadian source characteristics, units and definitionsBearer token

Discover Canadian source characteristics, units and definitions. Request and response formats are defined in the downloadable OpenAPI contract.

Request parameters
Name	Location	Description
`dataset`	query	string
`product_id`	query	See schema
`q`	query	See schema
`limit`	query	integer
`cursor`	query	See schema

GET/v1/canada/dataRetrieve Canadian observations, administrative polygons, POIs and roadsBearer token

Retrieve Canadian observations, administrative polygons, POIs and roads. Request and response formats are defined in the downloadable OpenAPI contract.

Request parameters
Name	Location	Description
`dataset` required	query	string
`dguid`	query	See schema
`geo_type`	query	See schema
`geo_uid`	query	See schema
`product_id`	query	See schema
`characteristic`	query	See schema
`period`	query	See schema
`naics`	query	See schema
`bbox`	query	See schema
`feature_type`	query	See schema
`feature_id`	query	See schema
`q`	query	See schema
`geometry`	query	boolean
`zoom`	query	integer
`limit`	query	integer
`cursor`	query	See schema

GET/catalog.jsonPublic dataset catalog and measured warehouse totalsPublic

Public dataset catalog and measured warehouse totals. Request and response formats are defined in the downloadable OpenAPI contract.

ANALYSIS CAPABILITIES

Work with places,
patterns and periods.

Published data and supported statistical operations, with source coverage and methods kept explicit.

Location intelligence

Resolve coordinates to census geographies; discover places and areas; retrieve official boundary geometry.

geography/lookup geography/places geography/areas geo/boundaries

Area & service-area analysis

Analyze US boundaries, circles, rectangles, polygons and unions with 48 registered ACS metrics. Custom-area estimates report methodology and coverage.

geo/analyze

Market discovery & ranking

Filter US places and counties, combine weighted priorities, validate criteria and rank supported markets with 40 registered metrics.

search/metrics search/validate search/areas

Comparison & historical trends

Compare up to five US markets and examine supported historical series. Source periods and missing observations remain explicit.

markets/compare markets/trends

Population, housing & workforce

Retrieve population, age, income, education, housing costs, tenure, occupation and commuting characteristics at their published resolutions.

demographics employment

Business & economic intelligence

Explore establishments, industry employment, payroll, GDP, personal income and permits. Build a combined market profile.

business-density economy market-profile

Risk & environmental context

Retrieve FEMA hazard indicators and EPA monitoring and toxic release records with their source geography and coverage.

environment

Consumer spending research

Compare published Consumer Expenditure Survey household groups. Spending is source-level context, not an invented neighborhood estimate.

spending/groups

Canadian public data

Discover Canadian geographies and metrics; retrieve census, population, business counts, boundaries, postal areas, roads and POIs through dedicated Canadian routes.

canada/geographies canada/metrics canada/data

Data engineering & exports

Discover capability limits and datasets, then export supported records for your warehouse, BI tools and models.

capabilities datasets export

Metric registry

48 geographic metrics and 40 market discovery metrics. Coverage depends on the source, geography and period.

Find a metric

48 geographic analysis metrics

total_populationTotal populationpeople · acs
male_populationMale populationpeople · acs
female_populationFemale populationpeople · acs
combined_populationCombined male and female populationpeople · acs
total_householdsTotal householdshouseholds · acs
population_densityPopulation per total geographic square milepeople_per_sq_mile · acs
median_ageMedian ageyears · acs-workforce
median_household_incomeMedian household incomeUSD · acs
median_home_valueMedian value of owner-occupied housingUSD · housing
homeownershipOwner-occupied share of occupied housing unitspercent · housing
rental_occupancyRenter-occupied share of occupied housing unitspercent · housing
college_degree_attainmentBachelor's degree or higher among people age 25 and overpercent · acs
unemploymentUnemployed share of civilian labor forcepercent · acs-workforce
labor_force_participationLabor force share of population age 16 and overpercent · acs-workforce
labor_force_populationLabor Force Populationpeople · acs-workforce
civilian_labor_forceCivilian Labor Forcepeople · acs-workforce
employed_populationEmployed Populationpeople · acs-workforce
unemployed_populationUnemployed Populationpeople · acs-workforce
armed_forces_populationArmed Forces Populationpeople · acs-workforce
not_in_labor_force_populationNot In Labor Force Populationpeople · acs-workforce
occupation_management_business_science_artsManagement Business Science Arts occupations, civilian employed age 16 and overpeople · acs-workforce
occupation_serviceService occupations, civilian employed age 16 and overpeople · acs-workforce
occupation_sales_officeSales Office occupations, civilian employed age 16 and overpeople · acs-workforce
occupation_natural_resources_construction_maintenanceNatural Resources Construction Maintenance occupations, civilian employed age 16 and overpeople · acs-workforce
occupation_production_transportation_material_movingProduction Transportation Material Moving occupations, civilian employed age 16 and overpeople · acs-workforce
worker_class_private_for_profitPrivate For Profit, civilian employed age 16 and overpeople · acs-workforce
worker_class_private_nonprofitPrivate Nonprofit, civilian employed age 16 and overpeople · acs-workforce
worker_class_local_governmentLocal Government, civilian employed age 16 and overpeople · acs-workforce
worker_class_state_governmentState Government, civilian employed age 16 and overpeople · acs-workforce
worker_class_federal_governmentFederal Government, civilian employed age 16 and overpeople · acs-workforce
worker_class_self_employed_unincorporatedSelf Employed Unincorporated, civilian employed age 16 and overpeople · acs-workforce
worker_class_unpaid_familyUnpaid Family, civilian employed age 16 and overpeople · acs-workforce
race_white_aloneWhite Alonepeople · acs
race_white_alone_percentWhite Alone share of total populationpercent · acs
race_black_aloneBlack Alonepeople · acs
race_black_alone_percentBlack Alone share of total populationpercent · acs
race_american_indian_alaska_native_aloneAmerican Indian Alaska Native Alonepeople · acs
race_american_indian_alaska_native_alone_percentAmerican Indian Alaska Native Alone share of total populationpercent · acs
race_asian_aloneAsian Alonepeople · acs
race_asian_alone_percentAsian Alone share of total populationpercent · acs
race_native_hawaiian_pacific_islander_aloneNative Hawaiian Pacific Islander Alonepeople · acs
race_native_hawaiian_pacific_islander_alone_percentNative Hawaiian Pacific Islander Alone share of total populationpercent · acs
race_other_race_aloneOther Race Alonepeople · acs
race_other_race_alone_percentOther Race Alone share of total populationpercent · acs
race_two_or_more_racesTwo Or More Racespeople · acs
race_two_or_more_races_percentTwo Or More Races share of total populationpercent · acs
hispanic_originHispanic or Latino, of any racepeople · acs
hispanic_origin_percentHispanic or Latino share of total population, of any racepercent · acs

40 market discovery metrics

total_populationTotal populationpeople · acs, acs-history · place, county
total_householdsTotal householdshouseholds · acs, acs-history · place, county
population_densityPopulation per total geographic square milepeople_per_sq_mile · acs, acs-history · place, county
median_ageMedian ageyears · acs-workforce · place, county
median_household_incomeMedian household incomeUSD · acs, acs-history · place, county
median_home_valueMedian value of owner-occupied housingUSD · housing, housing-history · place, county
homeownershipOwner-occupied share of occupied housing unitspercent · housing, housing-history · place, county
rental_occupancyRenter-occupied share of occupied housing unitspercent · housing, housing-history · place, county
college_degree_attainmentBachelor's degree or higher among people age 25 and overpercent · acs, acs-history · place, county
unemploymentUnemployed share of civilian labor forcepercent · acs-workforce · place, county
labor_force_participationLabor force share of population age 16 and overpercent · acs-workforce · place, county
labor_force_populationLabor Force Populationpeople · acs-workforce · place, county
civilian_labor_forceCivilian Labor Forcepeople · acs-workforce · place, county
employed_populationEmployed Populationpeople · acs-workforce · place, county
unemployed_populationUnemployed Populationpeople · acs-workforce · place, county
armed_forces_populationArmed Forces Populationpeople · acs-workforce · place, county
not_in_labor_force_populationNot In Labor Force Populationpeople · acs-workforce · place, county
occupation_management_business_science_artsManagement Business Science Arts occupations, civilian employed age 16 and overpeople · acs-workforce · place, county
occupation_serviceService occupations, civilian employed age 16 and overpeople · acs-workforce · place, county
occupation_sales_officeSales Office occupations, civilian employed age 16 and overpeople · acs-workforce · place, county
occupation_natural_resources_construction_maintenanceNatural Resources Construction Maintenance occupations, civilian employed age 16 and overpeople · acs-workforce · place, county
occupation_production_transportation_material_movingProduction Transportation Material Moving occupations, civilian employed age 16 and overpeople · acs-workforce · place, county
worker_class_private_for_profitPrivate For Profit, civilian employed age 16 and overpeople · acs-workforce · place, county
worker_class_private_nonprofitPrivate Nonprofit, civilian employed age 16 and overpeople · acs-workforce · place, county
worker_class_local_governmentLocal Government, civilian employed age 16 and overpeople · acs-workforce · place, county
worker_class_state_governmentState Government, civilian employed age 16 and overpeople · acs-workforce · place, county
worker_class_federal_governmentFederal Government, civilian employed age 16 and overpeople · acs-workforce · place, county
worker_class_self_employed_unincorporatedSelf Employed Unincorporated, civilian employed age 16 and overpeople · acs-workforce · place, county
worker_class_unpaid_familyUnpaid Family, civilian employed age 16 and overpeople · acs-workforce · place, county
annual_populationAnnual resident populationpeople · population, population-cities · place, county
population_growthAnnual population growthpercent · population, population-cities · place, county
industry_establishmentsEmployer establishments by industryestablishments · cbp, cbp-history · county
industry_employmentEmployer employment by industryjobs · cbp, cbp-history · county
industry_densityIndustry establishments per 1,000 residentsestablishments_per_1000_residents · cbp, population · county
industry_concentrationEstablishment location quotientratio · cbp · county
average_annual_payAverage annual pay, all ownerships and industriesUSD · bls · county
annual_jobsAnnual average jobs, all ownerships and industriesjobs · bls · county
housing_units_authorizedAnnual housing units authorized, county jurisdictionhousing_units · permits · county
natural_hazard_riskFEMA published natural hazard risk scorescore · fema · county
median_aqiMedian monitored Air Quality IndexAQI · epa · county

Custom-area count estimates use geographic allocation and report their method. Medians have aggregation limits. US market rankings compare published places and counties; they are not revenue forecasts. Canadian coverage uses the dedicated Canadian endpoints.

From first requestto production.

Make your first calls.

Use your existing stack.

Working examples.

Read a demographic record.

Query employment and wages.

Retrieve published hazard indicators.

Use the Canadian data routes.

API operations

Work with places,patterns and periods.

Location intelligence

Area & service-area analysis

Market discovery & ranking

Comparison & historical trends

Population, housing & workforce

Business & economic intelligence

Risk & environmental context

Consumer spending research

Canadian public data

Data engineering & exports

Metric registry

Help us improve the developer experience.

From first request
to production.

Work with places,
patterns and periods.