Utvikler-API Dokumentasjon

This version of the API is no longer supported.

Please see documentation for V2 of our API

Feel free to contact us at info@fluidsurveys.com

Bruk

Alle kall til utviklings-API gjøres gjennom http://fluidsurveys.no/api/surveys/?key=[din API-nøkkel]

Du kan også legge inn et "språk"-parameter som vil oversette tekst til det språket som ønskes. Eksempelvis vil http://fluidsurveys.no/api/surveys/?key=[Your API Key]&lang=fr oversette all tekst til Fransk.

Denne APIen godtar et "format" parameter som kan være "XML" eller "json". Resultater formatteres som standard til XML.

Legg merke til at verdier vil pakkes inn i CDATA der det er hensiktsmessig. Dette vil skje når felt som inneholder HTML lages.

Metoder
getSurveyList
Description: Returns information about all surveys a user has created.
Usage: http://fluidsurveys.no/api/surveys/?key=[Your API Key]&uk=[Your API User Key]&action=getSurveyList

Return format (XML): 
<?xml version="1.0" encoding='UTF-8'?>
<fsAPIResults query="user" param="1">
	<surveys>
		<survey id="3">
			<name>My Survey</name>
			<title>My survey's title</title>
			<description>My survey's description</description>
			<publishURL>http://fluidsurveys.no/surveys/me/my-survey/</publishURL>
			<publishLink><a href="http://fluidsurveys.no/surveys/me/my-survey/">My Survey</a></publishLink>
		<survey>
			
		<survey id="7">
			<name>Another Survey</name>
			<title>Another survey's title</title>
			<description>Another survey's description</description>
			<publishURL>http://fluidsurveys.no/surveys/me/another-survey/</publishURL>
			<publishLink><a href="http://fluidsurveys.no/surveys/me/another-survey/">My Survey</a></publishLink>			
		<survey>
	</surveys>
</fsAPIResults>
Return format (JSON): 
'fsApiResult': {
	surveys: [{
		'id': 3,
		'name': 'My Survey',
		'title': 'My survey\'s title'
		'description': 'My survey\'s description'
		'publish_url': "http://fluidsurveys.com/surveys/me/my-survey/"
	}, {
		'id': 7,
		'name': 'Another Survey',
		'title': 'Another survey\'s title'
		'description': 'Another survey\'s description'
		'publish_url': "http://fluidsurveys.com/surveys/me/my-survey/"
	}]
}
getSurvey
Description: Returns information about a survey.
Usage: http://fluidsurveys.no/api/surveys/?key=[Your API Key]&uk=[Your API User Key]&survey=[Survey ID]&action=getSurvey

Return format (XML): 
<?xml version="1.0" encoding='UTF-8'?>
<fsAPIResults query="survey" param="68">
	<survey id="68">
		<name>My Survey</name>
		<title>My survey's title</title>
		<description>My survey's description</description>
		<creator>
			<name>
				My Name
			</name>
			<email>
				my@email.com
			</email>
		</creator>
		<publishURL>http://fluidsurveys.no/surveys/me/my-survey/</publishURL>
		<publishLink><a href="http://fluidsurveys.no/surveys/me/my-survey/">My Survey</a></publishLink>
		<numberOfPages>1</numberOfPages>
		<numberOfQuestions>1</numberOfQuestions>
		<numberOfResponses>1</numberOfResponses>
		<completion>%50</completion>
		<live>True</live>
		<pages>
			<page>
				<question>
					<title>Isn't this fun?</title>
					<description></description>
					<type>boolean-choice</type>
					<id>DF754DFG</id>
				</question>
			</page>
		</pages>
	</survey>
</fsAPIResults>
Return format (JSON): 
'fsApiResult': {
	'survey_id': 68,
	'survey': {
		'name': 'My Surveys',
		'title': 'My surveys\'s title',
		'description': 'My surveys\'s description',,
		'num_pages': 1,
		'creator_name': 'My Name',
		'creator_email': 'my@email.com',
		'completion': 50,
		'live': "True",
		'num_responses': 1,
		'num_questions': 1,
		'publish_url': 'http://fluidsurveys.com/surveys/me/my-survey/',				
		'pages': [{
			'questions': [{
				'title': 'Isn\'t this fun?',
				'description': '',
				'type': 'boolean-choice',
				'id': DF754DFG
			}]
		}]
	}
}
getResponseList
Description: Returns a list of responses to a survey.
Usage: http://fluidsurveys.no/api/surveys/?key=[Your API Key]&uk=[Your API User Key]&survey=[Survey ID]&action=getResponseList

Note that 'group' represents all responses collecting within one survey-taking session.

Optional arguments: created_at_min=[date/time] and created_at_max=[date/time] to limit responses to certain date ranges.

Return format (XML): 
<?xml version="1.0" encoding='UTF-8'?>
<fsAPIResults query="survey" param="68">
	<survey id="68">
		<name>My Survey</name>
		<title>My survey's title</title>
		<description>My survey's description</description>
		<publishURL>http://fluidsurveys.no/surveys/me/my-survey/</publishURL>
		<publishLink><a href="http://fluidsurveys.no/surveys/me/my-survey/">My Survey</a></publishLink>
		<sessions>
			<group>
				<completed>false</completed>
				<completionTime></completionTime>
				<IPAddress>127.0.0.1</IPAddress>
				<language>en</language>
				<referrer>http://fluidsurveys.no</referrer>
				<responses question="Question 1">
					<response>
						Yes!
					</response>
				<responses>
			</group>
			
			<group>
				<completed>false</completed>
				<completionTime></completionTime>
				<IPAddress>127.0.0.1</IPAddress>
				<language>en</language>
				<referrer>http://fluidsurveys.no</referrer>
				<responses>
					<response question="Question 2">
						Not at all.
					</response>
				<responses>
			</group>
		</sessions>
	</survey>
</fsAPIResults>
Return format (JSON): 
'fsApiResult': {
	'survey_id': 68,
	'survey' : {
		'name': 'My Survey',
		'title': 'My survey\'s title',
		'description': 'My survey\s description',
		'publish_url': 'http://fluidsurveys.com/surveys/me/my-survey/',
		'responses': [{
			'completed': 'false',
			'completion_time': '',
			'ip_address': '127.0.0.1',
			'language': 'en',
			'referrer': 'http://fluidsurveys.com',
			'group': [{
				'response': 'Not at all',
				'question': 'Question 1'
			}]
		}]
	}
}
getSingleResponse
Description: Returns a single response from a survey.
Usage: http://fluidsurveys.no/api/surveys/?key=[Your API Key]&uk=[Your API User Key]&survey=[Survey ID]&&response=[Response Key]&action=getSingleResponse
Return format (JSON): 
'fsApiResult': {
	'response' : {
		'_completed': false,
		'_completion_time': '',
		'_ip_address': '127.0.0.1',
		'_language': 'en',
		'_referrer': 'http://fluidsurveys.com'
	}
}
Logging In

You can use the API to log into our system and create user accounts on the fly (account creation is only available to priviledged API keys).

To do so, create a form similar to the following: 

<form action="http://fluidsurveys.no/api/login/" method="POST">
	<div>
		<label>Username: <input type="text" name="username" /></label>
	</div>
	<div>
		<label>Email: <input type="text" name="email" /></label>
	</div>
	<div>
		<label>Password: <input type="password" name="password" /></label>
	</div>
	<div>
		<label>Group: <input type="text" name="group" /></label>
	</div>
	
	<input type="hidden" name="key" value="[Your developer key]" />;	

	<div>
		<input type="submit" value="OK" />
	</div>
</form>

When done through AJAX, the following will be returned:

XML 
			
<?xml version="1.0" encoding='UTF-8'?>
<chideAPIResults query="authenticate" param="my-user-name">
	<success>
		true
	</success>
</chideAPIResults>
JSON 
'fsApiResult': {		
	'success': 'true',
	'user': 'my-username'
}

If the user was found in our system, they will be logged in and redirected to their account. If the user was not found, an account will be created.

Note that the group field is optional. If it is provided, the user will be added to a group of the given name (this group will be created if it does not yet exist).

createSurvey
Description: Create a new survey.
Usage: http://fluidsurveys.no/api/surveys/?key=[Your API Key]&uk=[Your API User Key]&action=createSurvey

POST format must be multipart/form-data encoded with a single parameter "survey" containing JSON-encoded data in the following format: 
{
	"name": "My Survey",
	"title": "My Survey",
	"description": "This is my survey",
	"pages": [{
		"questions": [{
			"title": "A question",
			"description": "",
			"type": "single-choice",
			"choices": ["Yes", "No"] 
		}, {
			"title": "Another question",
			"type": "text-response"
		}]

	}, {
		"questions": [{
			"title": "A checkbox question",
			"description": "",
			"type": "multiple-choice",
			"choices": ["Yes", "No"]
		}]
	}]
}

That should return something like this:

XML 
			
<?xml version="1.0" encoding='UTF-8'?>
<chideAPIResults>
	<success>
		true
	</success>
	<survey id="101" />
</chideAPIResults>
JSON 
'fsApiResult': {								
	'success': 'true',
	'survey': 68
}
createResponse
Description: Create a new response to a survey.
Usage: http://fluidsurveys.no/api/surveys/?key=[Your API Key]&uk=[Your API User Key]&action=createResponse

POST format: 
survey: <survey identifier>

That should return something like this:

XML 
			
<?xml version="1.0" encoding='UTF-8'?>
<chideAPIResults query="userid" param="56">
	<response key="key" url="http://..." />
</chideAPIResults>
JSON 
'fsApiResult': {								
	'key': 'key',
	'url': 'http://...'
}
exportToCSV
Returns the survey's dataset as CSV.
Usage: http://fluidsurveys.no/api/surveys/?key=[Your API Key]&uk=[Your API User Key]&survey=[Survey ID]&action=exportToCSV
Optional parameters:
split_csv=true|false
score_based=true|false
include_labels=true|false
show_titles=true|false
escape_newline=true|false
Questions?

If you have any problems or questions about this API, feel free to send them to support@fluidsurveys.com