1. JavaRosa Team Dimagi Avatar JavaRosa Team Dimagi
  2. javarosa
  3. javarosa

Wiki

Clone wiki

javarosa / SuperRosaAPI

View History

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

  1. What values should be returned ie actual values vs percentages.
  1. Elements vs Attributes.

Updated