IOS Rest API for Charting and Visualization

Posted on 30 Dec 2013 in   Uncategorized

iOS – URL Scheme Connector

This API is intended for iOS Apps that want to use the SecondPrism Data Visualization Platform for visualizing data created by the iOS App. The basic flow is as follows:

App calls URL Scheme secondprism://?json={}
app-name is the name of the iOS App
json parameter is the chartCollection json Object – to view what the chartCollection looks like see the full JSON API Documentation for SecondPrism.
Example JSON formats:

secondprism://QuestionPro?json={chartCollection:[{title:”Chart Collection Title”, charts: [{title : “What is your gender?”, type:”BarChart”, datapoints:[{title:”Male”, frequency:10} , {title:”female”, frequency:40} , {title : “Prefer not to say” : frequency : 33}]}] }]}
This will create a chart for the data point :

What is your Gender
– Male (12%)
– Female (48%)
– Prefer not to say (40%)

This assumes the calling App is QuestionPro.

iOS Calling Function

// Create your JSON
NSString* json = @”{}”

// Be careful to always URL encode things like spaces and other
// symbols that aren’t URL friendly
NSString* escapedJSON =
[json stringByAddingPercentEscapesUsingEncoding: NSUTF8StringEncoding];

// Now create the URL string …
NSString* urlString = [NSString stringWithFormat:@”secondprism://MyApp?json=%@”,
escapedJSON];

// Now call the openURL
[[UIApplication sharedApplication] openURL:[NSURL URLWithString:urlString]];

SecondPrism – Install

In cases where SecondPrism is NOT installed on the client, you can catch the exception and open the URL to the itunes page for downloading and installing SecondPrism : Its a Free App.
http://itunes.apple.com/us/app/secondprism/id516050662?mt=8

REST API Documentation

1. Account Provisioning

2. Register Push Token

3. DEMO Users Provisioning

4. Upgrade DEMO Account

5. Add Chart Comment

6. Add Chart Insight

7. Get Users

8. Share Chart

9. Import from all Chart Services

10. Search Public / Premium Charts

11. Get Chart Comments

12. Get Chart Insights

13. Export Charts collection

14. Get Filtered Charts

15. Import Excel File

16. Add Chart Tags

17. Delete Chart Tags

18. Replace Chart Tags

19. Search Charts by Tag

20. Get Tag Cloud

Account Provisioning

This API creates a user account in SecondPrism, connects to the specified Chart Service and imports data from the service

The API URL is http://secondprism.com/user/register.do

The API parameters are:
emailAddress – This will be used as the username for login
password – Optional, will be generated if not provided
firstName – Optional
lastName – Optional
connector_name – Name of chart service connector. This should be a valid name as configured in SecondPrism viz. SurveyAnalytics, QuestionPro, IdeaScale
connector_username – This will be used to connect to the chart service
connector_password – This will be used to connect to the chart service

The request type is GET. The API responds with a JSON
The response JSON has two objects viz. response and status. If the request is successful, the response object consists the registered user attributes.

The status object indicates the status of the request.
If status.id >= 500, then the request was NOT successful. The status.message holds the error message.
If status.id = 200, then request was successful and status.message = “OK”

The following are the Error codes supported by this API:
500 – Internal server error
501 – Email address already registered
502 – Invalid connector name
503 – Invalid connector credentials
504 – Error in importing chart data
Limitations

Please note that only those chart services that accept username and password as connector user parameters will work with the REST API. Any additional parameters or parameters with different names will not work.
Example JSON formats:

Success response:
{
“response”: {
“emailAddress”: “john.doe@secondprism.com”,
“username”: “john.doe@secondprism.com”,
“password”: “e48rKUXfa3YL”,
“firstName”: “John”,
“lastName”: “Doe”,
“deviceKey”: “vqezh”
},
“status”: {
“method”: “register.do”,
“message”: “OK”,
“id”: 200,
“url”: “/user/register.do”,
“serverUTC”: 1335952158
}
}

Failure response:
{
“response”: null,
“status”: {
“method”: “/user/register.do”,
“message”: “id Chart Service Connector Auth credentials”,
“id”: 500,
“serverUTC”: 1335952090
}
}

Register Push Token

This API registers the iOS push token in SecondPrism

The API URL is http://secondprism.com/user/registerPushToken.do

The API parameters are:
deviceKey – This will be used to authenticate the user
UUID – This is the unique mobile device ID
pushToken – The push token to be registered
platformType – valid types are (a) iOS and (b) Android

NOTE: If deviceKey is null, the requesting user is assumed to be a DEMO user. For more information see DEMO Users Provisioning

The request type is GET. The API responds with a JSON
The response JSON has a status object which indicates the status of the request
If status.id = 500, then the request was NOT successful. The status.message holds the error message.
If status.id = 200, then request was successful and status.message = “OK”
Example JSON formats:

Success response:
{
“status”: {
“method”: “registerPushToken.do”,
“message”: “OK”,
“id”: 200,
“url”: “/user/registerPushToken.do”,
“serverUTC”: 1335952158
}
}

Failure response:
{
“status”: {
“method”: “registerPushToken.do”,
“message”: “Invalid request, pushtoken required.”,
“id”: 500,
“url”: “/user/registerPushToken.do”,
“serverUTC”: 1335952090
}
}

DEMO Users Provisioning

The above API can be used to register push tokens of registered users as well as demo users.
Demo users are those users who have not registered in the system.
When a demo user registers a push token, a temporary user is created in the system and push token associated with the user
When a demo user requests for chart data, the system responds with DEMO chart data
A Demo user can later upgrade the DEMO account to a real account by calling the Upgrade DEMO Account REST API (see below)

Upgrade DEMO Account

This API allows DEMO users to upgrade to a permanent user account

The API URL is http://secondprism.com/user/upgradeAccount.do

The API parameters are:
emailAddress
password
firstName
lastName
UUID – This is the unique mobile device ID

NOTE: firstName and lastName is optional, if firstName is not provided emailAddress will be used as firstName

The request type is GET. The API responds with a JSON
The response JSON has two objects viz. response and status. If the request is successful, the response object consists the registered user attributes.

The status object indicates the status of the request.
If status.id = 500, then the request was NOT successful. The status.message holds the error message.
If status.id = 200, then request was successful and status.message = “OK”
Example JSON formats:

Success response:
{
“response”: {
“emailAddress”: “UUID003@mydomain.com”,
“username”: “UUID003@mydomain.com”,
“password”: “pass”,
“firstName”: “UUID003 First Name”,
“lastName”: null,
“deviceKey”: “lYHFL”
},
“status”: {
“id”: 200,
“message”: “OK”,
“serverUTC”: 1337952896,
“url”: “/user/upgradeAccount.do”
}
}

Failure response:
{
“status”: {
“id”: 500,
“message”: “This account has already been upgraded”,
“serverUTC”: 1337952950,
“url”: “/user/upgradeAccount.do”
}
}

Add Chart Comment

This API allows users to add comment to a Chart

The API URL is http://secondprism.com/addChartComment.do

The API parameters are:
deviceKey
chartId – chartId should match with the ID of the Chart object as retrieved in the JSON output by the charts.do REST API
ownerId – ownerId should match with the ownerId of the Chart object as retrieved in the JSON output by the charts.do REST API
comment – The comment to be added to the chart
UUID – This is the unique mobile device ID (optional)

The request type is GET. The API responds with a JSON
The response JSON has two objects viz. response and status. If the request is successful, the response object contains all the comments associated with the chart

The status object indicates the status of the request.
If status.id >= 400, then the request was NOT successful. The status.message holds the error message.
If status.id = 200, then request was successful and status.message = “OK”

The following are the Error codes supported by this API:
400 – Bad request / one or more required request parameters missing
500 – Internal (unknown) server error
506 – Invalid login credentials (i.e. invalid deviceKey)
510 – Error occurred while adding chart comment
Example JSON formats:

Success response:
{
response: {
id: 317,
ownerId: 2,
comments: [{
id: 1,
text: “Test Comment 1”,
postedBy: “Krishnan Iyer”,
postedOn: “2012-10-04T08:40:17.000+0000”
},
{
id: 2,
text: “Test Comment 2”,
postedBy: “Admin User”,
postedOn: “2012-10-04T09:18:40.000+0000”
}]
},
status: {
id: 200,
message: “OK”,
serverUTC: 1349342320,
url: “/addChartComment.do”,
deviceKey: “AAAAA”
}
}

Failure response:
{
“status”: {
“id”: 500,
“message”: “Invalid chartId, cannot add comment.”,
“serverUTC”: 1338809538,
“url”: “/addChartComment.do”
}
}

Add Chart Insight

This API allows users to add insight to a Chart

The API URL is http://secondprism.com/addChartInsight.do

The API parameters are:
deviceKey
chartId – chartId should match with the ID of the Chart object as retrieved in the JSON output by the charts.do REST API
ownerId – ownerId should match with the ownerId of the Chart object as retrieved in the JSON output by the charts.do REST API
insight – The insight to be added to the chart
UUID – This is the unique mobile device ID (optional)

The request type is GET. The API responds with a JSON
The response JSON has a status object which indicates the status of the request
The response JSON has two objects viz. response and status. If the request is successful, the response object contains all the insights associated with the chart

The status object indicates the status of the request.
If status.id >= 400, then the request was NOT successful. The status.message holds the error message.
If status.id = 200, then request was successful and status.message = “OK”

The following are the Error codes supported by this API:
400 – Bad request / one or more required request parameters missing
500 – Internal (unknown) server error
506 – Invalid login credentials (i.e. invalid deviceKey)
508 – Error occurred while adding chart insight
Example JSON formats:

Success response:
{
response: {
id: 317,
ownerId: 2,
insights: [{
id: 4,
text: “Test Insight 1”,
postedBy: “Krishnan Iyer”,
postedOn: “2012-10-04T08:42:51.000+0000”
},
{
id: 5,
text: “Test Insight 2”,
postedBy: “Krishnan Iyer”,
postedOn: “2012-10-04T09:16:49.000+0000”
}]
},
status: {
id: 200,
message: “OK”,
serverUTC: 1349342209,
url: “/addChartInsight.do”,
deviceKey: “AeuLM”
}
}

Failure response:
{
“status”: {
“id”: 500,
“message”: “Invalid chartId, cannot add insight.”,
“serverUTC”: 1338809538,
“url”: “/addChartInsight.do”
}
}

Get Users

This API allows retrieves users in the system by userType

The API URL is http://secondprism.com/user/getUsers.do

The API parameters are:
userType – Valid values are Public, Premium
UUID – This is the unique mobile device ID

The request type is GET. The API responds with a JSON
The response JSON has two objects viz. response and status. If the request is successful, the response object consists the list of users
Apart from regular user information, Each user consists of the attributes chartTitle, chartSubtitle and a 48×48 icon (base64 encoded) representing the chart data
These details can be filled in by a registered user on the website in the Edit Profile page

The status object indicates the status of the request.
If status.id = 500, then the request was NOT successful. The status.message holds the error message.
If status.id = 200, then request was successful and status.message = “OK”
Example JSON formats:

Success response:
{
“response”: {
“users”: [{
“emailAddress”: “vivek.bhaskaran@surveyanalytics.com”,
“firstName”: “Vivek”,
“lastName”: “Bhaskaran”,
“userType”: “Premium”,
“lastLoginDate”: 1337839815000,
“subtitle”: null,
“title”: null,
“image”: “iVBORw0KGgoAAAANSUhEUgAAAQ4=”,
“createdOn”: 1340023940000,
“chartUrl”: “http://secondprism.com/charts.do?deviceKey=oZEWS”
},
{
“emailAddress”: “vivek.bhaskaran+1@surveyanalytics.com”,
“firstName”: “vivek”,
“lastName”: “bhaskrana”,
“userType”: “Premium”,
“lastLoginDate”: 1333594302000,
“subtitle”: null,
“title”: null,
“createdOn”: 1340023940000,
“chartUrl”: “http://secondprism.com/charts.do?deviceKey=rZInq”
}]
},
“status”: {
“id”: 200,
“message”: “OK”,
“serverUTC”: 1340352672,
“url”: “/user/getUsers.do”
}
}
Failure response:
{
“response”: null,
“status”: {
“id”: 500,
“message”: “A valid userType, one of Public/Premium should be provided”,
“serverUTC”: 1340352745,
“url”: “/user/getUsers.do”
}
}

Share Chart

This API allows users to share a Chart

The API URL is http://secondprism.com/shareChart.do

The API parameters are:
deviceKey
chartId – chartId should match with the ID of the Chart object as retrieved in the JSON output by the charts.do REST API
ownerId – ownerId should match with the ownerId of the Chart object as retrieved in the JSON output by the charts.do REST API
emailAddresses (optional) – Comma separated emailAddresses of the users to share the chart with. (Please make sure to URL encode the emailAddresses)
UUID (optional) – This is the unique mobile device ID

The request type is GET. The API responds with a JSON
The response JSON has a status object which indicates the status of the request
New emailAddresses are autoregistered. If emailAddresses are not specified, it is assumed that the chart is to be shared with public i.e. everyone
To share a chart, a user should be either (1) owner of a chart or (2) the chart should have been shared with user by another user or (3) chart should be public i.e. already shared by another user with everyone
A Chart Share mail is sent to the user. The user’s login information is displayed in the mail for new users
If status.id >= 400, then the request was NOT successful. The status.message holds the error message.
If status.id = 200, then request was successful and status.message = “OK”

The following are the Error codes supported by this API:
400 – Bad request / one or more required request parameters missing
500 – Internal (unknown) server error
505 – Invalid emailAddresses
506 – Invalid login credentials (i.e. invalid deviceKey)
507 – Error occurred while sharing chart
Example JSON formats:

Success response:
{
status: {
id: 200,
message: “OK”,
serverUTC: 1342105124,
url: “/shareChart.do”
}
}

Failure response:
{
status: {
id: 500,
message: “No deviceKey specified”,
serverUTC: 1342105673,
url: “/shareChart.do”
}
}

Import from all Chart Services

This API allows users to import from all Chart services. Note that Excel, SPSS, CSV are excluded since they involve file upload

The API URL is http://secondprism.com/importAllCharts.do

The API parameters are:
deviceKey
UUID – This is the unique mobile device ID (optional)

The request type is GET. The API responds with a JSON
The response JSON has a status object which indicates the status of the request
If status.id >= 400, then the request was NOT successful. The status.message holds the error message.
If status.id = 200, then request was successful

The following are the Error codes supported by this API:
400 – Bad request / one or more required request parameters missing
500 – Internal (unknown) server error
506 – Invalid login credentials (i.e. invalid deviceKey)
NOTE: Even if status.id = 200, the status.messages object indicates the individual status of each chart service pull
Example JSON formats:

Success responses:
Success Sample 1 (one chart service failed):
{
status: {
id: 200,
serverUTC: 1343128179,
url: “/importAllCharts.do”,
messages: {
IdeaScale: “Success”,
SurveyAnalytics: “Success”,
QuestionPro: “Failure : Error in importing data from Chart Service QuestionPro”,
Facebook: “Success”
}
}
}

Success Sample 2 (not connected to any service):
{
status: {
id: 200,
message: “Not connected to any chart service”,
serverUTC: 1343129777,
url: “/importAllCharts.do”
}
}

Failure response:
{
status: {
id: 506,
message: “Invalid login credentials provided”,
serverUTC: 1343129192,
url: “/importAllCharts.do”
}
}

Search Public / Premium Charts

This API allows users to search across all public and premium charts.

The API URL is http://secondprism.com/searchCharts.do

The API parameters are:
deviceKey
dataType – PUBLIC or PREMIUM
searchText – The text to search for
UUID – This is the unique mobile device ID (optional)

The request type is GET. The API responds with a JSON
The response JSON has two objects viz. response and status. If the request is successful, the response object consists the charts that matched the search text. The searchText is searched for in datapoint title as well as chart title across all charts in the repository of the specified dataType

The status object indicates the status of the request.
If status.id >= 400, then the request was NOT successful. The status.message holds the error message.
If status.id = 200, then request was successful

The following are the Error codes supported by this API:
400 – Bad request / one or more required request parameters missing
500 – Internal (unknown) server error
506 – Invalid login credentials (i.e. invalid deviceKey)
509 – Error occurred while searching…indicates a problem with the repository
Example JSON formats:

Success response:
{
“response”: [{
“title”: “How many times in the past week have you visited a Starbucks?”,
“id”: 180022,
“type”: “BarChart”,
“ownerId”: 1,
“url”: “http://localhost/How-many-times-in-the-past-week-have-you-visited-a/fchiCi1fJ/16AYYi7/sp2.do”,
“datapoints”: [{
“id”: 133357058,
“title”: “Once”,
“frequency”: 122.0,
“spotlight”: true
},
{
“id”: 133357059,
“title”: “Twice”,
“frequency”: 39.0,
“spotlight”: false
}]
},
{
“title”: “How much do you normally spend at Starbucks?”,
“id”: 180025,
“type”: “BarChart”,
“ownerId”: 1,
“url”: “http://localhost/How-much-do-you-normally-spend-at-Starbucks-/NC0u539rH/1e823PT/sp2.do”,
“datapoints”: [{
“id”: 133357076,
“title”: “5 – 10 dollars”,
“frequency”: 40.0,
“spotlight”: true
},
{
“id”: 133357075,
“title”: “Less than 5 dollars”,
“frequency”: 21.0,
“spotlight”: false
}]
}],
“status”: {
“id”: 200,
“message”: “OK”,
“serverUTC”: 1345459313,
“url”: “/searchCharts.do”
}
}

Failure response:
{
“response”: null,
“status”: {
“id”: 400,
“message”: “A valid dataType, one of PUBLIC/PREMIUM should be provided”,
“serverUTC”: 1345459575,
“url”: “/searchCharts.do”
}
}

Get Chart Comments

This API allows users to retrieve all comments associated with a chart

The API URL is http://secondprism.com/getChartComments.do

The API parameters are:
deviceKey
chartId – chartId should match with the ID of the Chart object as retrieved in the JSON output by the charts.do REST API
ownerId – ownerId should match with the ownerId of the Chart object as retrieved in the JSON output by the charts.do REST API
UUID – This is the unique mobile device ID (optional)

The request type is GET. The API responds with a JSON
The response JSON has two objects viz. response and status. If the request is successful, the response object consists the comments for the chart.

The status object indicates the status of the request.
If status.id >= 400, then the request was NOT successful. The status.message holds the error message.
If status.id = 200, then request was successful

The following are the Error codes supported by this API:
400 – Bad request / one or more required request parameters missing or invalid
500 – Internal (unknown) server error occurred while retrieving chart comments
506 – Invalid login credentials (i.e. invalid deviceKey)
Example JSON formats:

Success response:
{
response: {
id: 317,
ownerId: 2,
comments: [{
id: 1,
text: “Test Comment 1”,
postedBy: “Krishnan Iyer”,
postedOn: “2012-10-04T08:40:17.000+0000”
},
{
id: 2,
text: “Test Comment 2”,
postedBy: “Admin User”,
postedOn: “2012-10-04T08:41:42.000+0000”
}]
},
status: {
id: 200,
message: “OK”,
serverUTC: 1349342067,
url: “/getChartComments.do”,
deviceKey: “AeuLM”
}
}

Failure response:
{
response: null,
status: {
id: 400,
message: “Invalid request. Invalid chartId.”,
serverUTC: 1349342005,
url: “/getChartInsights.do”,
deviceKey: “AeuLM”
}
}

Get Chart Insights

This API allows users to retrieve all insights associated with a chart

The API URL is http://secondprism.com/getChartInsights.do

The API parameters are:
deviceKey
chartId – chartId should match with the ID of the Chart object as retrieved in the JSON output by the charts.do REST API
ownerId – ownerId should match with the ownerId of the Chart object as retrieved in the JSON output by the charts.do REST API
UUID – This is the unique mobile device ID (optional)

The request type is GET. The API responds with a JSON
The response JSON has two objects viz. response and status. If the request is successful, the response object consists the insights for the chart.

The status object indicates the status of the request.
If status.id >= 400, then the request was NOT successful. The status.message holds the error message.
If status.id = 200, then request was successful

The following are the Error codes supported by this API:
400 – Bad request / one or more required request parameters missing or invalid
500 – Internal (unknown) server error occurred while retrieving chart insights
506 – Invalid login credentials (i.e. invalid deviceKey)
Example JSON formats:

Success response:
{
response: {
id: 317,
ownerId: 2,
insights: [{
id: 3,
text: “Test Insight 1”,
postedBy: “Admin User”,
postedOn: “2012-10-04T08:42:38.000+0000”
},
{
id: 4,
text: “Test Insight 1”,
postedBy: “Krishnan Iyer”,
postedOn: “2012-10-04T08:42:51.000+0000”
}]
},
status: {
id: 200,
message: “OK”,
serverUTC: 1349341929,
url: “/getChartInsights.do”,
deviceKey: “AeuLM”
}
}

Failure response:
{
response: null,
status: {
id: 400,
message: “Invalid request. Invalid chartId.”,
serverUTC: 1349342005,
url: “/getChartInsights.do”,
deviceKey: “AeuLM”
}
}

Export Charts

This API allows users to export the whole charts collection that contains the chart specified by the chartId parameter to a specified format as specified by the exportFormat parameter. The response contains the filename and the contents of the file in the specified exportFormat and is base64 encoded. Decoding the file contents and saving as the filename should convert the file back to the specified exportFormat

The API URL is http://secondprism.com/exportCharts.do

The API parameters are:
deviceKey
chartId – chartId should match with the ID of the Chart object as retrieved in the JSON output by the charts.do REST API
ownerId – ownerId should match with the ownerId of the Chart object as retrieved in the JSON output by the charts.do REST API
exportFormat – Supported formats are Excel, PPT, InfoGraphics
UUID – This is the unique mobile device ID (optional)

The request type is GET. The API responds with a JSON
The response JSON has two objects viz. response and status. If the request is successful, the response object consists the filename and base64 encoded contents

The status object indicates the status of the request.
If status.id >= 400, then the request was NOT successful. The status.message holds the error message.
If status.id = 200, then request was successful

The following are the Error codes supported by this API:
400 – Bad request / one or more required request parameters missing or invalid
511 – Internal (unknown) server error occurred while exporting chart collection
506 – Invalid login credentials (i.e. invalid deviceKey)
Example JSON formats:

Success response:
{
response: {
filename: “StudentDebtSurvey.xls”,
contents: ” ”
},
status: {
id: 200,
message: “OK”,
serverUTC: 1349426722,
url: “/exportCharts.do”,
deviceKey: “AAAAA”
}
}

Failure response:
{
response: null,
status: {
id: 400,
message: “Invalid request. Invalid chartId.”,
serverUTC: 1349427742,
url: “/exportCharts.do”,
deviceKey: “AAAAA”
}
}

Get Filtered Charts

This API allows users to get filtered chart data. The request and response both are in JSON format

Sample request JSON for Filtered criteria:

{
“deviceKey”: “AAAAA”,
“chartCollectionID”: 4102,
“filterUrl”: “http://admin.questionpro.com/a/api/surveyanalytics.secondprism.getFilteredData?apiKey=2fb9f2d0-bacd-4bcf-87af-61680a5b1ef1&=tyddf&password=74b24”,
“elements”: [{
“filterElementIDList”: “70713_70714_70715_70716”,
“filterPointID”: 17598857,
“compID”: 1
},
{
“filterPointID”: 17598858,
“selectedFilterElementID”: 70717,
“compID”: 2,
“joint”: “AND”
}]
}

The API URL is http://secondprism.com/getFilteredCharts.do

The only API parameter is:
filterRequestJson: Criteria for getting charts in JSON format. Please refer above sample JSON. All attributes as in the sample JSON are required
The chartCollectionID is available for each chart collection in the JSON output of the charts.do REST API
The filterUrl is also available in the response object in the JSON output of the charts.do REST API. filterUrl is common URL for all filter requests

Only POST requests are supported. The API response is in JSON format
The response JSON has two objects viz. response and status. If the request is successful, the response object contains filtered chart data.

The status object indicates the status of the request.
If status.id = 200, the request was successful.

The following are the Error codes supported by this API:
400 – Bad request / filterRequestJson missing or has invalid format or deviceKey is missing in filterRequestJson.
506 – Invalid login credentials i.e. invalid deviceKey
512 – Server error occurred while getting filtered charts This error might occur because of following reasons which is returned as part of the status message:
Invalid chart owner ID in filterRequestJson
Invalid chart data set ID in filterRequestJson
Chart Service connection failed
Error while parsing response received from Chart Service
Chart Service Import failed because of any reason
Unknown Internal Server Error
Example JSON formats:

Success response:
{
“response”: {
“id”: 8,
“chartCollection”: [{
“charts”: [{
“title”: “2 Countries”,
“numberpoints”: [{
“title”: 7,
“subtitle”: “Started”,
“type”: “started”
},
{
“title”: 7,
“subtitle”: “Completed”,
“type”: “completed”
},
{
“title”: “100%”,
“subtitle”: “Completion Rate”,
“type”: “completion-rate”
},
{
“title”: 10,
“subtitle”: “Viewed”,
“type”: “viewed”
},
{
“title”: 0,
“subtitle”: “Drop Out”,
“type”: “dropout”
},
{
“title”: “24s”,
“subtitle”: “Avg. Time Taken”,
“type”: “time-taken”
}],
“type”: “Dashboard”
},
{
“datapoints”: [{
“title”: “N/A”,
“subtitle”: “Unknown”,
“frequency”: 6
},
{
“title”: “US”,
“subtitle”: “United States”,
“frequency”: 1
}],
“title”: “Countries Surveyed”,
“type”: “WorldMap”
},
{
“id”: 29720443,
“datapoints”: [{
“id”: 139828815,
“title”: “a”,
“frequency”: 0
},
{
“id”: 139828818,
“title”: “d”,
“frequency”: 0
}],
“title”: “Q1”,
“type”: “PieChart”
},
{
“id”: 29720444,
“datapoints”: [{
“id”: 139828819,
“title”: “a1”,
“frequency”: 0
},
{
“id”: 139828822,
“title”: “d1”,
“frequency”: 0
}],
“title”: “Q2”,
“type”: “PieChart”
}],
“title”: “Grouping Test For K”,
“chartCollectionID”: 3268459
}],
“username”: “tyddf”,
“emailAddress”: “vivek.bhaskaran@surveyanalytics.com”,
“clientLicense”: [{
“index”: 1,
“title”: “Customer ID”,
“value”: 8,
“key”: “customerID”
},
{
“title”: “Service”,
“value”: “QuestionPro”,
“key”: “service”
}],
“password”: “74b24”
},
“status”: {
“message”: “OK”,
“id”: 200,
“method”: “surveyanalytics.secondprism.getFilteredData”,
“serverUTC”: 1350544839900,
“url”: “/a/api/surveyanalytics.secondprism.getFilteredData”,
“apiKey”: “2fb9f2d0-bacd-4bcf-87af-61680a5b1ef1”
}
}

Failure response:
{
response: null,
status: {
id: 400,
message: “Invalid request. Invalid deviceKey.”,
serverUTC: 1349427742,
url: “/a/api/surveyanalytics.secondprism.getFilteredData”,
deviceKey: “AAAAA”
}
}

Import Excel File

This API allows users to import excel file (i.e. open excel file in SecondPrism). The response contains chart data of imported excel file.

The API URL is http://secondprism.com/importFile.do

The API parameters are:
deviceKey – This is required parameter.
UUID – This is optional parameter.
encodedFile – This required parameter. It is Base64 encoded String of excel file to import
fileName – This optional parameter. It is file name of excel file to import.

The requestType is POST. The API response is in JSON format.
The response JSON has two objects viz. response and status. If the request is successful, the response object contains chart data.

The status object indicates the status of the request.
If status.id >= 400, then the request was NOT successful. The status.message holds the error message.
If status.id = 200, then request was successful

The following are the Error codes supported by this API:
400 – Bad request / one or more required request parameters missing or invalid.
513 – Internal (unknown) server error occurred while importing excel file.
506 – Invalid login credentials (i.e. invalid deviceKey).
Example JSON formats:

Success response:
{
“response”: {
“id”: 24,
“ownerId”: 1,
“title”: “Sheet1”,
“subtitle”: “10/18/2012”,
“charts”: [{
“title”: “Chart1Header”,
“id”: 347,
“type”: “BarChart”,
“ownerId”: 1,
“datapoints”: [{
“id”: 2578,
“title”: “Option1”,
“frequency”: 2.0
},
{
“id”: 2579,
“title”: “Option2”,
“frequency”: 4.0
},
{
“id”: 2580,
“title”: “Option3”,
“frequency”: 2.0
}]
},
{
“title”: “Chart2Header”,
“id”: 348,
“type”: “BarChart”,
“ownerId”: 1,
“datapoints”: [{
“id”: 2581,
“title”: “Option4”,
“frequency”: 2.0
},
{
“id”: 2582,
“title”: “Option5”,
“frequency”: 3.0
}]
},
{
“title”: “Chart3Header”,
“id”: 349,
“type”: “BarChart”,
“ownerId”: 1,
“datapoints”: [{
“id”: 2583,
“title”: “Option6”,
“frequency”: 1.0
},
{
“id”: 2584,
“title”: “Option7”,
“frequency”: 2.0
}]
},
{
“title”: “Chart4Header”,
“id”: 350,
“type”: “BarChart”,
“ownerId”: 1,
“datapoints”: [{
“id”: 2585,
“title”: “Option8”,
“frequency”: 2.0
},
{
“id”: 2586,
“title”: “Option9”,
“frequency”: 2.0
},
{
“id”: 2587,
“title”: “Option10”,
“frequency”: 1.0
}]
},
{
“title”: “Chart5Header”,
“id”: 351,
“type”: “BarChart”,
“ownerId”: 1,
“datapoints”: [{
“id”: 2588,
“title”: “Option8”,
“frequency”: 3.0
},
{
“id”: 2589,
“title”: “Option9”,
“frequency”: 2.0
},
{
“id”: 2590,
“title”: “Option10”,
“frequency”: 1.0
}]
}]
},
“status”: {
“id”: 200,
“message”: “OK”,
“serverUTC”: 1350537509,
“url”: “/importFile.do”,
“deviceKey”: “AAAAA”
}
}

Failure response:
{
“status”: {
“id”: 506,
“message”: “Invalid login credentials provided”,
“serverUTC”: 1350537679,
“url”: “/importFile.do”
}
}

Add Chart Tags

This API allows users to add tags to a Chart

The API URL is http://secondprism.com/addChartTags.do

The API parameters are:
deviceKey
chartId – chartId should match with the ID of the Chart object as retrieved in the JSON output by the charts.do REST API
ownerId – ownerId should match with the ownerId of the Chart object as retrieved in the JSON output by the charts.do REST API
tags – The tags to be added to the chart. Multiple tags can be added, valid tag separators are comma, semicolon, space and fullstop. Tag text can contain only alphanumerics (0-9,A-Z,a-z) and the hyphen (-) character. If any one of the tags are invalid none of the tags will be added and API will return error. If a tag already exists, it will not be added, will be ignored
UUID – This is the unique mobile device ID (optional)

The request type is GET. The API responds with a JSON
The response JSON has two objects viz. response and status. If the request is successful, the response object contains the tags that were just added

The status object indicates the status of the request.
If status.id >= 400, then the request was NOT successful. The status.message holds the error message.
If status.id = 200, then request was successful and status.message = “OK”

The following are the Error codes supported by this API:
400 – Bad request / one or more required request parameters missing
500 – Internal (unknown) server error
506 – Invalid login credentials (i.e. invalid deviceKey)
514 – Error occurred while adding chart tags
Example JSON formats:

Success response:
{
response: {
id: 317,
ownerId: 2,
tags: [{
id: 1,
text: “Tag1”,
addedBy: “Krishnan Iyer”,
addedOn: “2012-11-06T17:40:17.000+0000”,
hits: 0
},
{
id: 2,
text: “Tag-2”,
addedBy: “Admin User”,
addedOn: “2012-11-06T17:42:40.000+0000”,
hits: 0
}]
},
status: {
id: 200,
message: “OK”,
serverUTC: 1349342345,
url: “/addChartTags.do”,
deviceKey: “AAAAA”
}
}

Failure response:
{
“status”: {
“id”: 400,
“message”: “One or more tags are invalid, cannot add tags.”,
“serverUTC”: 1338809987,
“url”: “/addChartTags.do”
}
}

Delete Chart Tags

This API allows users to delete a single tag or all tags from a Chart

The API URL is http://secondprism.com/deleteChartTags.do

The API parameters are:
deviceKey
chartId – chartId should match with the ID of the Chart object as retrieved in the JSON output by the charts.do REST API
ownerId – ownerId should match with the ownerId of the Chart object as retrieved in the JSON output by the charts.do REST API
tagID (do not specify if all tags have to be deleted) – The ID of the tag as obtained in getChartTags API to be deleted from the chart. If this parameter is skipped, all tags in the chart will be deleted
UUID – This is the unique mobile device ID (optional)

The request type is GET. The API responds with a JSON
The response JSON has a status object which indicates the status of the request
If status.id >= 400, then the request was NOT successful. The status.message holds the error message.
If status.id = 200, then request was successful and status.message = “OK”

The following are the Error codes supported by this API:
400 – Bad request / one or more required request parameters missing
500 – Internal (unknown) server error
506 – Invalid login credentials (i.e. invalid deviceKey)
515 – Error occurred while adding chart tags. The status message contains the error details
Example JSON formats:

Success response:
{
status: {
id: 200,
message: “OK”,
serverUTC: 1349342756,
url: “/deleteChartTags.do”,
deviceKey: “AAAAA”
}
}

Failure response:
{
“status”: {
“id”: 515,
“message”: “Invalid tagID specified, cannot delete tags.”,
“serverUTC”: 1338809857,
“url”: “/deleteChartTags.do”
}
}

Replace Chart Tags

This API allows users to replace existing tags with a new set of tags

The API URL is http://secondprism.com/replaceChartTags.do

The API parameters are:
deviceKey
chartId – chartId should match with the ID of the Chart object as retrieved in the JSON output by the charts.do REST API
ownerId – ownerId should match with the ownerId of the Chart object as retrieved in the JSON output by the charts.do REST API
tags – The tags to be added to the chart. Multiple tags can be added, valid tag separators are comma, semicolon, space and fullstop. Tag text can contain only alphanumerics (0-9,A-Z,a-z) and the hyphen (-) character. If any one of the tags are invalid none of the tags will be added and API will return error. The existing tags associated with the chart added by the user identified by the deviceKey parameter will be deleted and all the tags in the tags parameter will be added to the chart. Existing tags added by other users to the same chart will not be added again, will be ignored
UUID – This is the unique mobile device ID (optional)

The request type is GET. The API responds with a JSON
The response JSON has two objects viz. response and status. If the request is successful, the response object contains the latest set of tags associated with the chart

The status object indicates the status of the request.
If status.id >= 400, then the request was NOT successful. The status.message holds the error message.
If status.id = 200, then request was successful and status.message = “OK”

The following are the Error codes supported by this API:
400 – Bad request / one or more required request parameters missing
500 – Internal (unknown) server error
506 – Invalid login credentials (i.e. invalid deviceKey)
517 – Error occurred while replacing chart tags
Example JSON formats:

Success response:
{
response: {
id: 317,
ownerId: 2,
tags: [{
id: 1,
text: “Tag1”,
addedBy: “Krishnan Iyer”,
addedOn: “2012-11-06T17:40:17.000+0000”,
hits: 0
},
{
id: 2,
text: “Tag-2”,
addedBy: “Admin User”,
addedOn: “2012-11-06T17:42:40.000+0000”,
hits: 0
}]
},
status: {
id: 200,
message: “OK”,
serverUTC: 1349342345,
url: “/replaceChartTags.do”,
deviceKey: “AAAAA”
}
}

Failure response:
{
“status”: {
“id”: 400,
“message”: “One or more tags are invalid, cannot replace tags.”,
“serverUTC”: 1338809987,
“url”: “/replaceChartTags.do”
}
}

Search Charts By Tag

This API allows users to search charts by tag

The API URL is http://secondprism.com/searchChartsByTag.do

The API parameters are:
deviceKey
tag – tag text to search for
dataType – Allowed values are PUBLIC and PREMIUM
UUID – This is the unique mobile device ID (optional)

The request type is GET. The API responds with a JSON
The response JSON has two objects viz. response and status. If the request is successful, the response object contains a chart collection enclosing the charts that have associated tags matching the searched tag text

The status object indicates the status of the request.
If status.id >= 400, then the request was NOT successful. The status.message holds the error message.
If status.id = 200, then request was successful and status.message = “OK”

The following are the Error codes supported by this API:
400 – Bad request / one or more required request parameters missing
500 – Internal (unknown) server error
506 – Invalid login credentials (i.e. invalid deviceKey)
518 – Error occurred while searching for chart tags
Example JSON formats:

Success response:
{
“response”: {
“id”: 2,
“emailAddress”: “krishnan.iyer@crmchimp.com”,
“chartCollection”: [{
“id”: 0,
“ownerId”: 0,
“charts”: [{
“title”: “1”,
“id”: 317,
“type”: “Dashboard”,
“ownerId”: 1,
“url”: “http://localhost/1/gbwMoFX/Z1cYmR/sp2.do”,
“subtitle”: “Country”,
“numberpoints”: [{
“title”: 19,
“subtitle”: “Viewed”,
“type”: “viewed”
},
{
“title”: 3,
“subtitle”: “Completed”,
“type”: “completed”
},
{
“title”: 6,
“subtitle”: “Drop Out”,
“type”: “dropout”
},
{
“title”: 9,
“subtitle”: “Started”,
“type”: “started”
},
{
“title”: “33.33%”,
“subtitle”: “Completion Rate”,
“type”: “completion-rate”
},
{
“title”: “1 min”,
“subtitle”: “Avg. Time Taken”,
“type”: “time-taken”
}]
}]
}]
},
“status”: {
“id”: 200,
“message”: “OK”,
“serverUTC”: 1352740443,
“url”: “/searchChartsByTag.do”,
“deviceKey”: “YAmjY”
}
}

Failure response:
{
“response”: null,
“status”: {
“id”: 400,
“message”: “Invalid request. No tag provided.”,
“serverUTC”: 1352741105,
“url”: “/searchChartsByTag.do”
}
}

Get Tag Cloud

This API allows users to get PUBLIC or PREMIUM data tag cloud

The API URL is http://secondprism.com/getTagCloud.do

The API parameters are:
deviceKey
dataType – Allowed values are PUBLIC and PREMIUM
UUID – This is the unique mobile device ID (optional)

The request type is GET. The API responds with a JSON
The response JSON has two objects viz. response and status. If the request is successful, the response object contains a chart of type = TextCloud.

The status object indicates the status of the request.
If status.id >= 400, then the request was NOT successful. The status.message holds the error message.
If status.id = 200, then request was successful and status.message = “OK”

The following are the Error codes supported by this API:
400 – Bad request / one or more required request parameters missing
500 – Internal (unknown) server error
506 – Invalid login credentials (i.e. invalid deviceKey)
519 – Error occurred while retrieving tag cloud
Example JSON formats:

Success response:
{
“response”: {
“title”: “Public Charts Tag Cloud”,
“id”: 0,
“type”: “TextCloud”,
“ownerId”: 0,
“textpoints”: [{
“title”: “Tag1”,
“url”: “http://localhost/searchChartsByTag.do?deviceKey=AAAAA&dataType=PUBLIC&tag=Tag1”,
“frequency”: 1.0
},
{
“title”: “Tag2”,
“url”: “http://localhost/searchChartsByTag.do?deviceKey=AAAAA&dataType=PUBLIC&tag=Tag2”,
“frequency”: 1.0
},
{
“title”: “Tag3”,
“url”: “http://localhost/searchChartsByTag.do?deviceKey=AAAAA&dataType=PUBLIC&tag=Tag3”,
“frequency”: 1.0
}]
},
“status”: {
“id”: 200,
“message”: “OK”,
“serverUTC”: 1352742324,
“url”: “/getTagCloud.do”,
“deviceKey”: “AAAAA”
}
}

Failure response:
{
response: null,
status: {
id: 400,
message: “A valid dataType, one of PUBLIC/PREMIUM should be provided.”,
serverUTC: 1352742610,
url: “/getTagCloud.do”
}
}