Bug report: Example for SAHIE fails with 'unknown predicate variable' error

[jamgreen]

Describe the bug I attempted to follow the basic example calling the SAHIE data and the following error returned. Note I change my key for security reasons.

Error in apiCheck(req) : The Census Bureau returned the following error message: error: unknown predicate variable: 'year' Your API call was: https://api.census.gov/data/timeseries/healthins/sahie?key=asdf&get=NAME%2CIPRCAT%2CIPR_DESC%2CPCTUI_PT&for=state%3A01&year=2018

To Reproduce

This was the call I pulled directly from the example, just substituting my api key.

asdf <- getCensus(name = "timeseries/healthins/sahie", vars = c("NAME", "IPRCAT", "IPR_DESC", "PCTUI_PT"), region = "state:01", year = 2018, key = Sys.getenv("CENSUS_API_KEY"))

R session information:

• censusapi package version: censusapi_0.7.1
• R version: 4.0.2 on Windows 10 x64 (build 19042)

Additional context

Nothing immediately comes to mind that would be useful.

[hrecht]

Ugh it looks like the Census Bureau changed that API again. Previously the syntax was time, then it was changed to year, hence the updated documentation, and now it looks like it's time again. I updated the examples to use year in early June. Change it to time and it should work.

cc @loganpowell @uscensusbureau please stop making these undocumented and unannounced API changes.

[loganpowell]

Looks like either YEAR (all caps) or time will work... is this breaking?

[hrecht]

time was not working for several months earlier this year. Previously lower case year worked when I updated these examples in June. Can you confirm if the current version is still in flux or if it's final? Which is preferred, time or YEAR?

[loganpowell]

according to the discovery tool it seems both are acceptable, but time is required. They are not equal, i.e., time is ISO date/time standard and YEAR is just an Int.

[hrecht]

Related to #72 and #75. This seems to be working now. You can use either year or time, but I prefer to use year in these annual timeseries APIs to get more than one year.

Unfortunately the written SAHIE API documentation is years out of date so it's difficult for me to figure out what has changed or how to retrieve multiple years worth of data using the time parameter. year seems to work with year="start:stop" but time only works with the very not programmer-friendly time="from start to stop".

# This works and is programmer-friendly
year_prog <- getCensus(
  name = "timeseries/healthins/sahie", 
  vars = c("NAME", "IPRCAT", "IPR_DESC", "PCTUI_PT"), 
  region = "state:01", 
  year = "2010:2018")

# This does not work
year_verbose <- getCensus(
  name = "timeseries/healthins/sahie", 
  vars = c("NAME", "IPRCAT", "IPR_DESC", "PCTUI_PT"), 
  region = "state:01", 
  year = "from 2010 to 2018")

# This does not work
time_prog <- getCensus(
  name = "timeseries/healthins/sahie", 
  vars = c("NAME", "IPRCAT", "IPR_DESC", "PCTUI_PT"), 
  region = "state:01", 
  time = "2010:2018")

# This works using written out notation - not programmer-friendly
time_verbose <- getCensus(
  name = "timeseries/healthins/sahie", 
  vars = c("NAME", "IPRCAT", "IPR_DESC", "PCTUI_PT"), 
  region = "state:01", 
  time = "from 2010 to 2018")