Working With Census API and ACS 5-year data

've just started working with Census APIs, and so far I'm loving what this can do to improve my work flow when working with American Community Survey Data.

For most of the data work I'm doing, my primary geographic level is the county subdivision. BUT, I also like to include data for each of the counties I'm working with, and the state level.

I know how to access EACH of those three levels, but I'm not sufficiently familiar with JSON programming protocols to know how (or whether) I can combine multiple geographic LEVELS in a single API data call?

I have been looking at the EXAMPLES found here [], and don't see any that combine multiple geographic levels, but I strongly suspect this is something I should be able to do?

Thanks for any assistance folks can offer.

Cheers, Doug.

P.S FYI, this is me here: and here: 

  • As far as I know, you can only request a single geography in each API call. But the structure of the calls and the data returned are consistent, so you could write a for loop or use other functions to iterate through each geography you want and create the API calls. You don't mention how you are accessing the API, but if you are an R user, I highly recommend the tidycensus package, which wraps the API in a pretty easy interface and pulls the data directly into.

    Here for example is one way to get data for county subdivision, county, and state using R and tidycensus:

    geos <- c("state", "county", "county subdivision")

    ~ tidycensus::get_acs(
    geography = .x,
    state = "MA",
    variables = "B01003_001",
    survey = "acs5",
    year = 2019

    There also is a Cenus Slack channel which is a good place to ask questions about using Census APIs

  • Thanks, Matt. I'm definitely a newbie with R but will bookmark your reply so I can use this format when I get to that point of the learning curve! (As for the Census Bureau Slack channel, I'm definitely interested, but have to figure out how to navigate the process without a Census Bureau email address). Cheers, Doug. 

  • You should be able to join the Census slack with any email address -- it's for API users and there are some Census staff that answer questions. If that link isn't working, try the link at the top of this page:

    Good luck on your R journey! If you haven't already found it, R for Data Science is my favorite resource for learning R:

  • tidycensus has lots more to recommend it--more output options, getting spatial data in the same query, etc. And if you want block group data, which needs to be queried county-by-county, tidycensus will do this in one query and combine the results. 

    There's also the censusapi package, which allows access to a wider variety of datasets but is more stripped-down in that you need to format arguments exactly as the API requires--for example, using FIPS codes directly instead of having tidycensus translate state/county abbreviations/names for you). The advantage is that censusapi tends to be around 25%-50% faster in my experience, though I haven't done any formal benchmarking. In absolute terms, this doesn't matter much--only 1-3 seconds per query--but that can still result in substantial time savings if you need data for several tables and/or geographic levels.

    I know this isn't an R forum, but since you expressed interest: working with the Census Bureau API really helped me learn more R, especially in writing functions and understanding the many capabilities of the purrr package. In addition to map_dfr(), which Matt H used above to append data for multiple geographic levels, map_dfc() will join data for multiple tables (but to be on the safe side, you'll want to make sure whatever function you're using will sort the data that map_dfc() combines, because you can't specify a join-by variable).

    Good luck!

    ~~~ Edit 15 minutes later: I just realized that it's now possible to put wildcard characters in the query, which (for example) will let you get block groups for an entire state at once rather than county-by-county. This seems to magnify the time savings of censusapi over tidycensus. It doesn't solve the initial problem of combining data from multiple geographic levels, but it seemed worth mentioning.

  • Hi Matt! Do you think you could ping the admin to have them change the settings? I'm trying to join the Slack workspace but it does require a email address:

    Don’t have an email address?
    Contact the workspace administrator at U.S. Census Bureau for an invitation.

    I'm trying these entry points:

  • Interesting! Looks like those links are dead. Can you try this link:

    That is an invite link I was able to create from Slack.

    Either way I’ll let Logan at Census know the link on the developer page isn’t working. 

  • That worked – thank you so much, Matt!

  • Interesting about the speed difference between tidycensus and censusapi. I wonder if that is in the parsing of the API response -- if I have some time, I'll check it out. 

    As to wildcards for all block groups, we got an issue tracking that and hope to implement it at some point soon!

  • Thanks, btw, Matt. There were some issues getting into the Slack group, but I'm there now. I appreciate all the resources and support I can get! Cheers, Doug.

  • Hi Matt, I am also trying to join the Slack but none of the links in this thread work.  They all require me to have a email address.  I was wondering if you could send a new invite link so I could join.