API Functions

Main Interface

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
) -> DataFrame

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: 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 data

Example

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

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: 2022)
  • state: Optional state postal code or FIPS code
  • county: Optional county FIPS code (requires state)

Returns

DataFrame with requested Census data

Example

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

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)

Returns

DataFrame with requested Census data

Example

# Get total population for all states in 2013
df = get_acs3(
    variables = ["B01003_001E"],
    geography = "state",
    year = 2013
)
ACS.get_acs5 — Function
get_acs5(;
    variables::Vector{String},
    geography::String,
    year::Int = 2022,
    state::Union{String,Nothing} = nothing,
    county::Union{String,Nothing} = nothing
) -> 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)

Returns

DataFrame with requested Census data

Example

# Get total population for all states
df = get_acs5(
    variables = ["B01003_001E"],
    geography = "state"
)
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"
)
ACS.get_acs_moe1 — Function
get_acs_moe1(;
    variables::Vector{String},
    geography::String,
    year::Int = 2022,
    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: 2022)
  • 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"
)
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
)
ACS.get_acs_moe5 — Function
get_acs_moe5(;
    variables::Vector{String},
    geography::String,
    year::Int = 2022,
    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: 2022)
  • 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"
)

Helper Functions

ACS.state_postal_to_fips — Function
state_postal_to_fips(postal_code::String) -> String

Convert a state postal code to its FIPS code.

ACS.create_geoid — Function
create_geoid(df::DataFrame, geography::String) -> Vector{String}

Create GEOID values for a DataFrame based on geography type.

Internal Functions

These functions are used internally but may be useful for advanced users:

ACS.make_census_request — Function
make_census_request(url::String, headers::Vector{Pair{String,String}}) -> HTTP.Response

Make a request to the Census API with robust error handling and retries.

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

Build a Census API URL for the given parameters.

ACS.process_census_response — Function
process_census_response(r::HTTP.Response, geography::String) -> DataFrame

Process a Census API response into a DataFrame.