Introduction

# API Base URL
https://api.sustainability.oregonstate.edu/v2/

This document aims to provide you with public access to the APIs built by the OSU Sustainability Office. These APIs support our:

Energy Dashboard
Carbon Calculator
Sustainability Map (Coming Soon!)

Authentication

The authentication API allows our applications to authenticate users with CAS, using their ONID credentials. For more information about CAS at Oregon State University, refer to this document.

Users must navigate to https://api.sustainability.oregonstate.edu/v2/auth/login to begin the authentication process. Optionally, a return URI can be specified: https://api.sustainability.oregonstate.edu/v2/auth/login?returnURI=https://myco2.sustainability.oregonstate.edu/#/. The return URI parameter specifies a destination for the user once they have authenticated with ONID.

A typical login looks like this:

The user navigates to the Carbon Calculator homepage at https://myco2.sustainability.oregonstate.edu/#/
The user clicks the "Sign In" button. Their browser is redirected to https://api.sustainability.oregonstate.edu/v2/auth/login?returnURI=https://myco2.sustainability.oregonstate.edu/#/
The user successfully authenticates with CAS using ONID and Duo
The OSU Sustainability Office's authentication API stores a JSON Web Token (JWT) cookie in the user's browser
The user's browser is redirected to the specified return URI (in this case, it is https://myco2.sustainability.oregonstate.edu/#/)
Subsequent API calls are made using the JWT.

Logout

Simply direct the user's browser to https://api.sustainability.oregonstate.edu/v2/auth/logout. They will be securely logged out of ONID.

Carbon Calculator

The base URL for the Carbon Calculator's API is https://api.sustainability.oregonstate.edu/v2/carbon. The following routes can be accessed by appending the endpoint to the base URL (ie: https://https://api.sustainability.oregonstate.edu/v2/carbon/category...

Get Categories

# Request all categories
curl "https://api.sustainability.oregonstate.edu/v2/carbon/category"

# Request a specific category
curl "https://api.sustainability.oregonstate.edu/v2/carbon/category?ID=1"

{
  "categories": [
    {
      "id": 0,
      "color": "ffffff",
      "title": "Introduction",
      "IgnoreResults": true
    }
  ]
}

This method is used to retrieve one or more categories.

URL Parameters	Description
ID (Optional)	The ID of the requested category. When this is specified, only one category is returned.

Create Categories

# Create a new category
curl -X POST "https://api.sustainability.oregonstate.edu/v2/carbon/category" \
-H "Content-Type: application/json" \
-H "Cookie: token=(put authentication token here)" -d \
'{
  "color": "ffffff",
  "title": "New Category",
  "ignoreResults": false
}'

{
  "categories": [
    {
      "id": 9,
      "color": "ffffff",
      "title": "New Category",
      "ignoreResults": false
    }
  ]
}

This method is used to create a new category and is reserved for administrators. Administrators must include an authentication token with each request.

JSON Parameters	Description
color	The six-character hexidecimal string corresponding to the new category's color.
title	The category's title.
ignoreResults	A boolean value that is `true` if this category should not be included in the results calculations. `false` otherwise.

Delete Categories

# Delete a category by ID
curl -X DELETE "https://api.sustainability.oregonstate.edu/v2/carbon/category?ID=1" \
-H "Cookie: token=(put authentication token here)"

{
  "status": 200,
  "message": "Category deleted."
}

This method is used to delete a category and is reserved for administrators. Administrators must include an authentication token with each request.

URL Parameters	Description
ID	The ID of the category to be deleted.

Get Questions

This endpoint is used for performing CRUD operations on one or more questions.

# Request all questions for a particular category
curl "https://api.sustainability.oregonstate.edu/v2/carbon/question?categoryID=1"

# Request a specific question
curl "https://api.sustainability.oregonstate.edu/v2/carbon/question?ID=1"

{
  "questions": [
    {
      "ID": 999,
      "questionText": "How many miles do you drive each day?",
      "orderIndex": 3,
      "metaData": "This question is not real.",
      "input": {
        "type": "numerical",
        "value": 0, // this is the initial value that appears before the user modifies the input box on the calculator.
        "coef": 0.533,
        "unit": "mi",
        "isPrefix": false
      },
      "trigger": {
        "triggerValue": "Gasoline",
        "parentQuestion": 2,
        "visible": false
      },
      "categoryID": 0
    },
    ...
  ]
}

This method is used to retrieve one or more questions.

URL Parameters	Description
ID	The ID of the requested question. When this is specified, only one question is returned.
categoryID	When this is specified, all of the questions belonging to a particular category are returned.

Create Questions

# Create a new question
curl -X POST "https://api.sustainability.oregonstate.edu/v2/carbon/question" \
-H "Content-Type: application/json" \
-H "Cookie: token=(put authentication token here)" -d \
'{
  "questionText": "How many miles do you drive each day?",
  "orderIndex": 3,
  "metaData": "This question is not real.",
  "input": {
    "type": "numerical",
    "value": 0, // this is the initial value that appears before the user modifies the input box on the calculator.
    "coef": 0.533,
    "unit": "mi",
    "isPrefix": false
  },
  "trigger": {
    "triggerValue": "Gasoline",
    "parentQuestion": 2,
    "visible": false
  },
  "categoryID": 0
}'

{
  "questions": [
    {
      "ID": 999,
      "questionText": "How many miles do you drive each day?",
      "orderIndex": 3,
      "metaData": "This question is not real.",
      "input": {
        "type": "numerical",
        "value": 0, // this is the initial value that appears before the user modifies the input box on the calculator.
        "coef": 0.533,
        "unit": "mi",
        "isPrefix": false
      },
      "trigger": {
        "triggerValue": "Gasoline",
        "parentQuestion": 2,
        "visible": false
      },
      "categoryID": 0
    }
  ]
}

This method is used to delete a question and is reserved for administrators. Administrators must include an authentication token with each request.

JSON Parameters	Description
title	This string contains the title of a paragraph-type question.
questionText	This is the string containing text for the question, such as "How old are you?".
orderIndex	Each question is displayed in a particular order, beginning with 0. If -1 is supplied, this will be appended to the end of the current list of questions for the specified category. Otherwise, this question will be placed at the specified index. If a question already exists at the specified index, the new question will be inserted into the list at the index.
metaData	This is displayed when the user hovers the mouse over a tooltip. This contains information regarding any sources used for computing the CO2e coefficient for this question, or any other pertinent information.
input (optional)	An object describing the type of input that should be rendered for this question.
trigger (optional)	An object describing whether or not this question's visibility is triggered by the answer to another question. For example, the question: "How many miles do you drive?" may be triggered by the response "Yes" to the question: "Do you drive a car?"
categoryID	The ID of the category this question will reside within. To look up category IDs, refer to the /category endpoint.

Input Objects

A question can employ one of four kinds of inputs:

No input. This is used when a "question" is really just a paragraph. In this case, assign the input key a null value.

{
  "title": "Introduction",
  "questionText": "Welcome to the calculator.",
  "orderIndex": -1,
  "metaData": "This question is actually a paragraph.",
  "input": null,
  "trigger": null,
  "categoryID": 0
}

Numerical. This is used when a question computes a carbon footprint using an integer input by the user.

{
  "questionText": "How many miles do you drive each day?",
  "orderIndex": 3,
  "metaData": "This question is not real.",
  "unit": "mi",
  "isPrefix": false,
  "input": {
    "type": "numerical",
    "value": 0, // this is the initial value that appears before the user modifies the input box on the calculator.
    "coef": 0.533
  },
  "trigger": {
    "triggerValue": "Gasoline",
    "parentQuestion": 2,
    "visible": false
  },
  "categoryID": 0
}

List. This is used when a user must select from one or more predetermined values in a list (or a toggle switch).

{
  "questionText": "What kind of car do you drive?",
  "orderIndex": 2,
  "metaData": "This question is not real.",
  "input": {
    "type": "list",
    "values": ["Gasoline", "Diesel", "Hybrid", "Electric", "Other"],
    "coefs": [0.533, 0.421, 0.213, 0.048, 0]
  },
  "trigger": null,
  "categoryID": 0
}

Table. This is used when a user must input data in a table format.

{
  "questionText": "From the following list of appliances, electronics, lighting, etc, input how many of each item are in your room and how many hours a day each item is in use or plugged in. If you own an item not listed below please be sure to fill in extra fields: What is the item and wattage? You can find the wattage on the bottom of most appliances. Be sure to multiply by 1000 if the wattage is given in kilowatts.",
  "orderIndex": 4,
  "metaData": "This question is not real.",
  "input": {
    "type": "table",
    "formula": "C1 * C2 * C3 * 0.214",
    "values": [
      ["Item", "Quantity", "Watts", "Active Use (Hours/Day)", "Standby Use"],
      ["Refrigerator", 1, 160, 24, 0],
      ["Microwave", 1, 1000, 0, 0],
      ...
    ]
  },
  "trigger": null,
  "categoryID": 0
}

Trigger Objects

A question's visibility on the frontend can be triggered by another question. The user may respond to Question A favorably, "triggering" Question B's visibility. If this functionality is not desired, the trigger object can be null.

The object is constructed like this:

"trigger": {
  "triggerValue": "Gasoline",
  "parentQuestion": 2,
  "visible": false
}

JSON Parameters	Description
triggerValue	If the user's response to the parentQuestion is equivalent to the triggerValue, this question's visibility will be toggled.
parentQuestion	This is the orderIndex of the parent question within the current category.
visible	If true, the question will initially be visible. If false, the question will not initially be visible.

Delete Questions

# Delete a question by ID
curl -X DELETE "https://api.sustainability.oregonstate.edu/v2/carbon/question?ID=1" \
-H "Cookie: token=(put authentication token here)"

{
  "status": 200,
  "message": "Question deleted."
}

This method is used to create a new question and is reserved for administrators. Administrators must include an authentication token with each request.

URL Parameters	Description
ID	The ID of the question to be deleted.

Get Historical Data

# Request all historica data for the current user
curl "https://api.sustainability.oregonstate.edu/v2/carbon/data"

{
  "data": [
    {
      "ID": 1,
      "created": "YYYY-MM-DD hh:mm:ss", // SQL Datetime format, UTC timezone
      "totals":[
        {
          "categoryID": 1,
          "total": 1234.56
        },
        ...
      ]
    },
    ...
  ]
}

This method retrieves all of the historical datapoints for the current user.

Create New Historical Data

# Request all historica data for the current user
curl -X POST "https://api.sustainability.oregonstate.edu/v2/carbon/data" \
-H "Content-Type: application/json" \
-H "Cookie: token=(put authentication token here)" -d \
'{
  "totals":[
    {
      "categoryID": 1,
      "total": 1234.56
    },
    ...
  ]
}'

{
  "data": [
    {
      "ID": 999,
      "created": "YYYY-MM-DD hh:mm:ss", // SQL Datetime format, UTC timezone
      "totals":[
        {
          "categoryID": 1,
          "total": 1234.56
        },
        ...
      ]
    },
    ...
  ]
}

This method stores a results object as a historical data point.

Delete Historical Data

# Delete the specified historical data point
curl -X DELETE "https://api.sustainability.oregonstate.edu/v2/carbon/data?ID=1" \
-H "Cookie: token=(put authentication token here)"

{
  "status": 200,
  "message": "Data point deleted."
}

This method deletes the specified historical data point.

URL Parameters	Description
ID	The ID of the historical data point to be deleted. Each data point unique consists of a set of totals for each category and a timestamp.

{
  "status": 200,
  "message": "Data point deleted."
}