This is a (beta - release1) new edition of the Survey Solutions R API package, based on the recently (as stable) released httr2 package. Most of the syntax is the same as in the existing httr based SurveySolutionsAPI package, and therefore it should be easy to integrate it in your existing workflow, if you have used the previous edition so far.
But besides a few syntax changes as well as several other updates like more meaningful error messages using the cli and the rlang packages there are also quite a bunch of new features. Therefore i decided to release this package as a completely new one, such that users who do not want to switch to the new package or make use of the new features, can still work with the old package as usual. Nevertheless a transition to the new package is recommended.
Additionally the package also seeks a deeper integration with the updated susographql package, which now also is purely based on the httr2 package.
- suso_get_stats_interview, suso_get_assignments, suso_createUSER, suso_createASS, suso_getSV and suso_getINT with potentially long running queries now use httr2’s parallel request feature, which reduces processing time substantially. For example 10k assignments (suso_createASS) can now be created in about 3 minutes, a list of all interviewers (suso_getINT) in a workspace for 18K interviewers and 5k supervisors now only takes around 1.5 minutes. In particular in large scale surveys and censuses, this feature may facilitate working with the API considerably.
- suso_set_key: workspace can now be set as an environment variable, like it was already the case for server, user and password.
- suso_export: now has the option to merge all the data export files into a single data table and also add survey weights, for analysis-ready data sets.
- suso_export: of spatial (Survey Solutions Geography Questions) data (i.e. polygons, point locations, lines) can be processed into sf (simple feature) objects directly, by setting process_mapquestions = TRUE. For example a type polygons question, collected manually or automatic, will result in an sf polygon, which can be stored directly as a shape file with st_write.
- suso_export: now also processes available value labels and applies them to categorical variables, as well as variable labels. In case you have one or several translations for your questionnaire, these can be used as well, such that the labels applied are in the required language. The (ExportClass) specific methods, subsequently make use of these additional attributes, resulting in publication-ready tables and graphs.
- suso_export_paradata: now uses milliseconds for all time based calculations, and also adds comprehensive questionnaire information to the data, like i.e. question type.
- suso_export_paradata: now also identifies GPS variable in your questionnaire, and uses it, to add GPS location data to the paradata, which facilitates spatial analysis of paradata considerably.
- suso_mapupload, suso_mapassign, suso_maps, suso_mapreport and suso_deletemap now also enable complete map management with a single package, and the same syntax/outputs2.
- suso_assignWorkspace: now also supports workspace assignment of multiple supervisors and interviewers in one go. In addition it has the argument keep_old_workspace . If TRUE , then the existing workspaces the user is already assigned to are automatically added. With this new feature, all users from one workspace can be assigned to a new workspace with a single function call (requires admin credentials!).
- New classes and methods, i.e.: AssignmentClass, ExportClass, UserClass, and methods like summaryTable.exportClass (DT based) or boxplot_summary.exportClass (ggplot2 based).
- Http error messages are translated into R errors, and use the error codes (and messages) as provided by the Survey Solutions API response), which makes debugging easier.
- Several options, which allows the user to customize processing to their environment, like: suso.maxpar.req for the maximum number of parallel requests, suso.para.break for customizing breaks when calculating paradata response times, suso.para.tz for setting the time zone or suso.para.maxcore for the number of cores used in parallel processing.
- User notifications including progress bars when used in shiny applications, for potentially long running processes.
This is just a very rough overview of the most prominent features, for details please see the individual functions’ documentation. An extensive documentation is still in preparation and will follow over the next weeks, as well as some more class specific methods. For now, until the new documentation (i.e vignettes, gihub.io website) is released please use the original SurveySolutionsAPI package documentation, which is still valid for most of the functions.
For more details please see the corresponding GitHub repository: GitHub - michael-cw/SurveySolutionsAPIv2: A comprehensive set of R functions to access the Survey Solutions REST/GraphQL API (httr2 based version).
Since this is a beta release, feedback, bug reports and feature requests are very welcome. You can either use the standard GitHub approach by filing a bug report/feature request here or respond directly to this post.