API Reference

This page documents the public API for ACS.jl.

Main Data Retrieval Functions

These are the primary functions for retrieving ACS data:

ACS.get_acs — Function
get_acs(;
    variables::Vector{String},
    geography::String,
    year::Int = 2022,
    survey::String = "acs5",
    state::Union{String,Nothing} = nothing,
    county::Union{String,Nothing} = nothing,
    output_type::Type{T} = DataFrame
) where T

Main interface to fetch data from the American Community Survey.

Arguments

  • variables: Vector of Census variable codes (must end with 'E' for estimates)
  • geography: Geographic level ("state", "county", "tract", "block group")
  • year: Survey year (default: 2023)
  • survey: Survey type ("acs1", "acs3", or "acs5", default: "acs5")
  • state: Optional state postal code or FIPS code
  • county: Optional county FIPS code (requires state)
  • output_type: Type of output (DataFrame, StructArray, Vector{NamedTuple}, or NamedTuple{Vector})

Returns

Data in the requested format

Example

# Get total population for all states using 5-year estimates as a DataFrame
df = get_acs(
    variables = ["B01003_001E"],
    geography = "state",
    survey = "acs5"
)

# Get as a StructArray
sa = get_acs(
    variables = ["B01003_001E"],
    geography = "state",
    survey = "acs5",
    output_type = StructArray
)
source
ACS.get_acs1 — Function
get_acs1(;
    variables::Vector{String},
    geography::String,
    year::Int = 2022,
    state::Union{String,Nothing} = nothing,
    county::Union{String,Nothing} = nothing,
    output_type::Type{T} = DataFrame
) where T

Fetch estimates from American Community Survey 1-year estimates. Only available for geographies with populations of 65,000 and greater.

Arguments

  • variables: Vector of Census variable codes (must end with 'E' for estimates)
  • geography: Geographic level ("state", "county", "tract", "block group")
  • year: Survey year (default: 2023)
  • state: Optional state postal code or FIPS code
  • county: Optional county FIPS code (requires state)
  • output_type: Type of output (DataFrame, StructArray, Vector{NamedTuple}, or NamedTuple{Vector})

Returns

Data in the requested format

Example

# Get total population for all states as a DataFrame
df = get_acs1(
    variables = ["B01003_001E"],
    geography = "state"
)

# Get as a StructArray
sa = get_acs1(
    variables = ["B01003_001E"],
    geography = "state",
    output_type = StructArray
)
source
ACS.get_acs3 — Function
get_acs3(;
    variables::Vector{String},
    geography::String,
    year::Int = 2013,
    state::Union{String,Nothing} = nothing,
    county::Union{String,Nothing} = nothing,
    output_type::Type{T} = DataFrame
) where T

Fetch estimates from American Community Survey 3-year estimates. Only available from 2007-2013 for geographies with populations of 20,000 and greater.

Arguments

  • variables: Vector of Census variable codes (must end with 'E' for estimates)
  • geography: Geographic level ("state", "county", "tract", "block group")
  • year: Survey year (2007-2013)
  • state: Optional state postal code or FIPS code
  • county: Optional county FIPS code (requires state)
  • output_type: Type of output (DataFrame, StructArray, Vector{NamedTuple}, or NamedTuple{Vector})

Returns

Data in the requested format

Example

# Get total population for all states in 2013 as a DataFrame
df = get_acs3(
    variables = ["B01003_001E"],
    geography = "state",
    year = 2013
)

# Get as a Vector{NamedTuple}
nts = get_acs3(
    variables = ["B01003_001E"],
    geography = "state",
    year = 2013,
    output_type = Vector{NamedTuple}
)
source
ACS.get_acs5 — Function
get_acs5(;
    variables::Vector{String},
    geography::String,
    year::Int = 2022,
    state::Union{String,Nothing} = nothing,
    county::Union{String,Nothing} = nothing,
    output_type::Symbol = :dataframe
)

Fetch estimates from American Community Survey 5-year estimates.

Arguments

  • variables: Vector of Census variable codes (must end with 'E' for estimates)
  • geography: Geographic level ("state", "county", "tract", "block group")
  • year: Survey year (default: 2022)
  • state: Optional state postal code or FIPS code
  • county: Optional county FIPS code (requires state)
  • output_type: Symbol indicating output type (:dataframe, :structarray, :namedtuples, or :columnar)

Returns

Data in the requested format

Example

# Get total population for all states as a DataFrame
df = get_acs5(
    variables = ["B01003_001E"],
    geography = "state"
)

# Get as a StructArray
sa = get_acs5(
    variables = ["B01003_001E"],
    geography = "state",
    output_type = :structarray
)
source

Margin of Error Functions

Functions specifically for retrieving margin of error data:

ACS.get_acs_moe — Function
get_acs_moe(;
    variables::Vector{String},
    geography::String,
    year::Int = 2022,
    survey::String = "acs5",
    state::Union{String,Nothing} = nothing,
    county::Union{String,Nothing} = nothing
) -> DataFrame

Main interface to fetch margin of error data from the American Community Survey.

Arguments

  • variables: Vector of Census variable codes (must end with 'M' for MOE)
  • geography: Geographic level ("state", "county", "tract", "block group")
  • year: Survey year (default: 2022)
  • survey: Survey type ("acs1", "acs3", or "acs5", default: "acs5")
  • state: Optional state postal code or FIPS code
  • county: Optional county FIPS code (requires state)

Returns

DataFrame with requested Census MOE data

Example

# Get MOE for total population for all states using 5-year estimates
df = get_acs_moe(
    variables = ["B01003_001M"],
    geography = "state",
    survey = "acs5"
)
source
ACS.get_acs_moe1 — Function
get_acs_moe1(;
    variables::Vector{String},
    geography::String,
    year::Int = 2023,
    state::Union{String,Nothing} = nothing,
    county::Union{String,Nothing} = nothing
) -> DataFrame

Fetch margin of error values from American Community Survey 1-year estimates. Only available for geographies with populations of 65,000 and greater.

Arguments

  • variables: Vector of Census variable codes (must end with 'M' for MOE)
  • geography: Geographic level ("state", "county", "tract", "block group")
  • year: Survey year (default: 2023)
  • state: Optional state postal code or FIPS code
  • county: Optional county FIPS code (requires state)

Returns

DataFrame with requested Census MOE data

Example

# Get MOE for total population for all states
df = get_acs_moe1(
    variables = ["B01003_001M"],
    geography = "state"
)
source
ACS.get_acs_moe3 — Function
get_acs_moe3(;
    variables::Vector{String},
    geography::String,
    year::Int = 2013,
    state::Union{String,Nothing} = nothing,
    county::Union{String,Nothing} = nothing
) -> DataFrame

Fetch margin of error values from American Community Survey 3-year estimates. Only available from 2007-2013 for geographies with populations of 20,000 and greater.

Arguments

  • variables: Vector of Census variable codes (must end with 'M' for MOE)
  • geography: Geographic level ("state", "county", "tract", "block group")
  • year: Survey year (2007-2013)
  • state: Optional state postal code or FIPS code
  • county: Optional county FIPS code (requires state)

Returns

DataFrame with requested Census MOE data

Example

# Get MOE for total population for all states in 2013
df = get_acs_moe3(
    variables = ["B01003_001M"],
    geography = "state",
    year = 2013
)
source
ACS.get_acs_moe5 — Function
get_acs_moe5(;
    variables::Vector{String},
    geography::String,
    year::Int = 2023,
    state::Union{String,Nothing} = nothing,
    county::Union{String,Nothing} = nothing
) -> DataFrame

Fetch margin of error values from American Community Survey 5-year estimates.

Arguments

  • variables: Vector of Census variable codes (must end with 'M' for MOE)
  • geography: Geographic level ("state", "county", "tract", "block group")
  • year: Survey year (default: 2023)
  • state: Optional state postal code or FIPS code
  • county: Optional county FIPS code (requires state)

Returns

DataFrame with requested Census MOE data

Example

# Get MOE for total population for all states
df = get_acs_moe5(
    variables = ["B01003_001M"],
    geography = "state"
)
source

Additional Functions

Other useful functions provided by the package:

ACS.get_tiger_shapefile — Function
get_tiger_shapefile(year::Int, geography::String)

Download a TIGER/Line shapefile from the US Census Bureau FTP server.

Arguments

  • year::Int: The year of the shapefile to download (e.g., 2023)
  • geography::String: The geographic level, must be either "state" or "county"

Returns

  • Bool: true if download was successful, false otherwise

Examples

# Download 2023 state boundaries
success = get_tiger_shapefile(2023, "county")

# Download 2023 county boundaries  
success = get_tiger_shapefile(2023, "county")

Notes

  • Downloads 500k resolution shapefiles from ftp2.census.gov
  • Files are saved as ZIP archives in the current working directory
  • Existing files with the same name will be overwritten
source

Function Overview

Main Functions

  • get_acs() - General ACS data retrieval function
  • get_acs1() - 1-year ACS estimates (2005-present, except 2020)
  • get_acs3() - 3-year ACS estimates (2007-2013)
  • get_acs5() - 5-year ACS estimates (2009-present)

Margin of Error Functions

  • get_acs_moe() - General MOE data retrieval function
  • get_acs_moe1() - 1-year ACS margins of error
  • get_acs_moe3() - 3-year ACS margins of error
  • get_acs_moe5() - 5-year ACS margins of error

Utility Functions

  • get_tiger_shapefile() - Download Census TIGER shapefiles
  • state_postal_to_fips() - Convert state postal codes to FIPS codes
  • build_census_url() - Build Census API URLs
  • make_census_request() - Make requests to Census API