On-site data access

Once a member authorizes data sharing, you'll be able to immediately access that data via our API.

Topics:

• Project member endpoint
• Master access tokens
• Master access token endpoint
• Project information

API data access: Project member endpoint

Using access tokens for specific users, OAuth2 projects can use this endpoint to:

• retrieve the user's project member ID
• access other data associated with the project member

The way to use this endpoint is to send a secure GET request ('https') to the following URL with the access_token parameter set to the project's "master access token" and the project_member_id set to the project member's "project member id".

This returns JSON-formatted data that can be used to programmatically access and retrieve data files and other information for this specific project member. Data file information is paginated and, by default, lists a maximum of 100 data files. The returned JSON includes: "count", which is the total number of data files, "next", the URL for the next page of data files (if there are more to be listed), and "previous", the URL for the previous page of data files (if one exists).

Master access tokens

Each project has a "master access token" used for API calls. This token is a password for your project.

To find the token, your project management page and click on your project's name. The master access token should be listed in your project's details.

Keep this token PRIVATE.

• Do NOT publicly share this token.
• Do NOT share this token in an unsecured manner.
• NEVER put this token into a git repository.

This token is used to authorize the following:

• API access to any private data shared with your project
• sending messages to project members via API
• uploading data for project members via API

If you ever believe the security of this token may have been compromised, contact us at support@openhumans.org and we'll reset it to a new value.

When using this token in programs, we recommend you do NOT store it. You should enter the token each time you run your software.

If you want to have fully automated API transactions with Open Humans, you should use OAuth2 endpoints with user-specific access tokens.

API data access: master access token endpoint

To access private data shared with your project, send a secure GET request (using 'https') to /api/direct-sharing/project/members/ with the access_token parameter set to your project's "master access token". This returns JSON-formatted data with a list of the project's members as well as the first ten files that member has shared with the project. In addition, it provides: file_count, which tallies the total number of files the member has shared with the project, as well as exchange_member, which has a link to that member's exchange api endpoint, providing access to the full set of files. For more information on this endpoint, please see the exchange-member endpoint documentation.

For example:

https://www.openhumans.org/api/direct-sharing/project/members/?access_token=<MASTER_ACCESS_TOKEN>

This returns JSON formatted data that can be used to programmatically access and retrieve data and files for your project members.

Example API query results

For example, the following result comes from project that requests RunKeeper data access and has a single member authorized.

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "created": "2016-04-11T19:50:49.041825Z",
      "project_member_id": "76676885",
      "message_permission": false,
      "username_shared": false,
      "sources_shared": [
        "runkeeper"
      ],
      "username": null,
      "data": [
        {
          "id": 5915,
          "basename": "Runkeeper-activity-data-2016.json",
          "created": "2016-05-19T18:33:10.513837Z",
          "download_url": "https://open-humans-production.s3.amazonaws.com/member-files/runkeeper/d41ca013-8adc-44b2-eaf1-c229140d3f17/Runkeeper-activity-data-2016.json?Signature=phQ3qEf4KFvOdzTrBGvZZ%2bBKp8x%3D&Expires=1467284379&AWSAccessKeyId=AKIAIKOUJTDFSTN6P7GA",
          "metadata": {
            "tags": [
              "GPS",
              "Runkeeper"
            ],
            "complete": false,
            "dataYear": 2016,
            "description": "Runkeeper GPS maps and imported activity data."
          },
          "source": "runkeeper"
        }
      ]
    }
  ]
}

Download URLs

Data files for members can be retrieved using the download_url information. These URLs are temporary authorizations that will expire. You should use a program to immediately to retrieve the data files you need.

Pagination

The API uses pagination via the offset querystring parameter; the default page size is 100 results. A smaller or larger page size can be specified with the limit parameter.

API data access: Project information

Master access tokens can also be used to retrieve information about the project they are related to.

To use this endpoint, send a secure GET request (using 'https') to the following URL with the 'access_token' parameter set to access token:

https://www.openhumans.org/api/direct-sharing/project/?access_token=<ACCESS_TOKEN>

This returns JSON-formatted data related to the project itself.