Accessing Data via API

IN THIS ARTICLE
API Overview
Object-Based APIs
How to access the API
    COMMAND LINE (CURL)
    PYTHON (with requests)
    JAVASCRIPT (with node's https)
API Endpoints
    API Keys
    Pagination
Event Types
Specialized Data Needs
    Attendance Tracking
    Community Health Scores from API Data

API Overview

In addition to the Yellowdig Engage Web Application, Yellowdig also supports a publicly accessible API that users may use to download data for a wide variety of use cases. Yellowdig’s API allows users to pull fine-grained data—including attendance data, post and comment content, point-earning events, and other engagement metrics—from Communities to which they have access as an Owner, Facilitator, or Network Administrator. This makes the API useful for data analytics, attendance tracking, bulk data export, and more. Currently, the API is designed for read-only access, allowing for the downloading of platform-generated data, but does not enable data modification. This helps avoid any possibility of a bad actor modifying YD data and also makes it “safe” for relative API novices to use the API without any worry of accidentally deleting or modifying data.

For network administrators, Yellowdig’s APIs provide the easiest and most flexible way to pull your organization's data to understand student and instructor behavior. Though various reports do exist inside the platform for both the community and network levels, these have more limitations than what can be accessed from the APIs. The APIs are the only always-available, self-service way for client organizations to access their data at the most granular level, compile it, and analyze it as they see fit for research and reporting purposes.

---

Object-Based APIs

Yellowdig’s APIs are all framed around data calls that return “event objects” related to user behaviors.  Each event object type is indicative of something a student or instructor did within the platform.  For example, each time a student views a post a “post view” is recorded in our system which can be requested from the API.  The post view object that can be accessed from the API will include important information such as the actor that logged the view, the post that was viewed, who created the post that was viewed, what community and sub-organization the view was logged in, and a series of other attributes that will allow you to understand the context in which the view happened (e.g., the date/time).  Similar event objects are created for most events that can occur within Yellowdig (e.g., posts, comments, reactions, accolades, etc.) and their properties vary based on the type of event.  For example, posts do not reply to another user so there would be no information about a post action being in response to another user.  Likewise, a post or comment object would contain the exact contents of the post or comment but a view would not have any “content”.

For an extremely detailed analysis of individual communities, the event objects allow you to understand very granular detail all the way down to the exact content of individual student or instructor interactions (e.g., doing sentiment analysis on language used in the platform, mapping out network interactions between students, keeping track of student attendance, or noting the last time any student or instructor participated in Yellowdig).  

These same data can be stored and are typically aggregated to answer questions all the way up to the full organization level.  For example, the data can be used to answer: “How many instructors created communities for Yellowdig this term?”  Or you can ask questions about improving outcomes like: “How many instructors are commenting at least once per week in Yellowdig and where we work to increase that number to build instructor presence, are those efforts actually influencing instructor behavior?  Where instructor commenting is increasing, are we seeing students participate more?”

---

How to access the API

To consume the Yellowdig API, you will need to generate an API key. The amount of data to which you will have access is determined by the permissions and roles associated with your Yellowdig account.

To generate an API key, go to User Options → Account Settings → API Keys → GENERATE KEY. To copy your API key to the clipboard, click on the double paper icon.

Do not share your keys with anyone else. You are liable for protecting your API keys. To ensure data security, we recommend deleting keys you're no longer using by clicking the x button next to the key.

 

- Yellowdig's API is hosted at data.yellowdig.app

- Consult our technical API documentation: https://data.yellowdig.app/docs/index.html

- An example collection for Postman, an API platform, can be found here

 

See below for samples of API calls in a few different languages: 

COMMAND LINE (CURL)

curl -H 'apikey: your_key'\ 
https://data.yellowdig.app/your_route_and_params

PYTHON (with requests)

import requests
headers = {'apikey': 'your_key'}
requests.get('https://data.yellowdig.app/your_route_and_params', 
             headers=headers).json()

JAVASCRIPT (with node's https)

const http = require('https');

let options = {
  host: 'data.yellowdig.app',
  path: 'your_route_and_params',
  headers: {'apikey': 'your_key'}
};

callback = function(response) {
  let str = '';
  response.on('data', function(chunk) {
    str += chunk;
  });
};

http.request(options, callback).end().data

 

---

API Endpoints

The API readily supports the following operations:

• Listing community events
• Listing network events
• Finding the latest and earliest actions in a community per member
• Listing community points earned per member
• Listing the communities in a network
• Listing certain community stats 

API Keys

It will be necessary for anyone trying to use the APIs to generate an API key (instructions above). That key can be used to test the APIs and will be necessary to retrieve the level of data required. You must have an existing Yellowdig account to generate an API key. Once you’ve created an API key, it will need to be supplied as the “apikey” HTTP header to authenticate requests. Yellowdig’s API uses the incoming API key to identify the associated user. The permissions of the API request correspond to the identified user’s existing access to data within the Yellowdig application so any user can only access data from the API that they already have access to within Yellowdig. For example, suppose a user is an owner for three distinct Yellowdig communities. In that case, their API key can fetch data about those communities but not any other communities. However, if the associated user is a network administrator, their key can request information about any community within the organizational network that they oversee.  For example, a department head for Psychology who is an administrator of their department’s Yellowdig sub-organization would be able to access all data from communities placed within the Psychology sub-organization, but could not access data from communities in the Chemistry sub-organization.

Pagination

Users may generate hundreds of thousands of events within a Yellowdig community, so Yellowdig’s API enforces a pagination model to ensure that each request is limited in size. Most API routes return data in the following shape:

 

{

  "data": Array // a list of records
  "limit": Number // the user supplied limit of records

  "record-count": Number // the number of records in the "data" key

  "at-end": True|False. // indicates if more records exist 

}

This means that to download every event within a community, API users must make a series of HTTP requests until the at-end parameter indicates that all records have been consumed. Usually, this is achieved using the limit and offset parameters, or by supplying the start parameter to step forward by time. Note that the maximum quantity of records (limit) returned in a request is 250.

---

Event Types

The following events are tracked in Yellowdig and are currently available as event objects: 

 

 

---

Specialized Data Needs

Attendance Tracking

Yellowdig’s API supports two routes that are tailored for attendance tracking use cases: 

/network/:network-name/community/:community-id/earliest-events

/network/:network-name/community/:community-id/latest-events

These routes return a record for each member of the community indicating their earliest or latest event accordingly. Customers wishing to continually track attendance may request these routes daily to confirm which learners are participating in Yellowdig. Refer to the API documentation for more information on supported event filters

 

Community Health Scores from API Data

As currently built, the above APIs are focused around events and therefore do not currently aggregate and return community health data, which is often of interest to our partners. The following information about Health Scores is being provided to help you understand how the community health scores currently available within the “Health Check” area of each community are calculated.  As noted on some of these metrics, the current API would not easily support calculating some of these, but the others could be aggregated to allow easier comparisons of community performance and to create a way to identify particularly active and engaging communities to learn from those successes.

Each composite score for Listening, Interacting, and Sharing in the platform is a simple average of the percentile scores of each of the constituent metrics that appear there.  These constituent metrics are what appear below each composite score in the platform when you click on them.

Listening

• Conversation ratio - The total number of comments in the course divided by the total number of posts in the course.
• Avg # of posts viewed - The total number of times posts have been viewed, divided by the number of members in the course, divided by the number of days since the course start date.
• [Not currently available] Avg # of hyperlinks clicked - The total number of times hyperlinks shared in the course have been clicked, divided by the number of members in the course, divided by the number of days since the course start date.

Interacting

• Avg # of reactions given - The total number of reactions added to posts in the course, divided by the number of members in the course, divided by the number of days since the course start date.
• Avg # of connections - The total number of (comments, reactions, and mentions) divided by the number of members in the course.
• [Possible but currently cumbersome] % of posts with 1 or more comments - We consider a post to be "orphaned" if it never received any comments. This metric is calculated as 1 - (<number of orphaned posts in the course> / <total number of posts in the course>).
• [Partially available] % of connected users - The total number of members who have either been mentioned in a post or received a comment from another member on their post, divided by the total number of members in the course.  Mentions are not an action exposed in the current API but it would be possible to compute how many users received a comment from another member using the event/actor or post/parent information.

Sharing

• Avg # of posts - The total number of posts in the course, divided by the number of members in the course, divided by the number of days since the course start date.
• Avg # of comments - The total number of comments in the course, divided by the number of members in the course, divided by the number of days since the course start date.
• Avg total word count - The total number of words written in posts or comments in the course, divided by the number of members in the course, divided by the number of days since the course start date.
• [Not currently available] Avg # of links shared - The total number of hyperlinks shared in the course, divided by the number of members in the course, divided by the number of days since the course start date.
• [Not currently available] Avg # of multimedia items shared - The total number of attachments or drawings shared in the course, divided by the number of members in the course, divided by the number of days since the course start date.

 

Audience: This help article is for Instructors, Designers, and Administrators. Students or Learners cannot access these settings.