Use the data in your own spreadsheet or app (API)

Global Grid's figures can go straight into your own spreadsheet or app. This guide is written for everyone, not only programmers.

To download spreadsheet files instead, open the Data tab on the dashboard: a free account downloads the latest figures, and Pro adds full histories and the API.

What is an API?

An API is a web address that gives figures instead of a web page. Your spreadsheet or app visits the address and gets the latest numbers by itself, so there is nothing to copy and paste.

Get your key

API access comes with Pro (see the Subscribe tab). Open your Account page, find API keys, type a name and press Make key. The key starts with gg_ and is shown only once, so copy it somewhere safe. You can have up to three.

Three ways to use it

  1. Paste a link. Add format=csv&key=YOUR_KEY to any address below, then paste it into a browser (it downloads a spreadsheet file), into Excel (Data > Get Data > From Web), or into Google Sheets inside =IMPORTDATA("…"). For example:
    https://globalgrid.uk/api/v1/grid/GB/today?format=csv&key=YOUR_KEY
  2. For programmers: a header. Send the key as a header instead, which keeps it out of addresses, browser history and logs:
    Authorization: Bearer YOUR_KEY
  3. CSV or JSON. With format=csv you get a table with a header row, ready for a spreadsheet. Without it you get JSON, the usual format for programs: the same figures, plus notes on units and sources.

The addresses

Each one works as JSON or, with format=csv, as a spreadsheet file. Replace YOUR_KEY with your key.

Examples

Google Sheets. Paste this into a cell. The sheet fills with the last 24 hours and fetches them again from time to time while it is open (each fetch counts as a request):

=IMPORTDATA("https://globalgrid.uk/api/v1/grid/GB/today?format=csv&key=YOUR_KEY")

Excel. Choose Data > Get Data > From Web (in some versions Data > From Web), paste a link like the one above and press OK, then Load. Data > Refresh All fetches the latest figures.

Python (with the requests library):

import requests

r = requests.get("https://globalgrid.uk/api/v1/grid/GB",
                 headers={"Authorization": "Bearer YOUR_KEY"})
r.raise_for_status()
grid = r.json()
print(grid["carbonIntensity"], "g of CO2 per kWh")
print("Requests left today:", r.headers["x-ratelimit-remaining"])

curl (saves the last 24 hours as a file):

curl -H "Authorization: Bearer YOUR_KEY" "https://globalgrid.uk/api/v1/grid/GB/today?format=csv" -o gb-today.csv

Your daily allowance

Pro includes 1,000 requests a day, shared by all your keys. The count starts again at midnight UTC (1am UK time in summer). Every answer has a header, x-ratelimit-remaining, saying how many requests are left today, and the Account page shows each key's use.

If something goes wrong

CodeWhat it means
400Something in the address is not understood, such as a year outside 2000 to 2025, or a format other than csv.
401No key, or a key we do not recognise: check it is complete, or make a new one on the Account page.
402API access comes with Pro, and the key's account does not have Pro at the moment (for example, the subscription has ended).
404Unknown address or item, such as a mistyped country code or price name, or a price that cannot be shared. The answer lists the addresses.
429Today's 1,000 requests are used up. The count starts again at midnight UTC.
503The figures are not available right now, for example while a data source is down. Please try again later.

Credit and licences

Every CSV row and JSON answer names its source. When you share or publish the figures, credit that source:

The International Monetary Fund's monthly gas and coal prices are shown on the dashboard but are not offered in downloads or the API, because their licence is unclear. The terms explain what you may do with the data.

Keep your key safe

A link containing your key works for anyone who has it, so do not share it publicly or put it in a spreadsheet other people can open (in a shared Google Sheet, everyone who can open it can see the formula). If a key leaks, delete it on the Account page and make a new one: the old key stops working straight away.

Building a web page? The API answers requests from any website, without cookies. Anyone who opens a public page can see a key in its code, so call the API from your own server, or keep such pages private.

Business or bulk data? To ask, email GlobalGrid365@gmail.com.