Survey Data API 5.7
1: Overview
The Data API allows extraction of all survey data on incremental basis, which means that clients can obtain only new or changed data on specific intervals. The Data API consists of a set of callable methods and a single endpoint. To perform an operation you need to send a request to the endpoint specifying a method and some arguments, and will receive a formatted response.
All API calls are POST request with a method defined in the URL of the request. All parameters are expected to be a JSON encoded object in a single POST variable named "data".
The data API can only be accessed from pre-authorized client IP addresses and all traffic must be transmitted over secure SSL connection. Please contact your account manager or email customersupport@kinesissurvey.com if you would like to use the API.
All API related technical question should be sent to apisupport@kinesissurvey.com.
Example API Request URL:
https://web1.kinesissurvey.com/yourinstallation/api.pro?method=data.auth.connect
Example POST "data"
{ "username":"myaccount", "password":"shhh,secret!" }
For more information on JSON in general, see http://www.json.org/
For PHP JSON information, see http://www.php.net/manual/en/book.json.php
2: Errors
All errors in the API are returned in the following formation:
{
"success": false,
"error": "Session string is invalid",
"errno": 20101
}
NOTE: Not all errors have unique errno.
3: Methods
3.1: data.auth.connect
Establish a connection with the server using a Kinesis Survey account that has data export permissions.
| Name | Type | Required | Description |
|---|---|---|---|
| username | string | yes | A survey account with permissions to export data. |
| password | string | yes | The password for the corresponding survey account. |
Posted JSON in "data" field:
{
"username":"myaccount",
"password":"s3cr3tp4ssw0rd!"
}
JSON response on success:
{
"success":true,
"seskey":"ad4fabc390cd776af2cdf2a7da72e2e2"
}
3.2: data.auth.disconnect
Disconnect from the server.
| Name | Type | Required | Description |
|---|---|---|---|
| seskey | string | yes | The unique key that is used to identify an authorized user. |
Posted JSON in "data" field:
{
"seskey":"ad4fabc390cd776af2cdf2a7da72e2e2"
}
JSON response on success:
{
"success":true
}
3.3: data.job.create
Create a new data export job. Jobs are used to track incremental data exports from the survey database. This means that that the system will remember which job is at which point in the survey data. This avoids extracting and transferring data that has already been transferred from the survey to the client's system!
| Please make sure you understand the correct use of jobs to avoid overloading servers! |
| Name | Type | Required | Description |
|---|---|---|---|
| seskey | string | yes | The unique key that is used to identify an authorized user. |
| surveyid | int | yes | The surveyid that you wish to create the job for. |
| status | string[] | yes | The status of surveys you wish to export, passed as an array of string. Valid values are: dropout, profile, quota and completed. |
| uniqueids | int[] | no | The unique ids of questions in the survey that you wish to export, passed as an array of int. If nothing is supplied then all questions are included. |
Posted JSON in "data" field:
{
"seskey":"ad4fabc390cd776af2cdf2a7da72e2e2",
"surveyid":1,
"status":["dropout","quota"],
"uniqueids":[1,2,3]
}
JSON response on success:
{
"success":true,
"jobid":1
}
3.4: data.job.set
Set the job id that you wish to make use of for the export. Jobs are used to track incremental data exports from the survey database. This means that that the system will remember which job is at which point in the survey data. This avoids extracting and transferring data that has already been transferred from the survey to the client's system!
| Please make sure you understand the correct use of jobs to avoid overloading servers! |
| Name | Type | Required | Description |
|---|---|---|---|
| seskey | string | yes | The unique key that is used to identify an authorized user. |
| jobid | int | yes | The job id that you wish to use. |
Posted JSON in "data" field:
{
"seskey":"ad4fabc390cd776af2cdf2a7da72e2e2",
"jobid":1
}
JSON response on success:
{
"success":true
}
3.5: data.questions.get
Get the definition of all the questions, or the specific question by unique id.
| Name | Type | Required | Description |
|---|---|---|---|
| seskey | string | yes | The unique key that is used to identify an authorized user. |
| surveyid | int | yes | The surveyid that you wish to get the questions for. |
Posted JSON in "data" field:
{
"seskey":"ad4fabc390cd776af2cdf2a7da72e2e2",
"surveyid":1,
"uniqueid":1
}
JSON response on success:
{
"success":true,
"questions":{
"<uniqueid>": {<view question types>}
}
}
3.6: data.questions.done
Mark this question as done, so that the next time you request data it will be from the next question.
| Name | Type | Required | Description |
|---|---|---|---|
| seskey | string | yes | The unique key that is used to identify an authorized user. |
| uniqueid | int | yes | The question unique id that you wish to mark done. |
Posted JSON in "data" field:
{
"seskey":"ad4fabc390cd776af2cdf2a7da72e2e2",
"uniqueid":1
}
JSON response on success:
{
"success":true
}
3.7: data.questions.updateChecksum
Updates the checksum for the given question unique id. In effect, this clears any errors that you would receive for the question choices changing.
| Name | Type | Required | Description |
|---|---|---|---|
| seskey | string | yes | The unique key that is used to identify an authorized user. |
| jobid | int | yes | The job id that you wish to reset the checksum in. |
| uniqueid | int | yes | The question unique id that you wish to reset the checksum for. |
Posted JSON in "data" field:
{
"seskey":"ad4fabc390cd776af2cdf2a7da72e2e2",
"surveyid":1,
"uniqueid":1
}
JSON response on success:
{
"success":true,
"checksum":"912ec803b2ce49e4a541068d495ab570"
}
3.8: data.responses.get
Get the responses for the currently active question for all marked sessions.
| Name | Type | Required | Description |
|---|---|---|---|
| seskey | string | yes | The unique key that is used to identify an authorized user. |
Posted JSON in "data" field:
{
"seskey":"ad4fabc390cd776af2cdf2a7da72e2e2"
}
JSON response on success:
{
"success":true,
"responses": {
"<sessionid>" : "<view question responses>"
}
}
3.9: data.responses.hasNew
Checks if there are any new responses available for download.
| Name | Type | Required | Description |
|---|---|---|---|
| seskey | string | yes | The unique key that is used to identify an authorized user. |
Posted JSON in "data" field:
{
"seskey":"ad4fabc390cd776af2cdf2a7da72e2e2"
}
JSON response on success:
{
"success":true,
"hasnew":true
}
3.10: data.sessions.start
Marks the next available 10k records for download.
| Name | Type | Required | Description |
|---|---|---|---|
| seskey | string | yes | The unique key that is used to identify an authorized user. |
Posted JSON in "data" field:
{
"seskey":"ad4fabc390cd776af2cdf2a7da72e2e2"
}
JSON response on success:
{
"success":true
}
3.11: data.sessions.done
Marks the previous set of sessions that were marked by data.sessions.start as downloaded.
| Name | Type | Required | Description |
|---|---|---|---|
| seskey | string | yes | The unique key that is used to identify an authorized user. |
Posted JSON in "data" field:
{
"seskey":"ad4fabc390cd776af2cdf2a7da72e2e2"
}
JSON response on success:
{
"success":true
}
3.12: data.sessions.metaData
Returns all the system data that is collected for the current marked sessions.
| Name | Type | Required | Description |
|---|---|---|---|
| seskey | string | yes | The unique key that is used to identify an authorized user. |
Posted JSON in "data" field:
{
"seskey":"ad4fabc390cd776af2cdf2a7da72e2e2"
}
JSON response on success:
{
"success": true,
"records": {
"1": {
"sessionid": "1",
"agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.7; rv:8.0.1) Gecko/20100101 Firefox/8.0.1",
"testrun": "no",
"mobile": "no",
"request": "/tproject/survey/5.3.0/html.pro?ID=163",
"pcid": "",
"preferred_markup": null,
"markup": "html",
"ipaddress": "192.168.0.184",
"status": "completed",
"referer": "http://web4.kinesissurvey.com/tproject/survey/5.3.0/index2.pro?showlinks=yes",
"surveytime": "00:06:37",
"identifier": null,
"email": null,
"login": null,
"lastseen": "2011-12-21 14:52:37",
"created": "2011-12-21 14:27:24",
"expires": "2011-12-21 14:52:37"
}
}
}
3.13: data.surveys.get
Get all the available surveys to export data from.
| Name | Type | Required | Description |
|---|---|---|---|
| seskey | string | yes | The unique key that is used to identify an authorized user. |
Posted JSON in "data" field:
{
"seskey":"ad4fabc390cd776af2cdf2a7da72e2e2"
}
JSON response on success:
{
"success": true,
"surveys": {
"163": {
"sid": 163,
"name": "Question Templates",
"jobcode": null,
"theme": "Default",
"datapointcount": 11,
"completecount": 1,
"quotacount": 0,
"profilecount": 0,
"dropoutcount": 1,
"active": "yes",
"skeleton": "desktop",
"createdby": "Thomas Garvey",
"modified": "2011-12-22 16:59:00",
"created": "2011-12-21 14:21:52"
}
}
}
4: Question Types
4.1: Radio
{
"uniqueid": 1,
"label": "QRadioLabel",
"type": "radio",
"text": "This is the question text.",
"choices": [
{
"choiceid": 1,
"dataid": 1,
"cond": "$Q1==1",
"text": "Choice 1",
"exportValue": null
},
{
"choiceid": 2,
"dataid": 2,
"cond": null,
"text": "Choice 2",
"exportValue": null
},
{
"choiceid": 3,
"dataid": 3,
"cond": null,
"text": "Choice 3",
"exportValue": null
},
{
"choiceid": 4,
"dataid": 4,
"cond": null,
"text": "Other",
"exportValue": null
}
],
"others": [
{
"parent": 4,
"dataid": 5,
"cond": "",
"label": "QRadioLabel_o4"
}
],
"checksum": "6d4ea4053abafd21d4b558a97962a73d"
}
4.2: Checkbox
{
"uniqueid": 2,
"label": "QCheckboxLabel",
"type": "checkbox",
"text": "This is the question text.",
"choices": [
{
"choiceid": 1,
"dataid": 1,
"cond": "$Q1==1",
"text": "Choice 1",
"exportValue": null
},
{
"choiceid": 2,
"dataid": 2,
"cond": null,
"text": "Choice 2",
"exportValue": null
},
{
"choiceid": 3,
"dataid": 3,
"cond": null,
"text": "Choice 3",
"exportValue": null
},
{
"choiceid": 4,
"dataid": 4,
"cond": null,
"text": "Other",
"exportValue": null
}
],
"others": [
{
"parent": 4,
"dataid": 5,
"cond": "",
"label": "QCheckboxLabel_o4"
}
],
"checksum": "3d952027ab6bc325bfd326901e075fc7"
}
4.3: Pulldown
{
"uniqueid": 3,
"label": "QPulldownLabel",
"type": "pulldown",
"text": "This is the question text.",
"choices": [
{
"choiceid": 1,
"dataid": 1,
"cond": "$Q1==1",
"text": "Choice 1",
"exportValue": null
},
{
"choiceid": 2,
"dataid": 2,
"cond": null,
"text": "Choice 2",
"exportValue": null
},
{
"choiceid": 3,
"dataid": 3,
"cond": null,
"text": "Choice 3",
"exportValue": null
}
],
"checksum": "07660ead91bcfd10f57f742facb82133"
}
4.4: Text
{
"uniqueid": 4,
"label": "QTextLabel",
"type": "text",
"text": "This is the question text.",
"checksum": "3813dfdf7a51963212e9a9150d2a9153"
}
4.5: TextArea
{
"uniqueid": 5,
"label": "QTextAreaLabel",
"type": "textarea",
"text": "This is the question text.",
"checksum": "5ecf4c8576f59e54306b4bf8929a39c6"
}
4.6: Number
{
"uniqueid": 6,
"label": "QNumberLabel",
"type": "number",
"text": "This is the question text.",
"checksum": "ea57101ff34d53c379a021aad64cc486"
}
4.7: Date
{
"uniqueid": 8,
"label": "QDateLabel",
"type": "date",
"text": "This is the question text.",
"checksum": "3ff90b360399a1c66cd7353ca4f77342"
}
4.8: Ranking
{
"uniqueid": 9,
"label": "QRankingLabel",
"type": "ranking",
"text": "This is the question text.",
"choices": [
{
"choiceid": 1,
"dataid": 1,
"cond": "$Q1==1",
"text": "Choice 1"
},
{
"choiceid": 2,
"dataid": 2,
"cond": null,
"text": "Choice 2"
},
{
"choiceid": 3,
"dataid": 3,
"cond": null,
"text": "Choice 3"
}
],
"checksum": "0787d821118085d52abba27886f9fc45"
}
4.9: CardSort
{
"uniqueid": 10,
"label": "QCardSortLabel",
"type": "cardsort",
"text": "This is the question text.",
"choices": [
{
"choiceid": 1,
"dataid": 1,
"cond": "$Q1==1",
"text": "Choice 1"
},
{
"choiceid": 2,
"dataid": 2,
"cond": null,
"text": "Choice 2"
},
{
"choiceid": 3,
"dataid": 3,
"cond": null,
"text": "Choice 3"
}
],
"categories": [
{
"categoryid": 1,
"category": "Category 1"
},
{
"categoryid": 2,
"category": "Category 2"
},
{
"categoryid": 3,
"category": "Category 3"
}
],
"checksum": "97fbcd85148e960db68f6bc41c1e1820"
}
4.10: Slider
{
"uniqueid": 11,
"label": "QSliderLabel",
"type": "slider",
"text": "This is the question text.",
"slidertype": "single",
"minval": 0,
"maxval": 10,
"checksum": "ceb7de4ab1918d28bbb33bb66fc8e902"
}
5: Question Responses
5.1: Radio
{
"uniqueid": 1,
"label": "QRadioLabel",
"type": "radio",
"answers": {
"2": [
{
"dataid": 2
}
]
}
}
5.2: Checkbox
{
"uniqueid": 2,
"label": "QCheckboxLabel",
"type": "checkbox",
"answers": {
"2": [
{
"dataid": 1,
"answer": "unchecked"
},
{
"dataid": 2,
"answer": "checked"
},
{
"dataid": 3,
"answer": "unchecked"
}
]
}
}
5.3: Pulldown
{
"uniqueid": 3,
"label": "QPulldownLabel",
"type": "pulldown",
"answers": {
"2": [
{
"dataid": 2
}
]
}
}
5.4: Text
{
"uniqueid": 4,
"label": "QTextLabel",
"type": "text",
"answers": {
"2": {
"answer": "a"
}
}
}
5.5: TextArea
{
"uniqueid": 5,
"label": "QTextAreaLabel",
"type": "textarea",
"answers": {
"2": {
"answer": "a"
}
}
}
5.6: Number
{
"uniqueid": 6,
"label": "QNumberLabel",
"type": "number",
"answers": {
"2": {
"answer": "1.00000000"
}
}
}
5.7: Date
{
"uniqueid": 8,
"label": "QDateLabel",
"type": "date",
"answers": {
"2": {
"answer": "1901-01-01"
}
}
}
5.8: Ranking
{
"uniqueid": 9,
"label": "QRankingLabel",
"type": "ranking",
"answers": {
"2": [
{
"pickorder": 1,
"dataid": 1
},
{
"pickorder": "",
"dataid": 2
},
{
"pickorder": "",
"dataid": 3
}
]
}
}
5.9: CardSort
{
"uniqueid": 10,
"label": "QCardSortLabel",
"type": "cardsort",
"answers": {
"2": [
{
"categoryid": 1,
"dataid": 1
},
{
"categoryid": null,
"dataid": 2
},
{
"categoryid": null,
"dataid": 3
}
]
}
}
5.10: Slider
{
"uniqueid": 11,
"label": "QSliderLabel",
"type": "slider",
"answers": {
"2": {
"answermin": 0,
"answermax": 4
}
}
}
6: Example Script
export_data.php
<?php
/**
* This script is an example of something that might be ran from a cron job to
* export survey data from a survey into different text files. It is an example
* only and should not be used for production use as not every situation has
* been accounted for.
*/
// Set max script execution time.
set_time_limit(60*60);
/**
* Require SurveyDataExportClient
*/
require_once("SurveyDataExportClient.inc");
/**
* Set the job ID that you wish to use, or leave null to have a new job created.
*/
$jobID = NULL;
/**
* Set the survey ID that you wish to export.
*/
$surveyID = 5;
/**
* Create a new SurveyDataExportClient. This will be used to get all the data from
* the survey that we wish to export.
*/
$dataExport = new SurveyDataExportClient();
$dataExport->setGatewayUrl('https://www.example.com/install/api.pro');
$dataExport->connect('USERNAME', 'PASSWORD');
/**
* Get a listing of available surveys.
*/
$surveys = $dataExport->getSurveys();
file_put_contents('data/surveys.txt', var_export($surveys, true));
if (is_null($jobID))
{
$jobID = $dataExport->createJob($surveyID);
}
else
{
$dataExport->setJob($jobID);
}
echo $jobID;
$questionData = $dataExport->getQuestions($surveyID);
file_put_contents('data/questions.txt', var_export($questionData, true));
$questions = $questionData->questions;
$qtypes = array();
foreach ($questions AS $question)
{
$qtypes[$question->uniqueid] = $question->type;
}
while ($dataExport->hasNewResponses() === TRUE)
{
$dataExport->sessionStart();
$meta = $dataExport->getMetaData();
file_put_contents('data/sessions.txt', var_export($meta, true), FILE_APPEND);
while ($answers = $dataExport->getAnswers())
{
if (empty($answers))
{
break;
}
file_put_contents('data/' . $qtypes[$answers->uniqueid] . '_' . $answers->label . '.txt', var_export($answers, true), FILE_APPEND);
$dataExport->questionDone($answers->uniqueid);
}
$dataExport->sessionDone();
}
$dataExport->disconnect();
7: PHP Classes
7.1: Client.inc
<?php
/**
*
*
* @category API
* @package Tests
* @subpackage REST
* @author The Kinesis Team <support@kinesissurvey.com>
* @copyright 2003-2011 Kinesis Survey Technologies, LLC. All rights reserved.
* @version SVN: $Id$
*/
/**
* Exception to handle CURL errors, such as the file you are trying to access
* doesn't exist on the remote server.
*
* @category API
* @package Tests
* @subpackage REST
* @author The Kinesis Team <support@kinesissurvey.com>
* @copyright 2003-2011 Kinesis Survey Technologies, LLC. All rights reserved.
* @version SVN: $Id$
*/
class CurlException extends Exception
{
}
/**
* This Exception is thrown when the REST API returns a JSON encoded object
* with the success variable set to FALSE.
*
* @category API
* @package Tests
* @subpackage REST
* @author The Kinesis Team <support@kinesissurvey.com>
* @copyright 2003-2011 Kinesis Survey Technologies, LLC. All rights reserved.
* @version SVN: $Id$
*/
class RestException extends Exception
{
}
/**
* If for some reason the input given is in an unexpected format or value, this
* exception is thrown.
*
* @category API
* @package Tests
* @subpackage REST
* @author The Kinesis Team <support@kinesissurvey.com>
* @copyright 2003-2011 Kinesis Survey Technologies, LLC. All rights reserved.
* @version SVN: $Id$
*/
class InputException extends Exception
{
}
/**
*
*
* @category API
* @package Tests
* @subpackage REST
* @author The Kinesis Team <support@kinesissurvey.com>
* @copyright 2003-2011 Kinesis Survey Technologies, LLC. All rights reserved.
* @version SVN: $Id$
*/
class Client
{
/**
* The REST API gateway. It is required that the URL be SSL (https).
*
* @var string
*/
private $gatewayUrl = "";
/**
* Class construct.
*/
public function __construct()
{
}
/**
* Perform a request to the REST API and return a stdClass object
* as a response.
*
* @param string $method The method to call for the request.
* @param string $data The data that is required for the request.
*
* @return stdClass
*/
public function request($method, $data)
{
// Check that we have a gateway URL
if (empty($this->gatewayUrl))
{
throw new InputException('The gateway URL must be set before making a request.');
}
// The URL to access the API.
$postUrl = $this->gatewayUrl . '?method=' . $method;
// Add the data to our data post field.
$data = 'data=' . json_encode($data);
// Create CURL object.
$cHandle = curl_init($postUrl);
// Configure CURL to POST data.
curl_setopt($cHandle, CURLOPT_POST, TRUE);
// Configure CURL to use $data as the source of POST data.
curl_setopt($cHandle, CURLOPT_POSTFIELDS, $data);
// Configure CURL to follow any header redirects.
curl_setopt($cHandle, CURLOPT_FOLLOWLOCATION, TRUE);
// Configure CURL to not return HTTP headers.
curl_setopt($cHandle, CURLOPT_HEADER, FALSE);
// Configure CURL to return the request data.
curl_setopt($cHandle, CURLOPT_RETURNTRANSFER, TRUE);
// Configure CURL to timeout after 60 seconds.
curl_setopt($cHandle, CURLOPT_TIMEOUT, 60);
//
// Send the POST request using CURL.
$result = curl_exec($cHandle);
// Check if CURL had any problems.
if ($result === FALSE)
{
// Save error string and number.
$errMsg = curl_error($cHandle);
$errNo = curl_errno($cHandle);
// Close CURL session and free up resources.
curl_close($cHandle);
// Exit the application and display the message.
throw new CurlException($errMsg, $errNo);
}
// Close the CURL session and free all resources.
curl_close($cHandle);
// Decode our response back into a PHP object.
$result = json_decode($result);
if (is_null($result))
{
throw new RestException('Unable to decode REST response into object. Was expecting JSON response. Response: ' . $result);
}
// If the request failed, we will handle it by simply dieing with an error message.
if (isset($result->success) && $result->success === FALSE)
{
throw new RestException($result->error, $result->errno);
}
// Return any result object that we receive.
return $result;
}
/**
* This will set the gatewayURL for accessing the REST API.
*
* @param string $gatewayUrl The URL to access the REST API.
*
* @return void
*/
public function setGatewayUrl($gatewayUrl)
{
if (empty($gatewayUrl) OR $gatewayUrl == '')
{
throw new InputException('The gateway URL must be a fully qualified URL. Example: https://web1.kinesissurvey.com/mysurveyinstall/api.pro');
}
$this->gatewayUrl = $gatewayUrl;
}
/**
*
*
* @return string
*/
public function getGatewayUrl()
{
return $this->gatewayUrl;
}
}
7.2: SurveyDataExportClient.inc
<?php
/**
* Survey Data Export REST API Demo
*
* @category REST_API
* @package Kinesis_Survey
* @author The Kinesis Team <support@kinesissurvey.com>
*/
/**
* Require Client base class.
*/
require_once('Client.inc');
/**
* This PHP class makes use of the Survey Data Export REST API to pull data
* from a Kinesis Survey Install.
*
*
* @category REST_API
* @package Kinesis_Survey
* @author The Kinesis Team <support@kinesissurvey.com>
*/
class SurveyDataExportClient extends Client
{
/**
* Connect to the Survey Data Export REST API
*
* @param string $userName User account user name to login with.
* @param string $userPass User secret password.
*
* @return string
*/
public function connect($userName, $userPass)
{
// Check that we have a userName
if (empty($userName))
{
throw new InputException('The username may not be left blank.');
}
// Check that we have a userPass
if (empty($userPass))
{
throw new InputException('The password may not be left blank.');
}
// Our data object.
$data = new stdClass();
$data->username = $userName;
$data->password = $userPass;
$result = $this->request('data.auth.connect', $data);
if ($result->success === FALSE)
{
die('Login Error (' . $result->errno . '): ' . $result->error);
}
$this->sesKey = $result->seskey;
return $result->seskey;
}
/**
* Disconnect the active session.
*
* @return boolean
*/
public function disconnect()
{
// Check that we have a sesKey to send to the REST API.
if (!isset($this->sesKey) OR empty($this->sesKey))
{
throw new InputException('You must be connected with a valid session to call this method.');
}
// Our data object.
$data = new stdClass();
$data->seskey = $this->sesKey;
$result = $this->request('data.auth.disconnect', $data);
return $result->success;
}
/**
* Start a session for data export.
*
* @return boolean
*/
public function sessionStart()
{
// Check that we have a sesKey to send to the REST API.
if (!isset($this->sesKey) OR empty($this->sesKey))
{
throw new InputException('You must be connected with a valid session to call this method.');
}
// Our data object.
$data = new stdClass();
$data->seskey = $this->sesKey;
$result = $this->request('data.sessions.start', $data);
return $result->success;
}
/**
* Close a session for data export.
*
* @return boolean
*/
public function sessionDone()
{
// Check that we have a sesKey to send to the REST API.
if (!isset($this->sesKey) OR empty($this->sesKey))
{
throw new InputException('You must be connected with a valid session to call this method.');
}
// Our data object.
$data = new stdClass();
$data->seskey = $this->sesKey;
$result = $this->request('data.sessions.done', $data);
return $result->success;
}
/**
* Create a new job. This sets the questions and survey that
* will be used. If an array of question unique ID's is not provided
* then all questions will be used.
*
* @param number $surveyID Survey ID to use.
* @param string[] $status Statuses desired in job. ('dropout','profile','quota','completed')
* @param number[] $uniqueIDs Array of question unique ID's
*
* @return number The newly created job ID
*/
public function createJob($surveyID, $status = array('completed'), $uniqueIDs = NULL)
{
// Check that we have a sesKey to send to the REST API.
if (!isset($this->sesKey) OR empty($this->sesKey))
{
throw new InputException('You must be connected with a valid session to call this method.');
}
// Check that we have a proper question unique ID.
if (is_null($surveyID) OR !is_numeric($surveyID))
{
throw new InputException('The survey ID must be a numeric value.');
}
// Our data object.
$data = new stdClass();
$data->seskey = $this->sesKey;
$data->surveyid = $surveyID;
$data->status = $status;
// Check if we were given any $uniqueIDs
if (!is_null($uniqueIDs))
{
// Was it an array, or a single ID?
if (is_array($uniqueIDs))
{
// Verify all the entries.
foreach ($uniqueIDs AS $uniqueID)
{
// Check that we have a proper question unique ID.
if (is_null($uniqueID) OR !is_numeric($uniqueID))
{
throw new InputException('The question unique ID must be a numeric value.');
}
}
}
else
{
// Check that we have a proper question unique ID.
if (is_null($uniqueIDs) OR !is_numeric($uniqueIDs))
{
throw new InputException('The question unique ID must be a numeric value.');
}
$uniqueIDs = array($uniqueIDs);
}
$data->uniqueids = $uniqueIDs;
}
$result = $this->request('data.job.create', $data);
return $result->jobid;
}
/**
* Set the job that will be used for export.
*
* @param number $jobID The job ID that you wish to use.
*
* @return boolean
*/
public function setJob($jobID)
{
// Check that we have a sesKey to send to the REST API.
if (!isset($this->sesKey) OR empty($this->sesKey))
{
throw new InputException('You must be connected with a valid session to call this method.');
}
// Check that we have a proper job ID.
if (is_null($jobID) OR !is_numeric($jobID))
{
throw new InputException('The job ID must be a numeric value.');
}
// Our data object.
$data = new stdClass();
$data->seskey = $this->sesKey;
$data->jobid = $jobID;
$result = $this->request('data.job.set', $data);
return $result->success;
}
/**
* Get the questions.
*
* @param number $surveyID The survey ID that the questions should be returned from.
*
* @return stdClass[]
*/
public function getQuestions($surveyID)
{
// Check that we have a sesKey to send to the REST API.
if (!isset($this->sesKey) OR empty($this->sesKey))
{
throw new InputException('You must be connected with a valid session to call this method.');
}
// Check that we have a proper survey ID.
if (is_null($surveyID) OR !is_numeric($surveyID))
{
throw new InputException('The survey ID must be a numeric value.');
}
// Our data object.
$data = new stdClass();
$data->seskey = $this->sesKey;
$data->surveyid = $surveyID;
$result = $this->request('data.questions.get', $data);
return $result;
}
/**
* Update the checksum for a question that is giving a mis-matched checksum error.
*
* @param int $jobID The job ID that you wish to use.
* @param int $uniqueID The question unique ID that you wish to update.
*
* @return stdClass[]
*/
public function updateChecksum($jobID, $uniqueID)
{
// Check that we have a sesKey to send to the REST API.
if (!isset($this->sesKey) OR empty($this->sesKey))
{
throw new InputException('You must be connected with a valid session to call this method.');
}
// Check that we have a proper question unique ID.
if (is_null($uniqueID) OR !is_numeric($uniqueID))
{
throw new InputException('The question unique ID must be a numeric value.');
}
// Check that we have a proper job ID.
if (is_null($jobID) OR !is_numeric($jobID))
{
throw new InputException('The job ID must be a numeric value.');
}
// Our data object.
$data = new stdClass();
$data->seskey = $this->sesKey;
$data->jobid = $jobID;
$data->uniqueid = $uniqueID;
$result = $this->request('data.questions.updateChecksum', $data);
return $result;
}
/**
* Marks a specific question as being done for a session.
*
* @param number $uniqueID The question unique ID to be marked as done.
*
* @return boolean
*/
public function questionDone($uniqueID)
{
// Check that we have a sesKey to send to the REST API.
if (!isset($this->sesKey) OR empty($this->sesKey))
{
throw new InputException('You must be connected with a valid session to call this method.');
}
// Check that we have a proper uniqueID
if (is_null($uniqueID) OR !is_numeric($uniqueID))
{
throw new InputException('The question ID must be a numeric value.');
}
// Our data object.
$data = new stdClass();
$data->seskey = $this->sesKey;
$data->uniqueid = $uniqueID;
$result = $this->request('data.questions.done', $data);
return $result->success;
}
/**
* Checks if we have new responses to get.
*
* @return boolean
*/
public function hasNewResponses()
{
// Check that we have a sesKey to send to the REST API.
if (!isset($this->sesKey) OR empty($this->sesKey))
{
throw new InputException('You must be connected with a valid session to call this method.');
}
// Our data object.
$data = new stdClass();
$data->seskey = $this->sesKey;
$result = $this->request('data.responses.hasNew', $data);
return $result->hasnew;
}
/**
* Get the answers for the current question.
*
* @return stdClass[]
*/
public function getAnswers()
{
// Check that we have a sesKey to send to the REST API.
if (!isset($this->sesKey) OR empty($this->sesKey))
{
throw new InputException('You must be connected with a valid session to call this method.');
}
// Our data object.
$data = new stdClass();
$data->seskey = $this->sesKey;
$result = $this->request('data.responses.get', $data);
return $result->responses;
}
/**
* Fethes the meta data for the current records.
*
* @return stdClass[]
*/
public function getMetaData()
{
// Check that we have a sesKey to send to the REST API.
if (!isset($this->sesKey) OR empty($this->sesKey))
{
throw new InputException('You must be connected with a valid session to call this method.');
}
// Our data object.
$data = new stdClass();
$data->seskey = $this->sesKey;
$result = $this->request('data.sessions.metaData', $data);
return $result->records;
}
/**
* Returns a listing of all surveys available on the install.
*
* @return stdClass[]
*/
public function getSurveys()
{
// Check that we have a sesKey to send to the REST API.
if (!isset($this->sesKey) OR empty($this->sesKey))
{
throw new InputException('You must be connected with a valid session to call this method.');
}
// Our data object.
$data = new stdClass();
$data->seskey = $this->sesKey;
$result = $this->request('data.surveys.get', $data);
return $result->surveys;
}
}