Formhub Access Points (API)

formhub.org offers various access points to the form and data stored on formhub. Most of the access points refer to a user name and a form name, which I will denote as USERNAME and FORMNAME below:

(All access points use HTTP GET unless otherwise specified):

Authentication

All the access points discussed below support basic authentication using the Authorization header of the request. This allows you to retrieve the data using external applications.

E.g. To use curl to access csv data from the command line:

curl -u <USERNAME>:<PASSWORD> http://formhub.org/<USERNAME>/forms/<FORMNAME>/data.csv

form access points

XLS, XML and JSON forms:

https://formhub.org/USERNAME/forms/FORMNAME/form.FILETYPE

where FILETYPE can be xml, xls or json

JSONP form:

https://formhub.org/USERNAME/forms/FORMNAME/form.json&callback=CALLBACKFN

data access points

XLS and CSV Outputs

The xls and csv are more or less raw data outputs, where all the fields correspond to the "name"s specified in the xls form.

https://formhub.org/USERNAME/forms/FORMNAME/data.FILETYPE

where FILETYPE is xls or csv.

XlS data outputs have:

1. repeats broken out to a separate sheet
2. (currently) groups broken out to a separate sheet each

CSV data outputs have:

1. All data in one big sheet
2. GPS points broken out. If the name of a geopoint field is geopoint_field, four additional data fields name geopoint_field_latitude geopoint_field_longitude geopoint_field_precision and geopoint_field_altitude will be present in the sheet.
3. Repeats in the same sheet, (currently) upto four repeat elements are output. Each repeat element has a suffix after the name: [1], [2], [3], [4], etc.

KML Outputs

The kml output can be fed into google earth, and gives a view very similar to the map view on formhub--the question names are replaced by the text of the question.

https://formhub.org/USERNAME/forms/FORMNAME/data.kml

Parameters for data access

Date filter

start and end date must be formatted as YY_MM_DD_hh_mm_ss, both are optional and will filter inclusively. The below query returns results from January 1st 2011 at 00:00 and 00 seconds until December 31st at 23:59 and 59 seconds.

 https://formhub.org/USERNAME/forms/FORMNAME/form.FILETYPE?start=11_01_01_00_00_00&end=11_12_31_23_59_59

Raw file

A request like

https://formhub.org/USERNAME/forms/FORMNAME/data.kml

will usually result in a redirect, and the downloaded filename will have the current date attached to it (which helps you track when you downloaded submissions last). However, for programmatic purposes, if you want the raw file, and no redirects, you can add a raw=1 to the URL parameter list, like:

https://formhub.org/USERNAME/forms/FORMNAME/data.kml?raw=1

JSON Outputs

Formhub includes an API that provides the form data as JSON. This is primarily used through javascript by the various data views including the map and the data grid views.

Accessing

https://formhub.org/USERNAME/forms/FORMNAME/api

will give you back all the data submitted to the form in the JSON format.

API Parameters

The JSON data api also accepts a number of parameters which should be passed to the URL as GET parameters and appropriately URL encoded. The parameters are specified using the mongodb syntax:

http://www.mongodb.org/display/DOCS/Querying

query parameter

Use query parameter to specify a filter criteria. It should be specified using url encoded curly braces. In javascript, using jquery as an example, the call would look like this

$.getJSON('https://formhub.org/USERNAME/forms/FORMNAME/api', {'query': '{"age": "31"}'})

As an encoded url, this would translate into:

https://formhub.org/USERNAME/forms/FORMNAME/api?query=%7B%22age%22%3A+%2231%22%7D

start and limit parameters

Use the start parameter to skip a number of records and the limit parameter to limit the number of records returned.

JQuery calls:

$.getJSON('https://formhub.org/USERNAME/forms/FORMNAME/api', {'start': '3'})

$.getJSON('https://formhub.org/USERNAME/forms/FORMNAME/api', {'limit': '10'})

$.getJSON('https://formhub.org/USERNAME/forms/FORMNAME/api', {'start': '3', 'limit': 10})

URL encoded equivalents:

https://formhub.org/USERNAME/forms/FORMNAME/api?start=3

https://formhub.org/USERNAME/forms/FORMNAME/api?limit=10

https://formhub.org/USERNAME/forms/FORMNAME/api?start=3&limit=10

fields parameter

Use to specify which fields to return. Is specified using url encoded square braces.

JQuery call:

$.getJSON('https://formhub.org/USERNAME/forms/FORMNAME/api', {'fields': '["name", "age"]'})

URL encoded equivalent:

https://formhub.org/USERNAME/forms/FORMNAME/api?fields=%5B%22name%22%2C+%22age%22%5D

NOTE: the _id field is always returned as well.

count parameter

Use the count parameter to get the number of records returned by the call to the API. You can use this to get the number of records that meet a certain criteria. The value should be a number greater that zero to retrieve the count or zero or unspecified to retrieve the actual records.

JQuery call:

$.getJSON('https://formhub.org/USERNAME/forms/FORMNAME/api', {'query': '{"age": 31}', 'count': '1'})

URL encoded equivalent:

https://formhub.org/USERNAME/forms/FORMNAME/api?query=%7B%22age%22%3A+31%7D&count=1

sort parameter

Use the sort parameter to specify the field to order the returned set of records by and the direction of the sort i.e. ascending or descending. This is specified by enclosing the field and sort direction in url encoded curly braces where 1 denotes an ascending sort while -1 denotes a descending sort.

JQuery call:

Sort by age descending:

$.getJSON('https://formhub.org/USERNAME/forms/FORMNAME/api', {'sort': '{"age": -1}'})

URL encoded equivalent:

https://formhub.org/USERNAME/forms/FORMNAME/api?sort=%7B%22age%22%3A+-1%7D

Sort by age ascending:

$.getJSON('https://formhub.org/USERNAME/forms/FORMNAME/api', {'sort': '{"age": 1}'})

URL encoded equivalent:

https://formhub.org/USERNAME/forms/FORMNAME/api?sort=%7B%22age%22%3A+1%7D

TIP: You can use the chrome browser's console to get the url encoded equivalents by running the jquery call