Wiki
Clone wikijavarosa / SuperRosaAPI
SuperROSA Statistics Reporting API
This document provides a specification for the API and Request format for which OpenRosa compliant servers deliver Statistics Reporting data.
Basic Analysis
Description
This method will return the statistics for all questions in the form.
URL:
https://episurveyor.org/superrosa/analysis/basic/
Available Formats
• XML
HTTP Method: POST.
Parameters
- surveyid(Required):
- startdate(Required):
- enddate(Required):
- username(Required)
- password(Required)
XML Schema
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" targetNamespace="http://episurveyor.org/superrosa/analysis/basic/" xmlns:basic="http://episurveyor.org/superrosa/analysis/basic/">
<xs:element name="report">
<xs:complexType>
<xs:sequence>
<xs:element ref="basic:params"/>
<xs:element ref="basic:stats"/>
</xs:sequence>
<xs:attribute name="title" use="required"/>
<xs:attribute name="url" use="required" type="xs:anyURI"/>
</xs:complexType>
</xs:element>
<xs:element name="params">
<xs:complexType>
<xs:sequence>
<xs:element maxOccurs="unbounded" ref="basic:param"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="param">
<xs:complexType>
<xs:attribute name="name" use="required" type="xs:NCName"/>
<xs:attribute name="value" use="required"/>
</xs:complexType>
</xs:element>
<xs:element name="stats">
<xs:complexType>
<xs:sequence>
<xs:element maxOccurs="unbounded" ref="basic:question"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="question">
<xs:complexType>
<xs:sequence>
<xs:element maxOccurs="unbounded" ref="basic:stat"/>
</xs:sequence>
<xs:attribute name="Desc" use="required"/>
<xs:attribute name="name" use="required" type="xs:NCName"/>
<xs:attribute name="type" use="required" type="xs:NCName"/>
<xs:attribute name="url" use="required"/>
</xs:complexType>
</xs:element>
<xs:element name="stat">
<xs:complexType>
<xs:attribute name="allvalue" use="required" type="xs:integer"/>
<xs:attribute name="mvalue" type="xs:integer"/>
<xs:attribute name="myvalue" type="xs:integer"/>
<xs:attribute name="name" use="required" type="xs:NCName"/>
<xs:attribute name="type" type="xs:NCName"/>
</xs:complexType>
</xs:element>
</xs:schema>
Sample XML Response
<?xml version="1.0" encoding="UTF-8"?>
<report url="https://episurveyor.org/superrosa/analysis/basic/" title ="Basic Analysis" xmlns="http://episurveyor.org/superrosa/analysis/basic/">
<params>
<param name="surveyid" value="1292"/>
<param name="startdate" value="2009-08-10"/>
<param name="enddate" value="2009-08-15"/>
<param name="username" value="gnjuguna@datadyne.org"/>
</params>
<stats>
<question name="sex" Desc="Sex" type="multiradio" url="" >
<stat name="Male" myvalue="10" allvalue="10" />
<stat name="Male" myvalue="5" allvalue="10" />
</question>
<question name="diseases" Desc="Which diseases have you ever suffered from?" type="multicheckbox" url="" >
<stat name="Malaria" type="count" myvalue="10" allvalue="10" />
<stat name="Measles" type="count" myvalue="5" allvalue="10" />
<stat name="TB" type="count" mvalue="5" allvalue="20"/>
</question>
<question name="age" Desc="What is your age?" type="numeric" url="" >
<stat name="Mean" type="mean" myvalue="20" allvalue="22"/>
<stat name="Min" type="min" myvalue="16" allvalue="15"/>
<stat name="Max" type="max" myvalue="30" allvalue="40" />
<stat name="Median" type="median" myvalue="22" allvalue="22" />
<stat name="Mode" type="mode" myvalue="22" allvalue="22" />
</question>
</stats>
</report>
Time Series
Description
This method will return the statistics for a question grouped by a periods ,a period can be a date ,a month or a year.The grouping is determined by the duration between the startdate and the enddate.
URL:
https://episurveyor.org/superrosa/analysis/timeseries/
Available Formats
• XML
HTTP Method
POST.
Parameters
- questionid(Required)
- startdate(Required)
- enddate(Required)
- username(Required)
- password(Required)
XML Schema
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" targetNamespace="http://episurveyor.org/superrosa/analysis/timeseries/" xmlns:timeseries="http://episurveyor.org/superrosa/analysis/timeseries/">
<xs:element name="report">
<xs:complexType>
<xs:sequence>
<xs:element ref="timeseries:params"/>
<xs:element ref="timeseries:stats"/>
</xs:sequence>
<xs:attribute name="title" use="required"/>
<xs:attribute name="url" use="required" type="xs:anyURI"/>
</xs:complexType>
</xs:element>
<xs:element name="params">
<xs:complexType>
<xs:sequence>
<xs:element maxOccurs="unbounded" ref="timeseries:param"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="param">
<xs:complexType>
<xs:attribute name="name" use="required" type="xs:NCName"/>
<xs:attribute name="value" use="required"/>
</xs:complexType>
</xs:element>
<xs:element name="stats">
<xs:complexType>
<xs:sequence>
<xs:element ref="timeseries:question"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="question">
<xs:complexType>
<xs:sequence>
<xs:element maxOccurs="unbounded" ref="timeseries:stat"/>
</xs:sequence>
<xs:attribute name="Desc" use="required"/>
<xs:attribute name="name" use="required" type="xs:NCName"/>
<xs:attribute name="type" use="required" type="xs:NCName"/>
<xs:attribute name="url" use="required"/>
</xs:complexType>
</xs:element>
<xs:element name="stat">
<xs:complexType>
<xs:attribute name="allvalue" type="xs:integer"/>
<xs:attribute name="myvalue" type="xs:integer"/>
<xs:attribute name="name" use="required" type="xs:NCName"/>
<xs:attribute name="period" use="required"/>
<xs:attribute name="type" use="required" type="xs:NCName"/>
<xs:attribute name="value" type="xs:integer"/>
</xs:complexType>
</xs:element>
</xs:schema>
Sample XML Response
<?xml version="1.0" encoding="UTF-8"?>
<report url="https://episurveyor.org/superrosa/analysis/timeseries/ " title ="Time Series" xmlns="http://episurveyor.org/superrosa/analysis/timeseries/">
<params>
<param name="questionid" value="1292"/>
<param name="startdate" value="2009-08-10"/>
<param name="enddate" value="2009-08-15"/>
<param name="username" value="gnjuguna@datadyne.org"/>
</params>
<stats>
<question name="diseases" Desc="Which diseases have you ever suffered from?" type="multicheckbox" url="" >
<stat name="Malaria" type="count" period="1/1/2010" myvalue="10" allvalue="10" />
<stat name="Measles" type="count" period="1/1/2010" myvalue="5" allvalue="10" />
<stat name="TB" type="count" period="1/1/2010" value="5" />
<stat name="Malaria" type="count" period="1/2/2010" myvalue="10" allvalue="10" />
<stat name="Measles" type="count" period="2/1/2010" myvalue="5" allvalue="10" />
<stat name="TB" type="count" period="1/2/2010" myvalue="5" allvalue="15" />
</question>
</stats>
</report>
Collector Reports
Description
This method returns a summary of number of records collected per user.
URL:
https://episurveyor.org/superrosa/analysis/colectorreports/
Available Formats
• XML
HTTP Method:
POST.
Parameters
- surveyid(Required):
- startdate(Required):
- enddate(Required):
- username(Required)
- password(Required)
XML Schema
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" targetNamespace="https://episurveyor.org/superrosa/analysis/collectorreports/" xmlns:c="https://episurveyor.org/superrosa/analysis/collectorreports/">
<xs:element name="report">
<xs:complexType>
<xs:sequence>
<xs:element ref="c:params"/>
<xs:element ref="c:stats"/>
</xs:sequence>
<xs:attribute name="title" use="required"/>
<xs:attribute name="url" use="required" type="xs:anyURI"/>
</xs:complexType>
</xs:element>
<xs:element name="params">
<xs:complexType>
<xs:sequence>
<xs:element ref="c:param"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="param">
<xs:complexType>
<xs:attribute name="name" use="required" type="xs:NCName"/>
<xs:attribute name="value" use="required" type="xs:integer"/>
</xs:complexType>
</xs:element>
<xs:element name="stats">
<xs:complexType>
<xs:sequence>
<xs:element maxOccurs="unbounded" ref="c:stat"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="stat">
<xs:complexType>
<xs:attribute name="fsdate" use="required" type="xs:NMTOKEN"/>
<xs:attribute name="lsdate" use="required" type="xs:NMTOKEN"/>
<xs:attribute name="name" use="required" type="xs:NCName"/>
<xs:attribute name="type" use="required" type="xs:NCName"/>
<xs:attribute name="username" use="required"/>
<xs:attribute name="value" use="required" type="xs:integer"/>
</xs:complexType>
</xs:element>
</xs:schema>
Sample XML Response
<?xml version="1.0" encoding="UTF-8"?>
<report url="https://episurveyor.org/superrosa/analysis/collectorreports" title ="Collector Reports" xmlns="https://episurveyor.org/superrosa/analysis/collectorreports/">
<params>
<param name="surveyid" value="1292"/>
</params>
<stats>
<stat name="Count" type="count" username="gnjuguna@datadyne.org" value="10" fsdate ="2008-1-1" lsdate="2008-10-10" />
<stat name="Count" type="count" username="yibrahim@datadyne.org" value="20" fsdate ="2008-1-1" lsdate="2008-10-10" />
<stat name="Count" type="count" username="solomonkariri@datadyne.org" value="10" fsdate ="2008-1-1" lsdate="2008-10-10" />
<stat name="Count" type="count" username="geraldmutuhu@datadyne.org" value="10" fsdate ="2008-1-1" lsdate="2008-10-10" />
</stats>
</report>
</report>
HTTP Status codes:
200 -when a requested was executed successfully
400 BAD REQUEST'- When required parameters are missing or are formatted incorrectly.
401 UNAUTHORIZED - When a request fails authentication.
Errors
<?xml version="1.0" encoding="UTF-8"?>
<error xmlns="">
<errormessage> Invalid username and/or password.<errormessage/>
</error>
Notes
The URLs specified are specific to episurveyor.Other OpenRosa compliant servers can have different URLs.
Questions
- What values should be returned ie actual values vs percentages.
- Elements vs Attributes.
Updated