Upcoming Census API changes

[jcdepth]

Hi, I got an email from the Census today. It seems like there are some pretty major changes coming to how to query their API. The most relevant part of the email was:

Please note that beginning with the release of the 2016 ACS 1-Year estimates on September 14, 2017, the data will only be available in the new format. We will continue to maintain the 2015 1-Year estimates in the original format until October 2, 2017.

We will let you know when the 2015 ACS 5-Year estimates will be available in the new format. Eventually the remainder of the ACS products in the API will be converted to the new format and we will update you when we have a timeline for those releases. Please contact us via email at cnmp.developers.list@census.gov with any questions or concerns you might have.

There was a linked guide to the changes:
https://www.census.gov/content/dam/Census/data/developers/acs/acs-data-variables-guide.pdf

Does this mean there will have to be a rewriting of the functions in this package?

Thanks for all your hard work with censusapi, I use it on a daily basis.

[hrecht]

Thanks for posting - I didn't get the email!
I'll have to investigate further, it might require some internal function rewrites.

[murray-cecile]

Hi, I was wondering if you'd had a chance to check this out - mostly seems like it changes how it deals with annotation flags for missing values, controlled estimates, etc. But there also is a change to the url.

Here's the reminder email from Census, in case you didn't get it:

This is a reminder that the 2016 ACS 1-Year data will be released next Thursday. The data in the API will be released in a new format that includes the insertion of 'acs/' in the URI after the year and also includes separate annotation fields for each estimate (see guide for details). Also note that some of the 2016 ACS 1-Year annotation flags may include a decimal place (e.g., -8888888 to -8888888.0 or -8888888.00). This precision does not change the meaning of the annotation.

I use your package in my job literally every day, so thank you so much for all of your work on it!

[hrecht]

Hi @murray-cecile & @jcdepth - thanks for flagging. I won't be able to test until it's released, but please reply here with code if you run in to any issues. Since censusapi basically passes whatever you give it to the underlying API, the new endpoint should work.
It should look something like:
getCensus(name = "acs/acs1", vintage = 2016, ...)
I don't think there should be any issues with the annotation flags but we'll see on Thursday.

[hrecht]

This code from the 2015 1-year ACS works fine for me. They released the new "acs/acs1" endpoint for 2015 a little while ago. So hopefully 2016 should be fine too!

getCensus(name="acs/acs1", vintage=2015, vars=c("B01001_001E", "NAME"), region="state:*")

To get the name parameter for a given dataset, you can run

apis <- listCensusApis()

And look at the name column for your dataset of choice. Similarly, my understanding is that the new annotation fields are structured like other variables - so you'd enter something like B01001_001A in the vars list. (But please correct me if I'm misremembering.)

The decimal place change also shouldn't break anything.

[hrecht]

I've run a few basic tests and so far haven't run into any issues with the 2016 ACS. I'll leave this thread open for a little while in case anyone else does.
Here's an example getting total population and median household income estimate and margin of error, plus annotations. (Note there are no annotations for this one.)

dt <- getCensus(name = "acs/acs1", 
vintage = 2016, 
vars = c("B01001_001E", "B19013_001E", "B19013_001EA", "B19013_001M", "B19013_001MA", "NAME"), 
region = "state:*")
head(dt)

[murray-cecile]

As soon as I changed the endpoint, everything worked perfectly. Thanks again for creating this awesome package!

[hrecht]

Closing since no issues have been reported. If anyone runs in to bugs related to the 2016 ACS changes please open a new issue. Thanks all.