Tableau API

There are two API endpoints. Both use:

• API keys: These are different from the API keys used to download data. You generate an API key by going to the Manage Credentials page, under "New Credentials", and copying the Access Key and Secret Key that appear at the top of the page. The Secret Key will never be displayed again, so make sure you copy it somewhere!
• Study IDs: The way you reference a study (<study_object_id>) is the 24-character random string visible on the View Study page, right under the study's name.

Tableau Web Data Connector (WDC) API endpoint

Path: /api/v0/studies/<study_object_id>/summary-statistics/daily/wdc

This is designed to only be accessed from Tableau.

More documentation needed on how to set that up.

JSON API endpoint

Path: /api/v0/studies/<study_object_id>/summary-statistics/daily

Basic usage

You must pass your Access Key and Secret Key in via the headers X-Access-Key-Id and X-Access-Key-Secret.

You can call this endpoint using cURL. For the studies.beiwe.org deployment, here's how you'd pull all summary statistics from an entire study:

curl "https://studies.beiwe.org/api/v0/studies/<study_object_id>/summary-statistics/daily" -H "X-Access-Key-Id: abcd..." -H "X-Access-Key-Secret: efgh..."

Filtering

You can filter by date, participant ID, and which fields you want. This will make the query run faster. If the API query takes longer than 60 seconds to run, you'll get a 504 timeout error instead of a response. Add filters as GET parameters to the URL, using standard URL parameter format (add the first param to the URL like this: ?<parameter_name>=<parameter_value>, and all subsequent parameters like this: &<parameter_name>=<parameter_value>.

• Start date: start_date. Must be in YYYY-MM-DD format. Example: ?start_date=2021-03-15
• End date: end_date. Must be in YYYY-MM-DD format. Example: ?end_date=2021-04-01
• Participant IDs: participant_ids. Comma-separated list, with no other characters wrapping the list or each item. Example for two participant IDs: ?participant_ids=ouq7r382,r3h9qp2o.
• Fields: fields. Comma-separated list. Example: &fields=date,participant_id,accelerometer_bytes,distance_from_home

Example usage: let's say we want to get data from the study with ID "R69zae1Y7Lw6yuwVUR4BOALY", for March 15, 2021 through April 1, 2021, for participant "ouq7r382", and we only want the values of "accelerometer_bytes" and "distance_from_home". Here's how to make that API call with cURL:

curl "https://studies.beiwe.org/api/v0/studies/R69zae1Y7Lw6yuwVUR4BOALY/summary-statistics/daily?start_date=2021-03-15&end_date=2021-04-01&participant_ids=ouq7r382&fields=date,participant_id,accelerometer_bytes,distance_from_home" -H "X-Access-Key-Id: abcd..." -H "X-Access-Key-Secret: efgh..."