`checkarg_time_zone()` should use allowed values from Qualtrics API instead of `base::OlsonNames()`

[MarriumM]

Hello,

I am trying to download surveys from Qualtrics and have been able to connect to the API using my token and base URL (I'm guessing this on the basis of all_surveys() working with no errors).
However, the fetch_surveys does not seem to be working for me when trying to download any surveys. I get this error message:

> survey1 <- fetch_survey(surveyID = "SV_XXXX") ##Tried both copying survey id from the main Qualtrics IDs page as well as in the format of surveys$id[x]
Error in `qualtrics_response_codes()`:
! Qualtrics API reported a bad request error (400):
• Please report this on https://github.com/ropensci/qualtRics/issues

Running rlang::last_trace(drop = FALSE) gives me the following:

Backtrace:
    ▆
 1. └─qualtRics::fetch_survey(surveyID = "SV_XXX")
 2.   └─qualtRics:::export_responses_request(...)
 3.     └─qualtRics:::export_responses_init(surveyID = surveyID, body = body)
 4.       └─qualtRics:::qualtrics_api_request(...)
 5.         └─qualtRics:::qualtrics_response_codes(res)
 6.           └─rlang::abort(error_message)

I have been going over some of the previously closed issues with similar error messages and have tried all the alternatives I can find.

• I am the owner of these surveys so that shouldn't be an issue. I am able to download/export surveys via Qualtric's web interface easily.
• My base URL is correct as far as I can see, and I have tried both formats of organizationID.datacenterID.qualtrics.com and datacenterID.qualtrics.com when registering credentials (with no https:// in the beginning).
• I re-generated my API token just in case that was the problem somehow but nope.
• Running the reprex function with the fetch_surveys gives me the same error message as above:

library(qualtRics)
#> Warning: package 'qualtRics' was built under R version 4.4.3
survey1 <- fetch_survey(surveyID = "SV_XXX")
#> Error in `qualtrics_response_codes()`:
#> ! Qualtrics API reported a bad request error (400):
#> • Please report this on https://github.com/ropensci/qualtRics/issues

• Running the code below also gave me $httpsStatus "200 - OK"

fetch_url <- qualtRics::generate_url(query = "fetchsurvey", surveyID = "SV_XXX")
raw_payload <- qualtRics:::create_raw_payload(
  label = TRUE,
  start_date = NULL,
  end_date = NULL,
  limit = NULL,
  time_zone = NULL,
  unanswer_recode = NULL,
  unanswer_recode_multi = NULL,
  include_display_order = TRUE,
  include_questions = NULL,
  breakout_sets = NULL
)

res <- qualtRics:::qualtrics_api_request("POST", url = fetch_url, body = raw_payload)
res$meta

• In case I was getting proxied, I also ran the curl code in command prompt and got this:

C:\Users\MarriumM>curl --request GET \ --url https://organizationID.ca1.qualtrics.com/API/v3/whoami \ --header 'x-api-token: XXXXXXX'

curl: (3) URL rejected: Bad hostname
{"meta":{"httpStatus":"400 - Bad Request","error":{"errorMessage":"Expected authorization in headers, but none provided.","errorCode":"ATP_2"},"requestId":"7b76c415-69b1-4aad-8b6f-686a60f05d92"}}curl: (3) URL rejected: Bad hostname
curl: (3) URL rejected: Bad hostname

I Googled this and got another format of this command to try and got this as a result, which I am assuming means things are okay on this end and my request is not getting proxied?

 -H "X-API-TOKEN: XXXXX" -H "Content-Type: application/json"  -X GET "https://datacenterID.qualtrics.com/API/v3/whoami
{"result":{"brandId":"XX"
,"userId":"XX",
"userName":"XX",
"accountType":"XX",
"firstName":"X",
"lastName":"X",
"email":"X",
"datacenter":"viawest"},
"meta":{"requestId":"2ed8adf8-f84c-45d6-bde4-48a227236063"
,"httpStatus":"200 - OK"}}

I've tried figuring out what else could possibly be wrong but I have hit a wall at this point! Can you tell me why this is happening and/or what can I do to fix this?
I am a beginner to coding (and R!) so I am afraid I don't understand most of this other than what my searches on Google provide and so I apologize if there any obvious things I missed!

[juliasilge]

Thank you so much for all your detailed exploration to find out what the problem is!

Let's step through what the fetch_survey() function is trying to do, to see where the problem is.

The first thing is does initiate a request to the export-responses API endpoint. You can force that to see what happens by doing:

raw_payload <- '{"format":"csv","useLabels":true,"timeZone":"America/Denver","includeDisplayOrder":true,"breakoutSets":true}'

qualtRics:::export_responses_init("SV_xxxxxxxxx", raw_payload)

This should succeed and give you a request ID that looks something like "ES_xxxxxxxx".

Next we try to monitor progress from the response request download, and get a file download location. You can see how that goes with:

qualtRics:::export_responses_progress("SV_xxxxxxxxx", "ES_xxxxxxxx", TRUE)

This should succeed and give you a file ID that looks something like "46603aaf-42ad-498c-924b-052415670360-def".

After that, we try to download and then open the file, which you can do with (don't forget to use your own survey and file IDs):

qualtRics:::export_responses_filedownload(
  "SV_xxxxxxxxx",
  "46603aaf-42ad-498c-924b-052415670360-def",
  tempdir() 
)

If that last step is what fails, you might try seeing what errors you get from:

file_url <- qualtRics:::generate_url(
  "exportresponses_file",
  surveyID = "SV_xxxxxxxxx",,
  fileID = "46603aaf-42ad-498c-924b-052415670360-def"
)

out <- qualtRics:::qualtrics_api_request(
  verb = "GET",
  url = file_url,
  as = "raw"
)

[MarriumM]

Hi Julia,

Thank you for the step-by-step explanations! I really appreciate this look at how the function actually works.

I ran all these steps (except the last one since I didn't get any errors) and interestingly, I am able to download and open the file both via R and as a csv in the Temp folder. I did this for multiple surveys and I don't get any errors at all with the step by step process but I still do for the fetch_survey function (?).

Any thoughts on this?

[juliasilge]

Wow, strange! What happens if you do this?

raw_payload <- '{"format":"csv","useLabels":true,"timeZone":"America/Denver","includeDisplayOrder":true,"breakoutSets":true}'

qualtRics:::export_responses_request(
  "SV_xxxxxxxxx",
  raw_payload,
  verbose = TRUE,
  tmp_dir = tempdir() 
)

This wraps up initiating the request, monitoring the progress, getting the download location, downloading, and then opening the file.

[MarriumM]

The same thing happens, except now there's a download bar after which I have a tibble of the survey as well as a csv that gets downloaded to the temp folder.

> qualtRics:::export_responses_request(
+     "SV_XXXXXX",
+     raw_payload,
+     verbose = TRUE,
+     tmp_dir = tempdir() 
+ )
  |==================================================| 100%
# A tibble: 8 × 207                                         
  StartDate                EndDate Status IPAddress Progress
  <chr>                    <chr>   <chr>  <chr>     <chr>   

[juliasilge]

Oh my goodness, this is WILD. If you take a look at what happens in fetch_survey(), the only part that calls the Qualtrics API is export_responses_request()! 😱

Are you saying that:

• calling fetch_survey() gives you a 400 error?
• calling qualtRics:::export_responses_request() succeeds?

If so, I am wondering if you know how to use debugonce(), to step through the code? I would do debugonce(qualtRics::fetch_survey) and then see if you get an error.

[MarriumM]

Yes that is exactly it! It is super weird since only the main function doesn't work but the step by step and last code you asked me to run worked with no issues.

I don't know how to use debugonce() but I looked it up and copied the lines below so you can see what happens!

From what I can see, the error seems to be in the rawdata where export_responses_request() is defining it? Which again is weird since running export_responses_request() works fine on its own?

> mysurveys <-fetch_survey(surveyID = "SV_XXXX")
debugging in: fetch_survey(surveyID = "SV_XXXX")
debug: {
    if (lifecycle::is_present(last_response)) {
        lifecycle::deprecate_stop("3.1.2", "fetch_survey(last_response = )")
    }
    if (lifecycle::is_present(force_request)) {
        lifecycle::deprecate_warn("3.2.0", "fetch_survey(force_request = )")
    }
    if (lifecycle::is_present(save_dir)) {
        lifecycle::deprecate_warn("3.2.0", "fetch_survey(save_dir = )")
    }
    check_credentials()
    time_zone_formatted <- checkarg_time_zone(time_zone)
    start_date_formatted <- checkarg_datetime(start_date, time_zone = time_zone)
    end_date_formatted <- checkarg_datetime(end_date, time_zone = time_zone, 
        endofday = FALSE)
    include_metadata_formatted <- checkarg_include_metadata(include_metadata)
    include_questions_formatted <- checkarg_include_questions(include_questions)
    include_embedded_formatted <- checkarg_include_embedded(include_embedded)
    checkarg_col_types(col_types)
    checkarg_limit(limit)
    checkarg_convert_label_breakouts(convert, label, breakout_sets)
    checkarg_tempdir(tmp_dir)
    checkarg_isintegerish(unanswer_recode)
    checkarg_isintegerish(unanswer_recode_multi)
    checkarg_isboolean(include_display_order)
    checkarg_isboolean(verbose)
    checkarg_isboolean(import_id)
    checkarg_isboolean(add_column_map)
    checkarg_isboolean(add_var_labels)
    checkarg_isboolean(strip_html)
    raw_payload <- create_raw_payload(format = "csv", useLabels = label, 
        startDate = start_date_formatted, endDate = end_date_formatted, 
        timeZone = time_zone_formatted, limit = limit, seenUnansweredRecode = unanswer_recode, 
        multiselectSeenUnansweredRecode = unanswer_recode_multi, 
        includeDisplayOrder = include_display_order, questionIds = include_questions_formatted, 
        embeddedDataIds = include_embedded_formatted, surveyMetadataIds = include_metadata_formatted, 
        breakoutSets = breakout_sets)
    rawdata <- export_responses_request(surveyID = surveyID, 
        body = raw_payload, verbose = verbose, tmp_dir = tmp_dir)
    data <- process_raw_survey(rawdata = rawdata, import_id = import_id, 
        time_zone = time_zone_formatted, col_types = col_types, 
        add_column_map = add_column_map, add_var_labels = add_var_labels, 
        strip_html = strip_html)
    if (convert & label) {
        data <- infer_data_types(data, surveyID)
    }
    return(data)
}
Browse[1]> n
debug: if (lifecycle::is_present(last_response)) {
    lifecycle::deprecate_stop("3.1.2", "fetch_survey(last_response = )")
}
Browse[1]> n
debug: if (lifecycle::is_present(force_request)) {
    lifecycle::deprecate_warn("3.2.0", "fetch_survey(force_request = )")
}
Browse[1]> n
debug: if (lifecycle::is_present(save_dir)) {
    lifecycle::deprecate_warn("3.2.0", "fetch_survey(save_dir = )")
}
Browse[1]> n
debug: check_credentials()
Browse[1]> n
debug: time_zone_formatted <- checkarg_time_zone(time_zone)
Browse[1]> n
debug: start_date_formatted <- checkarg_datetime(start_date, time_zone = time_zone)
Browse[1]> n
debug: end_date_formatted <- checkarg_datetime(end_date, time_zone = time_zone, 
    endofday = FALSE)
Browse[1]> n
debug: include_metadata_formatted <- checkarg_include_metadata(include_metadata)
Browse[1]> n
debug: include_questions_formatted <- checkarg_include_questions(include_questions)
Browse[1]> n
debug: include_embedded_formatted <- checkarg_include_embedded(include_embedded)
Browse[1]> n
debug: checkarg_col_types(col_types)
Browse[1]> n
debug: checkarg_limit(limit)
Browse[1]> n
debug: checkarg_convert_label_breakouts(convert, label, breakout_sets)
Browse[1]> n
debug: checkarg_tempdir(tmp_dir)
Browse[1]> n
debug: checkarg_isintegerish(unanswer_recode)
Browse[1]> n
debug: checkarg_isintegerish(unanswer_recode_multi)
Browse[1]> n
debug: checkarg_isboolean(include_display_order)
Browse[1]> n
debug: checkarg_isboolean(verbose)
Browse[1]> n
debug: checkarg_isboolean(import_id)
Browse[1]> n
debug: checkarg_isboolean(add_column_map)
Browse[1]> n
debug: checkarg_isboolean(add_var_labels)
Browse[1]> n
debug: checkarg_isboolean(strip_html)
Browse[1]> n
debug: raw_payload <- create_raw_payload(format = "csv", useLabels = label, 
    startDate = start_date_formatted, endDate = end_date_formatted, 
    timeZone = time_zone_formatted, limit = limit, seenUnansweredRecode = unanswer_recode, 
    multiselectSeenUnansweredRecode = unanswer_recode_multi, 
    includeDisplayOrder = include_display_order, questionIds = include_questions_formatted, 
    embeddedDataIds = include_embedded_formatted, surveyMetadataIds = include_metadata_formatted, 
    breakoutSets = breakout_sets)
Browse[1]> n
**debug: rawdata <- export_responses_request(surveyID = surveyID, body = raw_payload, 
    verbose = verbose, tmp_dir = tmp_dir)**
Browse[1]> n
Error in `qualtrics_response_codes()`:
! Qualtrics API reported a bad request error (400):
• Please report this on https://github.com/ropensci/qualtRics/issues
Run rlang::last_trace(drop = FALSE) to see 1 hidden frame.
> rlang::last_trace(drop = FALSE)
<error/rlang_error>
Error in `qualtrics_response_codes()`:
! Qualtrics API reported a bad request error (400):
• Please report this on https://github.com/ropensci/qualtRics/issues
---
Backtrace:
    ▆
 1. └─qualtRics::fetch_survey(surveyID = "SV_0CUgWdeBLajTG18")
 2.   └─qualtRics:::export_responses_request(...)
 3.     └─qualtRics:::export_responses_init(surveyID = surveyID, body = body)
 4.       └─qualtRics:::qualtrics_api_request(...)
 5.         └─qualtRics:::qualtrics_response_codes(res)
 6.           └─rlang::abort(error_message)

[juliasilge]

That is so wild! Can you do debugonce(qualtRics:::export_responses_request) now, to see which part is erroring?

[MarriumM]

Okay so now I get this error where apparently surveyID is missing, although I have it loaded and went through all the steps of defining it first? (I also checked this with multiple survey IDs)

debugging in: qualtRics:::export_responses_request()
debug: {
    requestID <- export_responses_init(surveyID = surveyID, body = body)
    fileID <- export_responses_progress(surveyID = surveyID, 
        requestID = requestID, verbose = verbose)
    survey_rawdata <- export_responses_filedownload(surveyID = surveyID, 
        fileID = fileID, tmp_dir = tmp_dir)
    return(survey_rawdata)
}
Browse[1]> n
debug: requestID <- export_responses_init(surveyID = surveyID, body = body)
Browse[1]> n
Error in qualtRics:::export_responses_request() : 
  argument "surveyID" is missing, with no default

I don't know if it this helps or not, but I ran rlang::last_trace(drop = FALSE) to see if it would give me something and it gave me this:

> rlang::last_trace(drop = FALSE)
<error/rlang_error>
Error in `qualtrics_response_codes()`:
! Qualtrics API reported a bad request error (400):
• Please report this on https://github.com/ropensci/qualtRics/issues
---
Backtrace:
    ▆

1. └─qualtRics::fetch_survey(surveyID = "SV_XXXX")
2.   └─qualtRics:::export_responses_request(...)
3.     └─qualtRics:::export_responses_init(surveyID = surveyID, body = body)
4.       └─qualtRics:::qualtrics_api_request(...)
5.         └─qualtRics:::qualtrics_response_codes(res)
6.           └─rlang::abort(error_message)

Am I doing something wrong or is this helping?

[juliasilge]

When you are doing the debugging and you are at the line:

requestID <- export_responses_init(surveyID = surveyID, body = body)

Instead of just saying next, next, next, can you see what is stored in the variable surveyID? And I guess check the other ones like body while you are there. During debugging, you have a console there that you can type in, and you can print out a variable to see what its value is.

[MarriumM]

Okay that makes so much more sense then what I was doing before haha!

So I did two things. First I went and checked the requestID line with the export_responses_request function as you suggested. The surveyID gave me the correct surveyID value I had put in but I got an error that body was not defined(?, not sure if that's the correct term!).

> debugonce(qualtRics:::export_responses_request)
> qualtRics:::export_responses_request(surveyID = "SV_XXXX")
debugging in: qualtRics:::export_responses_request(surveyID = "SV_XXXX")
debug: {
    requestID <- export_responses_init(surveyID = surveyID, body = body)
    fileID <- export_responses_progress(surveyID = surveyID, 
        requestID = requestID, verbose = verbose)
    survey_rawdata <- export_responses_filedownload(surveyID = surveyID, 
        fileID = fileID, tmp_dir = tmp_dir)
    return(survey_rawdata)
}
Browse[1]> n
debug: requestID <- export_responses_init(surveyID = surveyID, body = body)
Browse[1]> surveyID
[1] "SV_XXXX"
Browse[1]> body
Error in qualtRics:::export_responses_request(surveyID = "SV_XXXX") : 
  argument "body" is missing, with no default

So then I checked the export_responses_request function within fetch_survey and this time it gave me both the correct surveyID as well as a description of the body. However, it still did not run the line and also gave me the same orignal error message.

> debugonce(qualtRics:::export_responses_request)
> fetch_survey(surveyID = "SV_XXXX")
debugging in: export_responses_request(surveyID = surveyID, body = raw_payload, 
    verbose = verbose, tmp_dir = tmp_dir)
debug: {
    requestID <- export_responses_init(surveyID = surveyID, body = body)
    fileID <- export_responses_progress(surveyID = surveyID, 
        requestID = requestID, verbose = verbose)
    survey_rawdata <- export_responses_filedownload(surveyID = surveyID, 
        fileID = fileID, tmp_dir = tmp_dir)
    return(survey_rawdata)
}
Browse[1]> n
debug: requestID <- export_responses_init(surveyID = surveyID, body = body)
Browse[1]> body
{"format":"csv","useLabels":true,"timeZone":"EST","includeDisplayOrder":true,"breakoutSets":true} 
Browse[1]> surveyID
[1] "SV_XXXX"
Browse[1]> n
Error in `qualtrics_response_codes()`:
! Qualtrics API reported a bad request error (400):
• Please report this on https://github.com/ropensci/qualtRics/issues
Run `rlang::last_trace()` to see where the error occurred.

Does this make sense?

[MarriumM]

Hi again Julia!

I don't know what happened but I randomly ran the fetch_survey function this morning and it seems like it is working for me now?

I checked to see if I was doing anything differently and the only difference I can see is that I was using Sys.setenv(TZ = "EST") to set the time zone before I ran fetch_survey() and every time I do that, it gives me the same error (bad request error (400)):

library(qualtRics)
#> Warning: package 'qualtRics' was built under R version 4.4.3

# Step 4 - List all surveys 

surveys <- all_surveys()

# Step 5 - Set time zone

Sys.setenv(TZ = "EST")

# Step 6 - Select surveys to be downloaded

mysurveys <-fetch_survey(surveyID = "SV_XXX")

#> Error in `qualtrics_response_codes()`:
#> ! Qualtrics API reported a bad request error (400):
#> • Please report this on https://github.com/ropensci/qualtRics/issues

^{Created on 2025-03-25 with reprex v2.1.1}

But when I don't run the Sys.setenv(TZ = "EST"), the fetch_survey() works just fine:

library(qualtRics)
#> Warning: package 'qualtRics' was built under R version 4.4.3

# Step 4 - List all surveys 

surveys <- all_surveys()

# Step 6 - Select surveys to be downloaded

mysurveys <-fetch_survey(surveyID = "SV_XXXX")
#>   |                                                                              |                                                                      |   0%  |                                                                              |======================================================================| 100%
#> 
#> ── Column specification ────────────────────────────────────────────────────────
#> cols(
#>   .default = col_character(),
#>   StartDate = col_datetime(format = ""),
#>   EndDate = col_datetime(format = ""),
#>   Progress = col_double(),
#>   `Duration (in seconds)` = col_double(),
#>   Finished = col_logical(),
#>   RecordedDate = col_datetime(format = ""),
#>   RecipientLastName = col_logical(),
#>   RecipientFirstName = col_logical(),
#>   RecipientEmail = col_logical(),
#>   ExternalReference = col_logical(),
#>   LocationLatitude = col_double(),
#>   LocationLongitude = col_double()
#> )
#> ℹ Use `spec()` for the full column specifications.

# Step 7 - Save responses to a csv file

write.csv(mysurveys, file = "baseline_survey.csv", row.names = FALSE)

^{Created on 2025-03-25 with reprex v2.1.1}

I still don't know why this made such a huge difference but the fetch_survey() definitely works now. So it was totally my bad and I am really sorry to trouble you with this for the past week or so! I can finally stop running in circles now...

[juliasilge]

Ah, amazing job on figuring it out! 🙌

Looks like that is not one of the allowed timezone strings for the Qualtrics API:
https://api.qualtrics.com/c2NoOjYwNTY0-time-zone

When we check the timezone here, we should use the allowed timezone strings from the API instead of OlsonNames():

qualtRics/R/checks.R

Line 183 in 97f1d1a

if(!time_zone %in% OlsonNames()){