This is the development version of the Survey Solutions R API package. It allows you to export data/paradata collected through CAWI, CATI or CAPI operations, manipulate users and questionnaires, create assignments, get information about the survey progress etc.. All directly out of R.
However it is more than just a simple wrapper around the Survey Solutions RESTful API, which one can easily address through using i.e. the excellent httr package which also constitutes the basis for this package. The main intention of this package though, is to be integrated into your own data collection workflow, either through a shiny application or just through a simple script. This allows you to build your own workflows with your own customized user interfaces for your Survey Solutions data collection operations, no matter if you are dealing with a small scale impact evaluation or a large scale census. For this reason, the API calls return easy to process data tables, and in some cases, like paradata, even add additional variables useful for further processing.
Important to note here is, that the package also makes extensive use of the data.table package, which allows for fast (multi-core) processing of large data sets. The individual functions either return a data.table, or a specific S3 extension of data.table, with individual methods defined. In case you are not familiar with it yet, you should probably have a look a this introduction.
Nevertheless, in case you don’t require the capacities offered by data.table, you can still treat the return objects like a data frame or even continue with it in the tidyverse. A package which combines both worlds is the dtplyr package, and for a comparison between the dplyr package and the data.table package see here.
Specific changes in version 0.6.X:
- Preparation for token authentication (not active yet)
- Map handling and management: suso_mapupload(), suso_mapassign(), suso_mapinfo()
- Introduction of S3 classes for return values, such that all information returned from the API can be used efficiently. See news for further details and classes.
Installation
The package is not on CRAN yet, so you have to install it by using
devtools::install_github("michael-cw/SurveySolutionsAPI", build_vignettes = T)The included vignettes also contain different examples and further explanations. Bellow you can find a few examples.
Examples
Credentials Management
To use the API you first need to set-up the API user on your Survey Solutions server. See here for details. After this done, you can use the suso_set_key() function, to provide your credentials.
library(SurveySolutionsAPI)
suso_clear_keys()
suso_set_key("https://xxx.mysurvey.solutions", "xxxxxx", "xxxxxxx")
suso_keys()
#> $suso
#> $suso$susoServer
#> [1] "https://xxx.mysurvey.solutions"
#>
#> $suso$susoUser
#> [1] "xxxxxx"
#>
#> $suso$susoPass
#> [1] "xxxxxxx"
#>
#>
#> attr(,"class")
#> [1] "suso_api"Workspace Management
You can also manage your workspaces through the API. In particular, you can
- request a list of all workspaces the API user has access to, as well as
- create new workspaces
- and assign users to a particular workspace.
However for the latter two operations you require ADMIN credentials. Standard API user credentials would not work.
To receive a list of workspaces to which the current API user has access to, you can just run:
ws <- suso_getWorkspace()
print(head(ws))
#> Name DisplayName DisabledAtUtc
#> 1: primary Default Workspace NA
#> 2: test test NA
#> 3: test2 test2 NAUser Management
These functions are particularly useful for survey management, and more details can be found in the corresponding vignette on survey management. Lets start with getting a list of all supervisors on the server.
sv <- suso_getSV(workspace = "test")
print(head(sv))
#> IsLocked CreationDate UserId UserName
#> 1: FALSE 2023-02-07 17:33:40 00d21677-0331-4698-ae7b-908aeac14dd6 somesvuser
#> 2: FALSE 2023-02-04 19:05:10 ded27a4a-716d-4bf2-8d54-aedc31fc164b SV0001
#> 3: FALSE 2023-02-04 19:36:03 5753ddde-3c7d-438f-9934-43fdf18fa802 SV0002
#> 4: FALSE 2023-02-04 19:36:03 72196c84-8f2f-488a-8d61-f23b8b998d43 SV0003
#> 5: FALSE 2023-02-04 19:36:03 1a9d4b10-c92d-401d-af69-2a7d0a391fe6 SV0004
#> 6: FALSE 2023-02-04 19:36:03 97e9e4ff-22e1-492f-a102-03c2115903e7 SV0005Questionnaire Management
The basic questionnaire API calls are handled through the suso_getQuestDetails function.
If no input is provided, the function returns a list of all questionnaires on the server:
questlist <- suso_getQuestDetails(workspace = "test")
# print(questlist)Specifying operation.type = status, you receive a list of statuses.
statlist <- suso_getQuestDetails(operation.type = "statuses", workspace = "test")
print(statlist)
#> [1] "Restored" "Created" "SupervisorAssigned" "InterviewerAssigned" "RejectedBySupervisor" "ReadyForInterview" "SentToCapi"
#> [8] "Restarted" "Completed" "ApprovedBySupervisor" "RejectedByHeadquarters" "ApprovedByHeadquarters" "Deleted"By taking a particular QuestionnaireId and specifying the operation.type you can execute further requests. For example,
Data Export
To export the data collected in Survey Solutions, you use suso_export.
#> The last file has been created 0.06833 hours ago.
#> FileName: assignment__actions
#> Nesting Level: 0
#> ****
#>
#> FileName: households
#> Nesting Level: 1
#> ****
#>
#> FileName: interview__actions
#> Nesting Level: 0
#> ****
#>
#> FileName: interview__diagnostics
#> Nesting Level: 0
#> ****
#>
#> FileName: interview__errors
#> Nesting Level: 0
#> ****Its return value is a list with the following elememts: main, R1, R2, R3, with
- main containing the files: interview__comments, kasai_listing1
- R1 containing all rosters at the first level
- R2 containing all rosters at the second level
- R3 containing all rosters at the third level
through the harmonized ID, main and roster files can easily be put together. More on this in the specific vignette.
Paradata Export
To retrieve the paradata for a particular interview you use suso_export_paradata
system.time(para1 <- suso_export_paradata(questID = questlist[1, QuestionnaireId], workspace = "test", version = questlist[1, Version], reloadTimeDiff = 24, onlyActiveEvents = F, allResponses = T))
#>
#> The last file has been created 1 hours ago.
#>
#> Starting download & file extraction.
#>
#>
#> Calculating Response Timings.
#>
#> Extracting GPS variable.
#> Processing:
#> AnswerSet
#>
#> AnswerRemoved
#>
#> ApproveByHeadquarter
#>
#> Restarted
#>
#> Reject
#>
#> QuestionDeclaredInvalid
#>
#> QuestionDeclaredValid
#>
#> Export & Transformation finished.
#> user system elapsed
#> 0.536 0.036 0.820Map management
Since recently, it is now also possible, to handle maps through the API. This is implemented through the lately introduced GraphQL API.
To upload a map, you can just use the suso_mapupload function like this:
suso_mapupload(workspace = "test", path_to_zip = mapPath)
#> xMaxVal yMaxVal xMinVal yMinVal wkid fileName size maxScale minScale shapeType importDateUtc uploadedBy users
#> 1: -78.39 26.8 -78.62 26.55 4326 checkshapesimple.shp 20467 0 0 Polygon 2023-02-16 17:24:47 961d073f-f316-4353-9e7e-1f00899cb837 <list[0]>To assign a map you can use the suso_mapassign function:
suso_mapassign(workspace = "test", fileName = "checkshapesimple.shp", userName = "INT0004")
#> fileName user shapeType importDateUtc
#> 1: checkshapesimple.shp INT0004 Polygon 2023-02-16 17:24:47Further information
To find information on the World Bank’s Survey Solutions CASS have a look on these pages:
Survey Solutions Support Page: https://support.mysurvey.solutions/
Survey Solutions Server request: https://mysurvey.solutions/
To find information on the API syntax, visit your own servers API documentation or got to:
And to find more information on the package, check out the package vignettes.