Today we have launched our data download and API feature, which can be activated within the app after updating to version 1.1.

This post describes the API. If you don’t know what an API is, it’s probably safe to ignore it.

Data endpoints

Participants’ data is available in a number of formats, from the following endpoints:

Each row of the XLS and CSV files, and each object of the JSON array, represents one response. They are listed in descending start time order, so the first row or Object corresponds to the most recent response.

Both JSON and CSV data are UTF-8 encoded. CSV columns are (unsurprisingly) comma-separated, CSV rows terminate with Unix line-endings (\n), and CSV strings are unquoted except when empty or in the case of embedded commas or newlines.

The content of the JSON, CSV and XLS formats is described further in the data dictionary.

Except where noted, the content of this guide applies to all formats, but the JSON and CSV formats are likely to be most useful.

Requests

All API requests are HTTP GET requests over a secure (https) connection. The first path component(s) of an API request URL identify and authenticate the participant whose data is requested, so that request URLs take this form:

https://mappiness.me/authentication_data/endpoint

Two kinds of authentication data are supported. The first is dealt with next; the second is explained in the last section of this guide.

Except in the case of JSON endpoint requests, supplying incorrect authentication data will return an HTML error page. For JSON endpoint requests, incorrect authentication data will produce the JSON response {"error":"bad_secret"}, wrapped in a callback (for JSON-P) if one was specified.

Universal authentication with API secret

The link provided within the app when data download is turned on incorporates the participant’s API secret, which is of the form xxx.xxxx.xxxx — for example, 3kkq.pk7d.23wb. More precisely, API secrets match this regular expression:

[23456789bcdfghjkmnpqrstvwxyz]{1,6}[.][23456789bcdfghjkmnpqrstvwxyz]{4}[.][23456789bcdfghjkmnpqrstvwxyz]{4}

The characters before the first dot (3kkq above) identify the participant. The remaining characters are randomly generated, and change each time data download is turned on.

The API secret can be used to authenticate any API request. For example, the following request (with the correct API secret) will return all data in JSON format:

https://mappiness.me/3kkq.pk7d.23wb/mappiness.json

Parameters

The API supports several request parameters to limit the data returned, which are appended to the URL in the usual way (?key1=value1&key2=value2 and so on).

limit=n

This limits the number of responses returned to the n most recent.

For example, the request URL

https://mappiness.me/3kkq.pk7d.23wb/mappiness.json?limit=1

returns the most recent response only.

This parameter is supported by all endpoints.

offset=n

This causes the first n most recent responses to be skipped.

For example, the request URL

https://mappiness.me/3kkq.pk7d.23wb/mappiness.json?limit=1&offset=1

returns the second most recent response only.

This parameter is supported by all endpoints.

before=epoch

This restricts the responses returned to those started before the date/time supplied. The epoch is an integer interpreted as the number of seconds since 1 January 1970.

For example, the request URL

https://mappiness.me/3kkq.pk7d.23wb/mappiness.json?before=1304204400

returns all responses completed before 1 May 2011.

This parameter is supported by all endpoints.

after=epoch

This restricts the responses returned to those started after the date/time supplied. Again, the epoch is an integer interpreted as the number of seconds since 1 January 1970.

For example, the request URL

https://mappiness.me/3kkq.pk7d.23wb/mappiness.json?after=1304204400

returns all responses completed after 1 May 2011.

This parameter can be used to poll for new responses. In that case the epoch value supplied should match the latest start_epoch value previously seen within a response.

This parameter is supported by all endpoints.

include=column_list

This limits the columns or JSON keys returned to those named in column_list, which is comma-separated. The * character can be used as a wildcard at the end of name fragments, and matches 1 or more characters.

For example, the request URL

https://mappiness.me/3kkq.pk7d.23wb/mappiness.json?include=happy,do_*

returns the happiness value and all activity indicators for each response.

This parameter is supported by the JSON, CSV and XLS endpoints.

callback=global_js_function_name

This wraps a JSON response in a function callback, to produce a JSON-P response for cross-domain browser-initiated API queries.

For example, the request URL

https://mappiness.me/3kkq.pk7d.23wb/mappiness.json?include=happy&limit=1&callback=setHappiness

returns only the most recent happiness value, looking something like this:

setHappiness([{"happy":0.620482}]);.

This parameter is supported by the JSON endpoint only.

Link-specific authentication with HMACs

If requests could only be authenticated using the API secret, then granting access to any of a participant’s data — for example, a photo, a single response data set, or even a single happiness value — would inevitably entail granting access to all his or her data. This might lead to inadvertent data sharing, and would probably preclude use of the API for JSON-P requests from the public web.

Therefore, to enable granting of access to limited subsets of the data only, any specific API URL can alternatively be authenticated using a unique string incorporating a hash-based message authentication code (HMAC). This code will only authenticate the exact individual API URL for which it was generated.

HMAC API authentication strings take the form u/xxx.xxxxxxxxxxxxxxxxxxxxxxxxxxxx — for example, u/3kkq.6641a7e8278bcd49e476e7acae15. More precisely, the strings match this regular expression:

u/[23456789bcdfghjkmnpqrstvwxyz]{1,6}[.][0-9a-f]{28}

The characters after u/ and before the first dot (3kkq above) identify the participant as before.

Like the API secret, all HMAC authentication strings — and thus the URLs of which they are part — change each time the participant turns data download on. (Note that when data download is turned off by a participant, neither form of authentication can provide access to their data through the API).

API-generated URLs that do not provide access to all data, such as links to photos and map locations, are automatically generated using HMAC authentication strings. For example, these two URLs might be provided in an API response for access to two specific photos:

https://mappiness.me/u/3kkq.a1d9840a7d6e6f9a6c13f2b7802f/private_photos/3.jpg

https://mappiness.me/u/3kkq.2727e5a04d8acc225b3320799348/private_photos/8.jpg

Generating HMAC-authenticated URLs

The HMAC keys include the participant’s API secret, but they also contain other participant-specific and non-participant-specific elements. For this reason, only the Mappiness API is able to generate HMAC-authenticated URLs.

Therefore, we provide a special API endpoint for this purpose. This endpoint accepts authentication only via API secret.

To use this endpoint to retrieve the HMAC-authenticated version of any API request URL in JSON format, insert get_u/ into that URL immediately before the API secret.

For example, a request URL like this:

https://mappiness.me/get_u/3kkq.pk7d.23wb/mappiness.json?include=happy&limit=1&callback=setHappiness

gives a response like this:

{"url":"https://mappiness.me/u/3kkq.21f8861d6df137bb07d47c0fec31/mappiness.json?include=happy&limit=1&callback=setHappiness"}

To add a callback (for JSON-P), insert get_u.global_js_function_name/ immediately before the API secret instead.

For example, a URL like this:

https://mappiness.me/get_u.receiveURL/3kkq.pk7d.23wb/mappiness.json?include=happy&limit=1&callback=setHappiness

returns this sort of JSON-P response:

receiveURL({"url":"https://mappiness.me/u/3kkq.21f8861d6df137bb07d47c0fec31/mappiness.json?include=happy&limit=1&callback=setHappiness"});

Feedback

Please don’t hesitate to get in touch with queries or comments, using our contact details on the main website.

Finally, please note that we can’t promise that elements of the API won’t change in future.