{"main_topic":"census","sub_topic":"acs","topic":"median_household_income_by_nativity","key":"census/acs/median_household_income_by_nativity","version":"1.0.0","year_min":2020,"year_max":2024,"year_gaps":[],"update_frequency":"annual","detail_levels":["counties","states"],"default_detail":"counties","path_template":"census/median_household_income_by_nativity/year={year}/{detail}.parquet","grain":["year","county_fips","district_code","tract_geoid","citizenship_status"],"title":"Median Household Income by Nativity (ACS)","summary":"What a typical household earns in Georgia and its larger immigrant-receiving counties, by whether the householder is native-born, foreign-born, a naturalized citizen or a noncitizen - American Community Survey 5-year medians.","description":"Median household income by nativity and citizenship status of the householder from the American Community Survey 5-year subject table S0501 (Selected Characteristics of the Native and Foreign-Born Populations - the 'Median Household income (dollars)' row only), for Georgia and the 20 to 24 counties the Census publishes the table for, vintages 2020-2024: the median income of all households and of households whose householder is native, foreign born, a naturalized citizen, or not a U.S. citizen, in each vintage's inflation-adjusted dollars with its 90 percent margin of error.","source":"U.S. Census Bureau, American Community Survey 5-Year Estimates, subject table S0501","source_url":"https://data.census.gov/table/ACSST5Y2024.S0501?g=040XX00US13","endpoint":"/api/v1/census/median_household_income_by_nativity","columns":[{"name":"year","type":"integer","role":"year","nullable":false,"label":"Year","short_description":"","description":"ACS 5-year vintage END year: 2024 covers the pooled 2020-2024 survey period, with dollars inflation-adjusted to 2024. Consecutive vintages overlap.","valid_values":null,"example":2024,"unit":null,"value_min":null,"value_max":null,"null_meaning":null,"key_metric_grain_contributor":false,"metric_component":null},{"name":"county_fips","type":"string","role":"fk_county","nullable":true,"label":"County FIPS","short_description":"","description":"5-digit county FIPS code (state 13 + county). Populated only on county-level rows; NULL on the state row. Only the 20 to 24 counties the Census publishes S0501 for appear in a vintage (a foreign-born population threshold; see limitations).","valid_values":null,"example":"13135","unit":null,"value_min":null,"value_max":null,"null_meaning":null,"key_metric_grain_contributor":false,"metric_component":null},{"name":"district_code","type":"string","role":"fk_district","nullable":true,"label":"District Code","short_description":"","description":"Always NULL: this topic collects state and county geography only (the Census does not publish S0501 for most school districts, so the district level was not collected). Kept for the census domain's standard key shape.","valid_values":null,"example":null,"unit":null,"value_min":null,"value_max":null,"null_meaning":null,"key_metric_grain_contributor":false,"metric_component":null},{"name":"tract_geoid","type":"string","role":"fk_tract","nullable":true,"label":"Tract GEOID","short_description":"","description":"Always NULL: S0501 is NULL at every census tract, so no tract rows are served. Kept for the census domain's standard key shape.","valid_values":null,"example":null,"unit":null,"value_min":null,"value_max":null,"null_meaning":null,"key_metric_grain_contributor":false,"metric_component":null},{"name":"citizenship_status","type":"string","role":"categorical","nullable":false,"label":"Citizenship Status","short_description":"Nativity and citizenship of the HOUSEHOLDER: native vs foreign born, and the foreign born by citizenship; a hierarchy, never summed.","description":"Nativity and citizenship status. Hierarchical, not a partition: all = native + foreign_born, and foreign_born = naturalized + noncitizen, so the five values must never be summed. 'all' is the total row. The ACS asks citizenship, not legal status: noncitizen covers lawful permanent residents, temporary visa holders, and unauthorized migrants alike. In this topic the universe is HOUSEHOLDS, classified by the nativity and citizenship of the householder (S0501 columns C01-C05, row 'Households - Median Household income (dollars)'); every household member's income counts toward the household total regardless of their own nativity.","valid_values":["all","native","foreign_born","naturalized","noncitizen"],"example":"foreign_born","unit":null,"value_min":null,"value_max":null,"null_meaning":null,"key_metric_grain_contributor":true,"metric_component":null},{"name":"median_household_income","type":"integer","role":"metric","nullable":true,"label":"Median Household Income","short_description":"Median income of households whose householder is in the citizenship group, in the vintage's inflation-adjusted dollars.","description":"Median household income in the past 12 months, in whole dollars inflation-adjusted to the vintage end year, for households whose householder is in the citizenship_status group (S0501 row 'Median Household income (dollars)'; ACS 5-year estimate). Medians never sum or average across geographies or citizenship groups, and dollars are not comparable across vintages without a deflator. Published medians are censored at both scale ends and preserved as published (see jam_values): 250001 means $250,000 or more and 2499 means $2,500 or less - neither occurs in 2020-2024 (served range $30,640 to $169,491). A value outside that window is impossible and would be NULLed and recorded as a mask (none in 2020-2024). NULL when the source could not compute a median (see null_meaning).","valid_values":null,"example":77353,"unit":"currency","value_min":null,"value_max":null,"null_meaning":"Median not computable: the Census had too few sampled households in the citizenship group to estimate a median (annotation -666666666, NULLed; the margin is NULL too). One such cell in 2020-2024: Coweta County noncitizen households, vintage 2020. Geographies the Census does not publish this table for are dropped, never served as NULL, and no value is suppressed by the platform.","key_metric_grain_contributor":false,"metric_component":null},{"name":"median_household_income_moe","type":"integer","role":"metric","nullable":true,"label":"Median Household Income Moe","short_description":"","description":"90 percent margin of error for median_household_income, in the same inflation-adjusted whole dollars, as published. County margins on the naturalized and noncitizen groups reach several tens of thousands of dollars (maximum $52,700 in 2020-2024). Never the headline metric.","valid_values":null,"example":null,"unit":"currency","value_min":null,"value_max":null,"null_meaning":"Two distinct cases. Beside a NULL median: the median could not be computed (annotation -222222222) - the one Coweta County 2020 noncitizen cell. Beside a PUBLISHED median: the median is censored at a scale end (2499 / 250001) and the Census publishes no margin for an open-ended interval (annotation -333333333) - this is NOT a controlled estimate; none in 2020-2024. Enforced by the moe_null_when_median_null and moe_null_iff_jam_value checks.","key_metric_grain_contributor":false,"metric_component":null}],"key_metric":"median_household_income","usage":"Star-schema fact table at state and county grain, one row per year x geography x citizenship_status. Join the counties dimension on county_fips (NULL on the state row); district_code and tract_geoid are always NULL. Only the 20 to 24 counties the Census publishes appear. Pin citizenship_status to one value ('all' is the total) and never sum or average medians across rows. Compare within a vintage only - dollars are inflation-adjusted per vintage. Read directly with DuckDB over Parquet.","limitations":"County coverage is PARTIAL: the Census publishes S0501 for only 20 to 24 of Georgia's 159 counties per vintage (22 in 2020, 20 in 2021, 23 in 2022, 24 in 2023, 24 in 2024) - the counties above a FOREIGN-BORN population threshold, not a total-population cut - and the published set shifts by vintage as counties cross it. Unpublished counties are absent from this table (not NULL, not zero, not imputed); the state row is always published; no school-district or tract geography is served at all. Statewide figures are complete; county figures cover metro Atlanta and the larger immigrant-receiving counties only. Medians never sum or average: never combine rows across geographies or across citizenship_status, which is a hierarchy, not a partition (all = native + foreign_born and foreign_born = naturalized + noncitizen households) - the 'all' median lies between the native and foreign-born medians, nothing more. Dollars are inflation-adjusted to each vintage's END year, so values are comparable across geographies and citizenship groups within a vintage but NOT across vintages without a deflator. Universe: households, classified by the HOUSEHOLDER's nativity and citizenship; the ACS asks citizenship, not legal status, so noncitizen covers lawful permanent residents, temporary visa holders, humanitarian migrants, and unauthorized migrants alike. Published medians are censored at both scale ends and preserved as published (250001 = $250,000 or more, 2499 = $2,500 or less; none occurs in 2020-2024). A NULL median means the Census could not compute one from too few sampled households (one cell: Coweta County noncitizen households, 2020) and its margin is NULL too; a NULL margin beside a published median would mark a censored median with no published margin, not a controlled estimate. ACS 5-year period estimates: the year column is the vintage END year and each estimate pools five years of survey responses (2024 = 2020-2024). Consecutive vintages share about 80 percent of their sample, so the series is heavily smoothed - never difference overlapping vintages as if they were annual change. Estimates are survey-based and carry 90 percent margins of error (the *_moe column, in the same dollars); county margins on the naturalized and noncitizen groups reach several tens of thousands of dollars. State and county rows serve vintages 2020-2024 only: the state row has NULL county_fips, county rows carry county_fips, and district_code and tract_geoid are NULL on every row.","null_semantics":{"suppressed_to_null":false,"zero_is_real":true},"available_years":[2020,2021,2022,2023,2024],"schema_hash":"4dccf9564728b0913a93a06945b6390880b9b13107a516d0be48e091a90b7750","tags":["census","u.s. census bureau, american community survey 5-year estimates, subject table s0501","median_household_income_by_nativity"],"granularity_description":"One row per year, county_fips, district_code, tract_geoid, citizenship_status (geography columns are NULL at higher aggregation levels).","example_queries":[{"description":"Latest year (2024), counties detail","query":"SELECT * FROM median_household_income_by_nativity WHERE year = 2024 LIMIT 100"},{"description":"Filter by citizenship_status = foreign_born","query":"SELECT * FROM median_household_income_by_nativity WHERE citizenship_status = 'foreign_born' AND year = 2024 LIMIT 100"}],"foreign_keys":[{"column":"county_fips","target_object":"counties","target_columns":["county_fips"],"attribute_columns_added":["county_name"],"scope":"global"},{"column":"district_code","target_object":"districts","target_columns":["district_code"],"attribute_columns_added":["district_name","district_census_id","district_type"],"scope":"domain"},{"column":"tract_geoid","target_object":"tracts","target_columns":["tract_geoid"],"attribute_columns_added":["tract_name"],"scope":"global"}],"filters":[{"param":"year","kind":"year_exact","type":"integer","multi_value":false,"enum_enforced":false,"values":null},{"param":"year_min","kind":"year_range","type":"integer","multi_value":false,"enum_enforced":false,"values":null},{"param":"year_max","kind":"year_range","type":"integer","multi_value":false,"enum_enforced":false,"values":null},{"param":"detail","kind":"detail","type":"string","multi_value":false,"enum_enforced":true,"values":["counties","states"],"default":"counties"},{"param":"district_code","kind":"foreign_key","column":"district_code","type":"string","multi_value":true,"enum_enforced":false,"values":null},{"param":"county_fips","kind":"foreign_key","column":"county_fips","type":"string","multi_value":true,"enum_enforced":false,"values":null},{"param":"tract_geoid","kind":"foreign_key","column":"tract_geoid","type":"string","multi_value":true,"enum_enforced":false,"values":null},{"param":"citizenship_status","kind":"categorical","column":"citizenship_status","type":"string","multi_value":true,"enum_enforced":true,"values":["all","native","foreign_born","naturalized","noncitizen"],"has_total":true,"total_value":"all","requires_single_value":false,"nullable":false,"null_filter_token":null},{"param":"district_type","kind":"dimension_attribute","dimension":"districts","column":"district_type","type":"string","multi_value":true,"enum_enforced":true,"values":["commission_charter","resa","standard","state_agency","state_charter","state_school","state_special"]}],"filter_hints":[],"values_endpoint":"/api/v1/census/median_household_income_by_nativity/values"}