Data Foundry APIs

The Data Foundry has several Application Programming Interfaces (APIs) that you can use.

Which API should you use?

Before you dive in and find out what the different APIs can do for you, think about what you actually need.

  • Do you want to download a dataset with an external software or create a prototype that works with a fresh copy of the dataset? Ok, then you should read the section about dataset APIs (just below).
  • Do you want to add to an IoT dataset or read and modify items in an Entity dataset from a prototype or external software? Or do you want to create a web application that stores user profiles or other items in a database (= Entity dataset)? Also in these cases you should be fine with the dataset API.
  • Do you want to create a web application for anonymous visitors or participants in a study to do something? On top of the dataset API, you might want to check out the participant API.
  • Do you want to create a tool that can create projects, datasets and project resources on behalf of a user? So, a user would log in, grab a token, and allow the tool to control Data Foundry? Ok, check out the v2 API below.
  • Do you want to create a new platform that needs to be able to register users and let users log in via a separate screen? Or do you want to use Data Foundry to authenticate users in your own platform? Then you would need the v1 API -- but be aware that we would need to talk first to give you this much access. ;-)

The first three types of API access to Data Foundry are self-service, so you can just create access for yourself and your collaborators. The last two types of access require a specific API token, for which you would need to contact us.

Dataset API

Let's start with the easiest API access: dataset access. Every dataset that is created on Data Foundry has it's own basic access API -- and a few dataset types have even more.

If you browse to any dataset page in one of your projects, you will find a "configuration" section in the lower half of the dataset page. This section contains the "CSV Token Link" tab. Here you can generate dataset-specific tokens and token links that allow you to download the dataset from external applications or your own code without having to be logged into Data Foundry. For example, if you would want to work with a dataset in a Python program and you grab a fresh copy of the data on program start, this is the way. (Why? Because Python would not know that you are logged into DF in your browser, nor would it be able to do this by itself easily.)

With the token links you can either download a CSV file of the dataset, which is directly usable in tools like Excel, R Studio, Python, Processing, etc. You can also download a JSON file of the dataset which is great for JavaScript or Node.js applications, visualization with D3.js and other tools.

This is not all: apart from the token link access that all datasets work with, there are special APIs for IoT, Entity and Media datasets. For example, if you have an IoT dataset, you can generate an separate token to log items into the dataset from external applications or your own software. For Java software such as Processing and embedded platforms, we even have libraries to allow for easy logging from within your code. You just need the token from the dataset page.

For Entity datasets, you can do even more: with a generated token, you can add, read, modify and delete individual items in the dataset. The access to items is very granular, so you can even build moderately complex web applications with this API access. Try it and contact us, if you need to know more.

For Media datasets, you can upload photos and images from an external program with this API. Just generate a token in the configuration tab and follow the example underneath the token form.

Participant API

Let's say you want to run a study with participants (or with anonymous visitors) and they need to accomplish a task on a webpage. You probably know already that you can just host the webpage in an Existing dataset. Also, you can make use of the Participant API that allows the JavaScript code on the webpage to access information about the currently visiting participant, and more: you can log data in an IoT dataset (if available in the same project), store diary entries for this participant, upload images or photos, and even access previously stored data by the participant. This allows to realize quite complex online studies. The API for accessing participant-specific data can also be used to create participant study dashboards. It supports both pre-registered participants and anonymous/unregistered participants.

Platform API v2

The newest version of the Platform API is v2. It allows to build tools that rely on the Data Foundry as a storage and automation backend. All actions in this API are available from a DF user perspective. Users of the tool that uses this API need to enter their own token to give the API access. Check out the API documentation!

Platform API v1

The older version of the Platform API is v1 and it is designed for two purposes:

  • allowing for the design and implementation of different front-ends with the DF backend
  • allowing for authenticating users from Data Foundry in other applications

Check it out here!