{"_id":"57028c6c747d6d0e0076ff6d","user":"558435c2fb52ee0d0015d190","version":{"_id":"558444ceafccfd0d00fcb2bb","forked_from":"55843604fd8d910d007b9505","project":"55843604fd8d910d007b9502","__v":60,"createdAt":"2015-06-19T16:35:26.435Z","releaseDate":"2015-06-19T16:35:26.435Z","categories":["558444cfafccfd0d00fcb2bc","558444cfafccfd0d00fcb2bd","55ad4ce733616a0d00599d2e","55ad4cef6aadf20d0015b764","55ad4cf36aadf20d0015b765","55ad4cfb24cf160d0013584f","55ad4d0024cf160d00135850","55ad4d0a24cf160d00135851","55ad4d0d24cf160d00135852","55ad4d126aadf20d0015b766","55ad4d1624cf160d00135853","55ad4d1933616a0d00599d2f","55ad4d2233616a0d00599d30","55ad4d2e24cf160d00135854","55d35b6bf77e6d0d00b1b092","55d3649a0168850d0073f14a","55d366d40168850d0073f15a","55d37fcff77e6d0d00b1b13f","55d383e50168850d0073f1e1","55d3ac26c336ec0d007c2251","55d3c51cb2330119009c31db","55d3c59bfe37111900e536f3","55d3c5a7fe37111900e536f4","55d3c5b4fe37111900e536f5","55d3c5d4fe37111900e536f6","55d3c5d6b2330119009c31df","55d3c5d71f478b170077c164","55d3c687b2330119009c31e4","55d3c6a4fe37111900e536f9","55d3c6befe37111900e536fa","55d3c6e8d2c66f0d00497f93","55d49dcfd7c16b2d007de905","55d4ca8f5082980d0009c79b","55d4cab9c95a3d2f0069ad3d","55d4d279c95a3d2f0069ad60","55d4d9355082980d0009c7e1","55d4f6b5988e130d000b3eb1","55d64dc8e60a2f0d00b88ecb","5627ca43fcbbc621004ec07d","56c64a0d8f98b50d0012c37c","56f1b8b13eb62a34003ea041","56f1b9df4476fb2200795e8c","57f6907dca5e5d1700039ae9","591dd06ca266c423002ec4ca","59234825e465c11900922518","5936f82eaa591e0027638d57","59972f54fd7078001992c136","599c6da8f180820025f14909","59b054613c3e1b0019cf27d9","59b1ceca2d6231003ad73e5f","59b1cf1857911600382e0dc4","59b1cf2730f3d60010c30ef7","59b1cf385d4b89003035441a","59b1cf5857911600382e0dc6","59bc2c4e26ac9b0010a8b753","59bc2ce20b3eb30010657b70","59f0c793ba3bc90030f413ab","59f0cd62f5ecda00325294b9","59fb55a8e8d0f600101aedc3","59fcb05c067f8d0028613f86","5a2af4a1bc5fba00283909c1"],"is_deprecated":false,"is_hidden":false,"is_beta":true,"is_stable":true,"codename":"","version_clean":"3.0.0","version":"3"},"category":{"_id":"59234825e465c11900922518","__v":0,"version":"558444ceafccfd0d00fcb2bb","project":"55843604fd8d910d007b9502","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2017-05-22T20:20:53.281Z","from_sync":false,"order":1,"slug":"using-the-qualtrics-api","title":"Using the Qualtrics APIs"},"__v":16,"parentDoc":null,"project":"55843604fd8d910d007b9502","updates":["579fa3e72444f50e00ff132d","58597395fb96101b000d602a","588dabeb0b08260f00d226ca","5899f89ad7758725009859a7","5899fbf079a27e1b00deda4a","59cee53b86221200280ec675","59cee8058ecf58002650bd01"],"next":{"pages":[],"description":""},"createdAt":"2016-04-04T15:46:52.700Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":4,"body":"This document describes how you can get your users' responses to your surveys. The first and second sections explain how to get responses using Python and Java, and the last section shows how to use the **qualtRics** package to get survey responses with R.\n[block:api-header]\n{\n  \"title\": \"Getting Survey Responses with Python\"\n}\n[/block]\nThe process of getting survey responses requires four steps:\n\n1. Request the responses with the [Create Response Export](doc:create-response-export) API. Qualtrics will create a .zip file that contains the requested responses. You can use various filtering options to this request to retrieve a subset of the responses to speed up processing. See step 1 in the samples below.\n\n2. Request the export status using the [Get Response Export Progress](doc:get-response-export-progress) API. The `result` object will contain a `percentComplete` value. Keep looping until `percentComplete` is 100. (You might want to sleep a few seconds between requests.) \n\n3. Once the export progress is 100, use the `file` string in the `result` object from Get Response Export Progress. (See the third code sample below for an example.) Make a `GET` request to this URL to retrieve your response file, which will be a zipped file containing the responses. The samples below show an alternative method by creating the URL from the id returned in step 1.\n\n4. Unzip the file to find the survey responses in the format you requested (csv, csv2013, xml, json, or spss). If the file exceeds the static limits on file size, your responses will be split into several files and included in the .zip file.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"# For Python 2.7.10\\nimport requests\\nimport zipfile\\ntry: import simplejson as json\\nexcept ImportError: import json\\n\\n# Setting user Parameters\\napiToken = \\\"MYAPITOKEN\\\"\\nsurveyId = \\\"SV_dimlWvV7hWLCJdX\\\"\\nfileFormat = \\\"csv\\\"\\ndataCenter = 'ca1'\\n\\n# Setting static parameters\\nrequestCheckProgress = 0\\nprogressStatus = \\\"in progress\\\"\\nbaseUrl = \\\"https://{0}.qualtrics.com/API/v3/responseexports/\\\".format(dataCenter)\\nheaders = {\\n    \\\"content-type\\\": \\\"application/json\\\",\\n    \\\"x-api-token\\\": apiToken,\\n    }\\n\\n# Step 1: Creating Data Export\\ndownloadRequestUrl = baseUrl\\ndownloadRequestPayload = '{\\\"format\\\":\\\"' + fileFormat + '\\\",\\\"surveyId\\\":\\\"' + surveyId + '\\\"}'\\ndownloadRequestResponse = requests.request(\\\"POST\\\", downloadRequestUrl, data=downloadRequestPayload, headers=headers)\\nprogressId = downloadRequestResponse.json()[\\\"result\\\"][\\\"id\\\"]\\nprint downloadRequestResponse.text\\n\\n# Step 2: Checking on Data Export Progress and waiting until export is ready\\nwhile requestCheckProgress < 100 and progressStatus is not \\\"complete\\\":\\n  requestCheckUrl = baseUrl + progressId\\n  requestCheckResponse = requests.request(\\\"GET\\\", requestCheckUrl, headers=headers)\\n  requestCheckProgress = requestCheckResponse.json()[\\\"result\\\"][\\\"percentComplete\\\"]\\n  print \\\"Download is \\\" + str(requestCheckProgress) + \\\" complete\\\"\\n\\n\\n# Step 3: Downloading file\\nrequestDownloadUrl = baseUrl + progressId + '/file'\\nrequestDownload = requests.request(\\\"GET\\\", requestDownloadUrl, headers=headers, stream=True)\\n\\n# Step 4: Unziping file\\nwith open(\\\"RequestFile.zip\\\", \\\"wb\\\") as f:\\n    for chunk in requestDownload.iter_content(chunk_size=1024):\\n      f.write(chunk)\\nzipfile.ZipFile(\\\"RequestFile.zip\\\").extractall(\\\"MyQualtricsDownload\\\")\",\n      \"language\": \"python\",\n      \"name\": \"Python 2\"\n    },\n    {\n      \"code\": \"# Python 3\\n\\nimport requests\\nimport zipfile\\nimport json\\nimport io\\n\\n# Setting user Parameters\\napiToken = \\\"MYAPITOKEN\\\"\\nsurveyId = \\\"SV_dimlWvV7hWLCJdX\\\"\\nfileFormat = \\\"csv\\\"\\ndataCenter = 'ca1'\\n\\n# Setting static parameters\\nrequestCheckProgress = 0\\nprogressStatus = \\\"in progress\\\"\\nbaseUrl = \\\"https://{0}.qualtrics.com/API/v3/responseexports/\\\".format(dataCenter)\\nheaders = {\\n    \\\"content-type\\\": \\\"application/json\\\",\\n    \\\"x-api-token\\\": apiToken,\\n    }\\n\\n# Step 1: Creating Data Export\\ndownloadRequestUrl = baseUrl\\ndownloadRequestPayload = '{\\\"format\\\":\\\"' + fileFormat + '\\\",\\\"surveyId\\\":\\\"' + surveyId + '\\\"}'\\ndownloadRequestResponse = requests.request(\\\"POST\\\", downloadRequestUrl, data=downloadRequestPayload, headers=headers)\\nprogressId = downloadRequestResponse.json()[\\\"result\\\"][\\\"id\\\"]\\nprint(downloadRequestResponse.text)\\n\\n# Step 2: Checking on Data Export Progress and waiting until export is ready\\nwhile requestCheckProgress < 100 and progressStatus is not \\\"complete\\\":\\n    requestCheckUrl = baseUrl + progressId\\n    requestCheckResponse = requests.request(\\\"GET\\\", requestCheckUrl, headers=headers)\\n    requestCheckProgress = requestCheckResponse.json()[\\\"result\\\"][\\\"percentComplete\\\"]\\n    print(\\\"Download is \\\" + str(requestCheckProgress) + \\\" complete\\\")\\n\\n# Step 3: Downloading file\\nrequestDownloadUrl = baseUrl + progressId + '/file'\\nrequestDownload = requests.request(\\\"GET\\\", requestDownloadUrl, headers=headers, stream=True)\\n\\n# Step 4: Unzipping the file\\nzipfile.ZipFile(io.BytesIO(requestDownload.content)).extractall(\\\"MyQualtricsDownload\\\")\\nprint('Complete')\",\n      \"language\": \"python\",\n      \"name\": \"Python 3\"\n    }\n  ]\n}\n[/block]\nTo create a response export you will need to send a POST request to the responseexports endpoint. You will get back an ID for the asynchronous export request.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"result\\\": {\\n    \\\"id\\\": \\\"ES_e7s2ja08o9o4df6cd7ptckmfma\\\"\\n  },\\n  \\\"meta\\\": {\\n    \\\"httpStatus\\\": \\\"200 - OK\\\"\\n  }\\n}\",\n      \"language\": \"json\",\n      \"name\": \"POST - 200 OK\"\n    }\n  ]\n}\n[/block]\nTo get the status of an export send a GET request for the responseexport you just created. When the export is complete, `percentComplete` will equal 100 and `file` will contain a URL to download the survey response file from.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"result\\\": {\\n    \\\"percentComplete\\\": 100,\\n    \\\"file\\\": \\\"https://yourdatacenterid.qualtrics.com/API/v3/responseexports/ES_e7s2ja08o9o4df6cd7ptckmfma/file\\\"\\n  },\\n  \\\"meta\\\": {\\n    \\\"httpStatus\\\": \\\"200 - OK\\\"\\n  }\\n}\",\n      \"language\": \"json\",\n      \"name\": \"GET - 200 OK\"\n    }\n  ]\n}\n[/block]\nThe resulting file will be a .zip file containing one or more data files in the specified format. The maximum number of records per data file is 1M. If the maximum number of rows of data is reached, additional data files will be included in the .zip file in the format: <surveyname>_<filenum>.<fileExtension>\n[block:api-header]\n{\n  \"title\": \"Getting Survey Responses with Java\"\n}\n[/block]\n\nThe following Java snippet demonstrates how to download responses for the specified survey. Version 1.8 of the Java Development Kit (JDK) was used.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"import com.fasterxml.jackson.databind.JsonNode;\\nimport com.fasterxml.jackson.databind.ObjectMapper;\\nimport org.apache.commons.io.IOUtils;\\nimport org.apache.http.HttpResponse;\\nimport org.apache.http.client.HttpClient;\\nimport org.apache.http.entity.StringEntity;\\nimport org.apache.http.client.methods.HttpGet;\\nimport org.apache.http.client.methods.HttpPost;\\nimport org.apache.http.client.methods.HttpRequestBase;\\nimport org.apache.http.client.utils.URIBuilder;\\nimport org.apache.http.impl.client.HttpClientBuilder;\\nimport org.apache.http.util.EntityUtils;\\n\\n\\nimport java.io.FileOutputStream;\\nimport java.io.IOException;\\nimport java.net.URI;\\nimport java.net.URISyntaxException;\\nimport java.util.zip.ZipEntry;\\nimport java.util.zip.ZipInputStream;\\n\\npublic class ExportClient\\n{\\n  private static final String SURVEY_ID = \\\"SV_123456\\\";\\n  private static final String API_TOKEN = System.getenv(\\\"Q_API_TOKEN\\\");\\n  private static final String DATA_CENTER = System.getenv(\\\"Q_DATA_CENTER\\\");\\n  \\n  private static HttpClient httpClient;\\n  private static ObjectMapper mapper;\\n\\n \\n  public static void main(String[] args) throws IOException, URISyntaxException, InterruptedException\\n  {\\n    httpClient = HttpClientBuilder.create().build();\\n    mapper = new ObjectMapper();\\n\\n    // Step 1: Start the export\\n      URI uri = new URIBuilder()\\n        .setScheme(\\\"https\\\")\\n        .setHost(String.format(\\\"%s.qualtrics.com\\\", DATA_CENTER))\\n        .setPath(\\\"/API/v3/responseexports\\\")\\n        .build();\\n\\n    HttpPost post = new HttpPost(uri);\\n    post.setHeader(\\\"X-API-TOKEN\\\", API_TOKEN);\\n    post.setHeader(\\\"Content-Type\\\", \\\"application/json\\\");\\n    \\n    StringEntity body = new StringEntity(String.format(\\\"{ \\\\\\\"format\\\\\\\": \\\\\\\"csv\\\\\\\", \\\\\\\"surveyId\\\\\\\": \\\\\\\"%s\\\\\\\" }\\\", SURVEY_ID));\\n    post.setEntity(body);\\n    JsonNode responseJson = sendResponseEngineRequest(post);\\n    String exportId = responseJson.get(\\\"result\\\").get(\\\"id\\\").asText();\\n    URI exportStatusUrl = new URIBuilder()\\n        .setScheme(\\\"https\\\")\\n        .setHost(String.format(\\\"%s.qualtrics.com\\\", DATA_CENTER))\\n        .setPath(\\\"/API/v3/responseexports/\\\" + exportId)\\n        .build();\\n\\n    // Step 2: Wait for the export to complete\\n    String fileUrl;\\n    while (true)\\n    {\\n      HttpGet statusGet = new HttpGet(exportStatusUrl);\\n      statusGet.setHeader(\\\"X-API-TOKEN\\\", API_TOKEN);\\n      JsonNode statusJson = sendResponseEngineRequest(statusGet);\\n      if (statusJson.get(\\\"result\\\").get(\\\"percentComplete\\\").asInt() == 100)\\n      {\\n        fileUrl = statusJson.get(\\\"result\\\").get(\\\"file\\\").asText();\\n        break;\\n      }\\n      Thread.sleep(2000);\\n    }\\n\\n    // Step 3: Download the exported file\\n    HttpGet statusGet = new HttpGet(fileUrl);\\n    statusGet.setHeader(\\\"X-API-TOKEN\\\", API_TOKEN);\\n    HttpResponse response = httpClient.execute(statusGet);\\n\\n    // Step 4: Extract exported file\\n    ZipInputStream zs = new ZipInputStream(response.getEntity().getContent());\\n    ZipEntry entry;\\n    while ((entry = zs.getNextEntry()) != null)\\n    {\\n      FileOutputStream out = new FileOutputStream(\\\"./\\\" + entry.getName());\\n      IOUtils.copy(zs, out);\\n      out.close();\\n    }\\n  }\\n\\n  private static JsonNode sendResponseEngineRequest(HttpRequestBase httpRequest) throws IOException\\n  {\\n    HttpResponse response = httpClient.execute(httpRequest);\\n    String body = EntityUtils.toString(response.getEntity());\\n    return mapper.readTree(body);\\n  }\\n}\\n\",\n      \"language\": \"java\",\n      \"name\": \"ExportClient\"\n    }\n  ]\n}\n[/block]\nReplace the values of `SURVEY_ID`, `API_TOKEN`, and `DATA_CENTER` with the correct values for your account. See [Finding Your Qualtrics IDs](doc:finding-qualtrics-ids) for more information.\n\nThe following .jar files are necessary:\n\n- [commons-io-2.5.jar](https://mvnrepository.com/artifact/commons-io/commons-io/2.5)\n- [commons-logging-1.2.jar](https://commons.apache.org/proper/commons-logging/download_logging.cgi)\n- [httpcore-4.4.6.jar](https://hc.apache.org/downloads.cgi)\n- [org.apache.httpcomponents.httpclient_4.5.3.jar](https://hc.apache.org/downloads.cgi)\n- [jackson-annotations-2.9.1.jar](http://central.maven.org/maven2/com/fasterxml/jackson/core/jackson-annotations/2.9.1/)\n- [jackson-core-2.9.1.jar](http://central.maven.org/maven2/com/fasterxml/jackson/core/jackson-core/2.9.1/)\n- [jackson-databind-2.9.1.jar](http://central.maven.org/maven2/com/fasterxml/jackson/core/jackson-databind/2.9.1/)\n\nCopy the .jar files to a folder. In this example, the .jar files are in a folder on the desktop called **Libraries**. The source file (**ExportClient.java**) is in another folder on the desktop. Both `javac` and `java` need to be in your path.\n\nOn Linux and Mac, compile the Java snippet (saved as **ExportClient.java**) using the following command line:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"javac -extdirs ~/Desktop/Libraries/ ExportClient.java \",\n      \"language\": \"shell\",\n      \"name\": \"Compile\"\n    }\n  ]\n}\n[/block]\nRun the generated .class file by typing the following:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"java -cp \\\"../Libraries/*:.\\\" ExportClient\",\n      \"language\": \"shell\",\n      \"name\": \"Run\"\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Wildcards in classpath\",\n  \"body\": \"Do not use \\\\*.jar (or similar) in the classpath (-cp) because the wildcard character has a special interpretation in Java 6 and above. It expands to the .jar files in the specified folder.\"\n}\n[/block]\n\nWhen the program completes, the downloaded survey results will be available in the same folder as the program.\n\n[block:api-header]\n{\n  \"title\": \"Getting Survey Responses with R\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Support for R package: qualtRics\",\n  \"body\": \"The Qualtrics Support team does not provide support for custom code. The **qualtRics** package is not supported by Qualtrics and any specific issues with the package itself should be directed to the [qualtRics issues](https://github.com/JasperHG90/qualtRics/issues) page.\\n\\nAny issues with the Qualtrics REST API should be directed to [Qualtrics Integrations Support team](https://www.qualtrics.com/support-center/?Product=Integrations).\"\n}\n[/block]\nThe R package **qualtRics** makes it easy to get survey responses into the statistical package R. The package allows you to get your survey responses without unzipping files or extracting information from JSON objects. This section discusses version 2.0 of the package. For more information about the package, see [qualtRics](https://github.com/JasperHG90/qualtRics).\n\nIn RStudio, you can install the package from the Tools menu, Install Packages. The package is available from CRAN.\n\nThe following sample shows how to get a data frame containing information about your surveys using the `getSurveys` function:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"require(qualtRics)\\n\\nregisterOptions(api_token=\\\"YOUR API KEY\\\", root_url=\\\"https://yourdatacenterid.qualtrics.com\\\")\\nsurveys <- getSurveys()\",\n      \"language\": \"r\",\n      \"name\": \"R\"\n    }\n  ]\n}\n[/block]\nThe `surveys` data frame contains information about all of your surveys. For example:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"                   id           name            ownerId         lastModified isActive\\n2  SV_0fHnuNimdt3R9pX     Newer Name UR_123456789012345 2017-05-25T22:15:22Z     TRUE\\n21 SV_0zSlknmZXhJ4BAx    TestFromURL UR_123456789012345 2017-05-24T20:26:13Z    FALSE\\n3  SV_0x1XmEv9pCD2asB           Test UR_123456789012345 2017-05-24T16:07:23Z    FALSE\\n4  SV_3V7MgGcbG4YA3NH  Test Survey 2 UR_123456789012345 2017-05-24T21:10:21Z    FALSE\\n5  SV_4SRzY5wAmUZSzkx   TestFromUrl2 UR_123456789012345 2017-05-24T21:07:15Z    FALSE\\n6  SV_4VxakCgq7b1eU8B   TestFromUrl2 UR_123456789012345 2017-05-24T21:06:42Z    FALSE\\n7  SV_5Ae4nEvcCXslEmR         Simple UR_123456789012345 2017-05-25T20:52:09Z    FALSE\\n8  SV_5d16l4JrllvxLXf Second Project UR_123456789012345 2017-05-18T19:49:31Z    FALSE\\n9  SV_7TZNw44dHLLPRt3    TestFromURL UR_123456789012345 2017-05-24T20:27:15Z    FALSE\\n10 SV_9vTqLp3Yk8LofjL  Timezone Test UR_123456789012345 2017-06-09T19:29:58Z     TRUE\\n11 SV_eVPWQKXxLplsOdP  QuestionTypes UR_123456789012345 2017-06-05T23:01:12Z     TRUE\",\n      \"language\": \"r\",\n      \"name\": \"Survey Table in R\"\n    }\n  ]\n}\n[/block]\nYou can use the survey ID in this data frame to retrieve the responses for the survey you want. Here, for instance, is how to retrieve the responses to the \"Timezone Test\" survey (row ten, survey ID \"SV_9vTqLp3Yk8LofjL\"):\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"timezoneSurvey <- getSurvey(surveys$id[10])\",\n      \"language\": \"r\"\n    }\n  ]\n}\n[/block]\nThe `timezoneSurvey` data frame contains the survey responses. The following shows the column names for the timezoneSurvey:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"names(timezoneSurvey)\\n [1] \\\"ResponseID\\\"            \\\"ResponseSet\\\"           \\\"IPAddress\\\"            \\n [4] \\\"StartDate\\\"             \\\"EndDate\\\"               \\\"RecipientLastName\\\"    \\n [7] \\\"RecipientFirstName\\\"    \\\"RecipientEmail\\\"        \\\"ExternalDataReference\\\"\\n[10] \\\"Finished\\\"              \\\"Status\\\"                \\\"Q1\\\"                   \\n[13] \\\"LocationLatitude\\\"      \\\"LocationLongitude\\\"     \\\"LocationAccuracy\\\"     \",\n      \"language\": \"r\",\n      \"name\": \"Column Names in a Sample Response File\"\n    }\n  ]\n}\n[/block]","excerpt":"How to get responses to your surveys.","slug":"response-exports","type":"basic","title":"Getting Survey Responses"}

Getting Survey Responses

How to get responses to your surveys.

This document describes how you can get your users' responses to your surveys. The first and second sections explain how to get responses using Python and Java, and the last section shows how to use the **qualtRics** package to get survey responses with R. [block:api-header] { "title": "Getting Survey Responses with Python" } [/block] The process of getting survey responses requires four steps: 1. Request the responses with the [Create Response Export](doc:create-response-export) API. Qualtrics will create a .zip file that contains the requested responses. You can use various filtering options to this request to retrieve a subset of the responses to speed up processing. See step 1 in the samples below. 2. Request the export status using the [Get Response Export Progress](doc:get-response-export-progress) API. The `result` object will contain a `percentComplete` value. Keep looping until `percentComplete` is 100. (You might want to sleep a few seconds between requests.) 3. Once the export progress is 100, use the `file` string in the `result` object from Get Response Export Progress. (See the third code sample below for an example.) Make a `GET` request to this URL to retrieve your response file, which will be a zipped file containing the responses. The samples below show an alternative method by creating the URL from the id returned in step 1. 4. Unzip the file to find the survey responses in the format you requested (csv, csv2013, xml, json, or spss). If the file exceeds the static limits on file size, your responses will be split into several files and included in the .zip file. [block:code] { "codes": [ { "code": "# For Python 2.7.10\nimport requests\nimport zipfile\ntry: import simplejson as json\nexcept ImportError: import json\n\n# Setting user Parameters\napiToken = \"MYAPITOKEN\"\nsurveyId = \"SV_dimlWvV7hWLCJdX\"\nfileFormat = \"csv\"\ndataCenter = 'ca1'\n\n# Setting static parameters\nrequestCheckProgress = 0\nprogressStatus = \"in progress\"\nbaseUrl = \"https://{0}.qualtrics.com/API/v3/responseexports/\".format(dataCenter)\nheaders = {\n \"content-type\": \"application/json\",\n \"x-api-token\": apiToken,\n }\n\n# Step 1: Creating Data Export\ndownloadRequestUrl = baseUrl\ndownloadRequestPayload = '{\"format\":\"' + fileFormat + '\",\"surveyId\":\"' + surveyId + '\"}'\ndownloadRequestResponse = requests.request(\"POST\", downloadRequestUrl, data=downloadRequestPayload, headers=headers)\nprogressId = downloadRequestResponse.json()[\"result\"][\"id\"]\nprint downloadRequestResponse.text\n\n# Step 2: Checking on Data Export Progress and waiting until export is ready\nwhile requestCheckProgress < 100 and progressStatus is not \"complete\":\n requestCheckUrl = baseUrl + progressId\n requestCheckResponse = requests.request(\"GET\", requestCheckUrl, headers=headers)\n requestCheckProgress = requestCheckResponse.json()[\"result\"][\"percentComplete\"]\n print \"Download is \" + str(requestCheckProgress) + \" complete\"\n\n\n# Step 3: Downloading file\nrequestDownloadUrl = baseUrl + progressId + '/file'\nrequestDownload = requests.request(\"GET\", requestDownloadUrl, headers=headers, stream=True)\n\n# Step 4: Unziping file\nwith open(\"RequestFile.zip\", \"wb\") as f:\n for chunk in requestDownload.iter_content(chunk_size=1024):\n f.write(chunk)\nzipfile.ZipFile(\"RequestFile.zip\").extractall(\"MyQualtricsDownload\")", "language": "python", "name": "Python 2" }, { "code": "# Python 3\n\nimport requests\nimport zipfile\nimport json\nimport io\n\n# Setting user Parameters\napiToken = \"MYAPITOKEN\"\nsurveyId = \"SV_dimlWvV7hWLCJdX\"\nfileFormat = \"csv\"\ndataCenter = 'ca1'\n\n# Setting static parameters\nrequestCheckProgress = 0\nprogressStatus = \"in progress\"\nbaseUrl = \"https://{0}.qualtrics.com/API/v3/responseexports/\".format(dataCenter)\nheaders = {\n \"content-type\": \"application/json\",\n \"x-api-token\": apiToken,\n }\n\n# Step 1: Creating Data Export\ndownloadRequestUrl = baseUrl\ndownloadRequestPayload = '{\"format\":\"' + fileFormat + '\",\"surveyId\":\"' + surveyId + '\"}'\ndownloadRequestResponse = requests.request(\"POST\", downloadRequestUrl, data=downloadRequestPayload, headers=headers)\nprogressId = downloadRequestResponse.json()[\"result\"][\"id\"]\nprint(downloadRequestResponse.text)\n\n# Step 2: Checking on Data Export Progress and waiting until export is ready\nwhile requestCheckProgress < 100 and progressStatus is not \"complete\":\n requestCheckUrl = baseUrl + progressId\n requestCheckResponse = requests.request(\"GET\", requestCheckUrl, headers=headers)\n requestCheckProgress = requestCheckResponse.json()[\"result\"][\"percentComplete\"]\n print(\"Download is \" + str(requestCheckProgress) + \" complete\")\n\n# Step 3: Downloading file\nrequestDownloadUrl = baseUrl + progressId + '/file'\nrequestDownload = requests.request(\"GET\", requestDownloadUrl, headers=headers, stream=True)\n\n# Step 4: Unzipping the file\nzipfile.ZipFile(io.BytesIO(requestDownload.content)).extractall(\"MyQualtricsDownload\")\nprint('Complete')", "language": "python", "name": "Python 3" } ] } [/block] To create a response export you will need to send a POST request to the responseexports endpoint. You will get back an ID for the asynchronous export request. [block:code] { "codes": [ { "code": "{\n \"result\": {\n \"id\": \"ES_e7s2ja08o9o4df6cd7ptckmfma\"\n },\n \"meta\": {\n \"httpStatus\": \"200 - OK\"\n }\n}", "language": "json", "name": "POST - 200 OK" } ] } [/block] To get the status of an export send a GET request for the responseexport you just created. When the export is complete, `percentComplete` will equal 100 and `file` will contain a URL to download the survey response file from. [block:code] { "codes": [ { "code": "{\n \"result\": {\n \"percentComplete\": 100,\n \"file\": \"https://yourdatacenterid.qualtrics.com/API/v3/responseexports/ES_e7s2ja08o9o4df6cd7ptckmfma/file\"\n },\n \"meta\": {\n \"httpStatus\": \"200 - OK\"\n }\n}", "language": "json", "name": "GET - 200 OK" } ] } [/block] The resulting file will be a .zip file containing one or more data files in the specified format. The maximum number of records per data file is 1M. If the maximum number of rows of data is reached, additional data files will be included in the .zip file in the format: <surveyname>_<filenum>.<fileExtension> [block:api-header] { "title": "Getting Survey Responses with Java" } [/block] The following Java snippet demonstrates how to download responses for the specified survey. Version 1.8 of the Java Development Kit (JDK) was used. [block:code] { "codes": [ { "code": "import com.fasterxml.jackson.databind.JsonNode;\nimport com.fasterxml.jackson.databind.ObjectMapper;\nimport org.apache.commons.io.IOUtils;\nimport org.apache.http.HttpResponse;\nimport org.apache.http.client.HttpClient;\nimport org.apache.http.entity.StringEntity;\nimport org.apache.http.client.methods.HttpGet;\nimport org.apache.http.client.methods.HttpPost;\nimport org.apache.http.client.methods.HttpRequestBase;\nimport org.apache.http.client.utils.URIBuilder;\nimport org.apache.http.impl.client.HttpClientBuilder;\nimport org.apache.http.util.EntityUtils;\n\n\nimport java.io.FileOutputStream;\nimport java.io.IOException;\nimport java.net.URI;\nimport java.net.URISyntaxException;\nimport java.util.zip.ZipEntry;\nimport java.util.zip.ZipInputStream;\n\npublic class ExportClient\n{\n private static final String SURVEY_ID = \"SV_123456\";\n private static final String API_TOKEN = System.getenv(\"Q_API_TOKEN\");\n private static final String DATA_CENTER = System.getenv(\"Q_DATA_CENTER\");\n \n private static HttpClient httpClient;\n private static ObjectMapper mapper;\n\n \n public static void main(String[] args) throws IOException, URISyntaxException, InterruptedException\n {\n httpClient = HttpClientBuilder.create().build();\n mapper = new ObjectMapper();\n\n // Step 1: Start the export\n URI uri = new URIBuilder()\n .setScheme(\"https\")\n .setHost(String.format(\"%s.qualtrics.com\", DATA_CENTER))\n .setPath(\"/API/v3/responseexports\")\n .build();\n\n HttpPost post = new HttpPost(uri);\n post.setHeader(\"X-API-TOKEN\", API_TOKEN);\n post.setHeader(\"Content-Type\", \"application/json\");\n \n StringEntity body = new StringEntity(String.format(\"{ \\\"format\\\": \\\"csv\\\", \\\"surveyId\\\": \\\"%s\\\" }\", SURVEY_ID));\n post.setEntity(body);\n JsonNode responseJson = sendResponseEngineRequest(post);\n String exportId = responseJson.get(\"result\").get(\"id\").asText();\n URI exportStatusUrl = new URIBuilder()\n .setScheme(\"https\")\n .setHost(String.format(\"%s.qualtrics.com\", DATA_CENTER))\n .setPath(\"/API/v3/responseexports/\" + exportId)\n .build();\n\n // Step 2: Wait for the export to complete\n String fileUrl;\n while (true)\n {\n HttpGet statusGet = new HttpGet(exportStatusUrl);\n statusGet.setHeader(\"X-API-TOKEN\", API_TOKEN);\n JsonNode statusJson = sendResponseEngineRequest(statusGet);\n if (statusJson.get(\"result\").get(\"percentComplete\").asInt() == 100)\n {\n fileUrl = statusJson.get(\"result\").get(\"file\").asText();\n break;\n }\n Thread.sleep(2000);\n }\n\n // Step 3: Download the exported file\n HttpGet statusGet = new HttpGet(fileUrl);\n statusGet.setHeader(\"X-API-TOKEN\", API_TOKEN);\n HttpResponse response = httpClient.execute(statusGet);\n\n // Step 4: Extract exported file\n ZipInputStream zs = new ZipInputStream(response.getEntity().getContent());\n ZipEntry entry;\n while ((entry = zs.getNextEntry()) != null)\n {\n FileOutputStream out = new FileOutputStream(\"./\" + entry.getName());\n IOUtils.copy(zs, out);\n out.close();\n }\n }\n\n private static JsonNode sendResponseEngineRequest(HttpRequestBase httpRequest) throws IOException\n {\n HttpResponse response = httpClient.execute(httpRequest);\n String body = EntityUtils.toString(response.getEntity());\n return mapper.readTree(body);\n }\n}\n", "language": "java", "name": "ExportClient" } ] } [/block] Replace the values of `SURVEY_ID`, `API_TOKEN`, and `DATA_CENTER` with the correct values for your account. See [Finding Your Qualtrics IDs](doc:finding-qualtrics-ids) for more information. The following .jar files are necessary: - [commons-io-2.5.jar](https://mvnrepository.com/artifact/commons-io/commons-io/2.5) - [commons-logging-1.2.jar](https://commons.apache.org/proper/commons-logging/download_logging.cgi) - [httpcore-4.4.6.jar](https://hc.apache.org/downloads.cgi) - [org.apache.httpcomponents.httpclient_4.5.3.jar](https://hc.apache.org/downloads.cgi) - [jackson-annotations-2.9.1.jar](http://central.maven.org/maven2/com/fasterxml/jackson/core/jackson-annotations/2.9.1/) - [jackson-core-2.9.1.jar](http://central.maven.org/maven2/com/fasterxml/jackson/core/jackson-core/2.9.1/) - [jackson-databind-2.9.1.jar](http://central.maven.org/maven2/com/fasterxml/jackson/core/jackson-databind/2.9.1/) Copy the .jar files to a folder. In this example, the .jar files are in a folder on the desktop called **Libraries**. The source file (**ExportClient.java**) is in another folder on the desktop. Both `javac` and `java` need to be in your path. On Linux and Mac, compile the Java snippet (saved as **ExportClient.java**) using the following command line: [block:code] { "codes": [ { "code": "javac -extdirs ~/Desktop/Libraries/ ExportClient.java ", "language": "shell", "name": "Compile" } ] } [/block] Run the generated .class file by typing the following: [block:code] { "codes": [ { "code": "java -cp \"../Libraries/*:.\" ExportClient", "language": "shell", "name": "Run" } ] } [/block] [block:callout] { "type": "info", "title": "Wildcards in classpath", "body": "Do not use \\*.jar (or similar) in the classpath (-cp) because the wildcard character has a special interpretation in Java 6 and above. It expands to the .jar files in the specified folder." } [/block] When the program completes, the downloaded survey results will be available in the same folder as the program. [block:api-header] { "title": "Getting Survey Responses with R" } [/block] [block:callout] { "type": "warning", "title": "Support for R package: qualtRics", "body": "The Qualtrics Support team does not provide support for custom code. The **qualtRics** package is not supported by Qualtrics and any specific issues with the package itself should be directed to the [qualtRics issues](https://github.com/JasperHG90/qualtRics/issues) page.\n\nAny issues with the Qualtrics REST API should be directed to [Qualtrics Integrations Support team](https://www.qualtrics.com/support-center/?Product=Integrations)." } [/block] The R package **qualtRics** makes it easy to get survey responses into the statistical package R. The package allows you to get your survey responses without unzipping files or extracting information from JSON objects. This section discusses version 2.0 of the package. For more information about the package, see [qualtRics](https://github.com/JasperHG90/qualtRics). In RStudio, you can install the package from the Tools menu, Install Packages. The package is available from CRAN. The following sample shows how to get a data frame containing information about your surveys using the `getSurveys` function: [block:code] { "codes": [ { "code": "require(qualtRics)\n\nregisterOptions(api_token=\"YOUR API KEY\", root_url=\"https://yourdatacenterid.qualtrics.com\")\nsurveys <- getSurveys()", "language": "r", "name": "R" } ] } [/block] The `surveys` data frame contains information about all of your surveys. For example: [block:code] { "codes": [ { "code": " id name ownerId lastModified isActive\n2 SV_0fHnuNimdt3R9pX Newer Name UR_123456789012345 2017-05-25T22:15:22Z TRUE\n21 SV_0zSlknmZXhJ4BAx TestFromURL UR_123456789012345 2017-05-24T20:26:13Z FALSE\n3 SV_0x1XmEv9pCD2asB Test UR_123456789012345 2017-05-24T16:07:23Z FALSE\n4 SV_3V7MgGcbG4YA3NH Test Survey 2 UR_123456789012345 2017-05-24T21:10:21Z FALSE\n5 SV_4SRzY5wAmUZSzkx TestFromUrl2 UR_123456789012345 2017-05-24T21:07:15Z FALSE\n6 SV_4VxakCgq7b1eU8B TestFromUrl2 UR_123456789012345 2017-05-24T21:06:42Z FALSE\n7 SV_5Ae4nEvcCXslEmR Simple UR_123456789012345 2017-05-25T20:52:09Z FALSE\n8 SV_5d16l4JrllvxLXf Second Project UR_123456789012345 2017-05-18T19:49:31Z FALSE\n9 SV_7TZNw44dHLLPRt3 TestFromURL UR_123456789012345 2017-05-24T20:27:15Z FALSE\n10 SV_9vTqLp3Yk8LofjL Timezone Test UR_123456789012345 2017-06-09T19:29:58Z TRUE\n11 SV_eVPWQKXxLplsOdP QuestionTypes UR_123456789012345 2017-06-05T23:01:12Z TRUE", "language": "r", "name": "Survey Table in R" } ] } [/block] You can use the survey ID in this data frame to retrieve the responses for the survey you want. Here, for instance, is how to retrieve the responses to the "Timezone Test" survey (row ten, survey ID "SV_9vTqLp3Yk8LofjL"): [block:code] { "codes": [ { "code": "timezoneSurvey <- getSurvey(surveys$id[10])", "language": "r" } ] } [/block] The `timezoneSurvey` data frame contains the survey responses. The following shows the column names for the timezoneSurvey: [block:code] { "codes": [ { "code": "names(timezoneSurvey)\n [1] \"ResponseID\" \"ResponseSet\" \"IPAddress\" \n [4] \"StartDate\" \"EndDate\" \"RecipientLastName\" \n [7] \"RecipientFirstName\" \"RecipientEmail\" \"ExternalDataReference\"\n[10] \"Finished\" \"Status\" \"Q1\" \n[13] \"LocationLatitude\" \"LocationLongitude\" \"LocationAccuracy\" ", "language": "r", "name": "Column Names in a Sample Response File" } ] } [/block]