Quickstart

  1. Choose the plan that's right for you.
  2. Register for a user account.
  3. Check out the interactive docs and tutorials below.
  4. Get and use your API token to make authenticated requests and receive JSON data in response.
  5. Make something awesome!
  6. Keep in touch so we can feature your work, answer your questions, and benefit from your feedback.

Make authenticated requests

Basics

  • Authenticated API requests have unlimited access to API endpoints, while unauthenticated API requests are throttled.
  • An API token is automatically generated for you when you create your user account.
  • API tokens are used in the Authorization HTTP header.
  • To keep your account secure, the WattTime API is only available over HTTPS.

Accessing your token

You can access your token in two ways:

To use the endpoint, POST a valid username and password, e.g., {'username': 'myname', 'password': 'secret'}. This will return a JSON response like {'token': '0123abcdef4567abcdef0123abcdef4567abcdef'}. POSTing to this endpoint does not modify the state of your token.

Possible errors
POST request problem response code response content
/api/v1/obtain-token-auth/ missing username and password 400 {'username': ['This field is required.'], 'password': ['This field is required.']}
/api/v1/obtain-token-auth/?username=myname missing password 400 {'password': ['This field is required.']}
/api/v1/obtain-token-auth/?password=secret missing username 400 {'username': ['This field is required.']}
/api/v1/obtain-token-auth/?username=myname&password=wrongpw invalid username and password 400 {'non_field_errors': ['Unable to login with provided credentials.']}

Using your token

To authenticate your API requests, include your 40-digit hexadecimal token in the Authorization HTTP Header. Follow these examples, substituting your actual token for the dummy token 0123abcdef4567abcdef0123abcdef4567abcdef:

Using curl:

curl -X GET https://api.watttime.org/api/v1/datapoints/ -H 'Authorization: Token 0123abcdef4567abcdef0123abcdef4567abcdef'
Using Python Requests:
>>> import requests
>>> requests.get('https://api.watttime.org/api/v1/datapoints/', headers={'Authorization': 'Token 0123abcdef4567abcdef0123abcdef4567abcdef'})

Possible errors
header problem response code response content
[blank] too many unauthenticated requests 429 {'detail': 'Request was throttled. Expected available in 86400.0 seconds.'}
Authorization: Token badtoken invalid token 401 {'detail': 'Invalid token'}
Authorization: Token missing token 401 {'detail': 'Invalid token header. No credentials provided.'}

Find the balancing authority for a location

In order to get data about power grid operations at a particular point, you need to know the name of the grid operator (technically the balancing authority). For instance, the balancing authority for Berkeley, California is CAISO.

If you know the latitude and longitude for your location, you can find the balancing authority by querying the /api/v1/balancing_authorities/ endpoint. This endpoint is accessible from Visitor, Open, and Pro accounts.

Use the loc query parameter. This accepts GeoJSON-formatted points, like {"type":"Point","coordinates":[LON,LAT]}.

For instance, Berkeley is at latitude 37.871667, longitude -122.272778. So, a GET request to https://api.watttime.org/api/v1/balancing_authorities/?loc={"type":"Point","coordinates":[-122.272778,37.871667]} will return a JSON response like:

[
    {
        "name": "California Independent System Operator",
        "ba_type": "ISO",
        "url": "https://api.watttime.org/api/v1/balancing_authorities/CAISO/",
        "abbrev": "CAISO",
        "link": "http://oasis.caiso.com/",
        "states": ["CA"],
        "notes": ""
    }
]
The abbrev attribute (here, "CAISO") is the one you want to use as the ba query parameter for other endpoints.

Get generation mix data

Basics

  • Generation mix means the number of megawatts of power generated from different sources (wind, coal, etc) at a given place and time.
  • You can get a time series of generation mix data by querying the /api/v1/datapoints/ endpoint.
  • This endpoint is accessible from Visitor, Open, and Pro accounts.

The request

A simple GET request to https://api.watttime.org/api/v1/datapoints/ returns a paginated list of datapoints at all locations, sorted from the future to the past.

Several query parameters are available to help you restrict your query:

  • ba filters by place (see tutorial)
  • start_at and end_at filter by time (formatted like 2015-10-20T16:45:30-08:00)
  • market filters by data type (use RT5M to get past data from the real-time 5 minute market, or DAHR to get forecasted data from the day-ahead hourly market)
  • page_size sets the number of data points that are returned in a single query

The response

The JSON data in the response body is formatted like:

{
  "count": 55,
  "next": "http://api.watttime.org/api/v1/datapoints/?ba=MISO&market=RT5M&page=2&page_size=2",
  "previous": null,
  "results": [
    {
      "timestamp": "2015-10-15T00:55:00Z",
      "created_at": "2015-10-15T00:56:39.743213Z",
      "carbon": 1547.04233848854,
      "genmix": [
        {"fuel": "wind", "gen_MW": 2489},
        {"fuel": "other", "gen_MW": 1287},
        {"fuel": "nuclear", "gen_MW": 9866},
        {"fuel": "natgas", "gen_MW": 16443},
        {"fuel": "coal", "gen_MW": 42851}
      ],
      "url": "http://api.watttime.org/api/v1/datapoints/2075/",
      "market": "RT5M",
      "freq": "5m",
      "ba": "MISO"
    },
    {
      "timestamp": "2015-10-15T00:50:00Z",
      "created_at": "2015-10-15T00:53:11.972544Z",
      "carbon": 1547.89217828272,
      "genmix": [
        {"fuel": "wind", "gen_MW": 2469},
        {"fuel": "other", "gen_MW": 1324},
        {"fuel": "nuclear", "gen_MW": 9877},
        {"fuel": "natgas", "gen_MW": 16558},
        {"fuel": "coal", "gen_MW": 43004}
      ],
      "url": "http://api.watttime.org/api/v1/datapoints/1960/",
      "market": "RT5M",
      "freq": "5m",
      "ba": "MISO"
    }
  ]
}

Here's what each JSON attribute signifies:

  • count is the number of results that can be paged through
  • next is a link to the next page of results (or null)
  • previous is a link to the previous page of results (or null)
  • results is a list of the data points on this page
Each data point has the following key attributes (plus some metadata):
  • timestamp is the time at which the data is valid, in UTC
  • carbon is the average carbon footprint (i.e., the number of pounds of CO2 produced for every MW of power generated, averaged over everything on the local grid)
  • genmix is a list of the number of MW of power generated from each fuel (different fuel breakdowns will be available in different balancing authorities)

Get marginal carbon data

Basics

  • Marginal carbon emissions are the number of pounds of CO2 generated by the marginal power plant at a given place and time.
  • You can get a time series of marginal carbon data by querying the /api/v1/marginal/ endpoint.
  • This endpoint is accessible only to Pro accounts and is subject to additional terms and conditions.

The request

A simple GET request to https://api.watttime.org/api/v1/marginal/ returns a paginated list of datapoints at all locations, sorted from the future to the past.

Several query parameters are available to help you restrict your query:

  • ba filters by place (see tutorial)
  • start_at and end_at filter by time (formatted like 2015-10-20T16:45:30-08:00)
  • market filters by data type (use RT5M to get past data from the real-time 5 minute market, or DAHR to get forecasted data from the day-ahead hourly market)
  • page_size sets the number of data points that are returned in a single query

The response

The JSON data in the response body is formatted like:

{
  "count": 55,
  "next": "http://api.watttime.org/api/v1/marginal/?ba=MISO&market=RT5M&page=2&page_size=2",
  "previous": null,
  "results": [
    {
      "timestamp": "2015-10-15T00:55:00Z",
      "genmix": [
        {"fuel": "wind", "gen_MW": 2489},
        {"fuel": "other", "gen_MW": 1287},
        {"fuel": "nuclear", "gen_MW": 9866},
        {"fuel": "natgas", "gen_MW": 16443},
        {"fuel": "coal", "gen_MW": 42851}
      ],
      "url": "http://api.watttime.org/api/v1/marginal/2075/",
      "market": "RT5M",
      "freq": "5m",
      "ba": "MISO",
      "marginal_carbon": {
        "value": 1666.8,
        "units": "lb/MW",
        "structural_model": "..."
      },
      "load": null
    },
    {
      "timestamp": "2015-10-15T00:50:00Z",
      "genmix": [
        {"fuel": "wind", "gen_MW": 2469},
        {"fuel": "other", "gen_MW": 1324},
        {"fuel": "nuclear", "gen_MW": 9877},
        {"fuel": "natgas", "gen_MW": 16558},
        {"fuel": "coal", "gen_MW": 43004}
      ],
      "url": "http://api.watttime.org/api/v1/marginal/1960/",
      "market": "RT5M",
      "freq": "5m",
      "ba": "MISO",
      "marginal_carbon": {
        "value": 1668.8,
        "units": "lb/MW",
        "structural_model": "..."
      },
      "load": null
    }
  ]
}

Here's what each JSON attribute signifies:

  • count is the number of results that can be paged through
  • next is a link to the next page of results (or null)
  • previous is a link to the previous page of results (or null)
  • results is a list of the data points on this page
Each data point has the following key attributes (plus some metadata):
  • timestamp is the time at which the data is valid, in UTC
  • marginal_carbon is the marginal carbon footprint (with value value and units units)
  • genmix is a list of the number of MW of power generated from each fuel, same as from the generation mix endpoint (or null if the data is unavailable)
  • load is the number of MW of total power demand in the balancing authority (or null if the data is unavailable)