Emissions API

General usage and limitations

Nowtricity API gives you access to live and historical electricity production emissions data in grams CO2eq/kWh from multiple countries. Check the frequently asked questions for more information on how that data is calculated.

The API requests are made with a simple GET to a URL and data is returned in JSON.

It's free to use, but please play nice. Cache data on your end and limit the number of requests made. A user-agent must be provided.

Personal keys have access to the data of one country only, limited to 4 requests per hour and 100 per day. Commercial keys have access to all countries, limited to 200 requests per hour and 3600 per day. Hourly limits reset every hour and daily limits every day.

Commercial keys require a followable link to Nowtricity on the page indicated when requesting the key. Links are checked regularly and keys are blocked if the link is removed, changed to nofollow or the page is blocked to search engines.

Cite the data source as Nowtricity.

Authentication

All requests to the API need to have your API key sent in a header X-Api-Key

You can easily set this in Postman (Authorization > Type: API Key > Key: X-Api-Key > Value: Your key) or with cURL curl 'https://www.nowtricity.com/api/countries/' -A 'UserAgentString' -H 'X-Api-Key: Your key'

Countries

This endpoint will return the list of currently available countries and their respective ID

{
    "countries": [
        {
            "id": "austria",
            "name": "Austria"
        },
        {
            "id": "belgium",
            "name": "Belgium"
        },
		[...]
    ]
}

Current emissions

This endpoint will return the current live data emissions of a specific country. Replace {country-id} with the ID returned in Countries endpoint

For example, for Portugal a request would be made to https://www.nowtricity.com/api/current-emissions/portugal/

{
    "country": {
        "id": "portugal",
        "name": "Portugal"
    },
    "emissions": {
        "value": 155,
        "unit": "g CO2eq/kWh",
        "timestamp": 1656694800,
        "dateUTC": "2022-07-01T17:00:00+00:00",
        "dateLocal": "2022-07-01T18:00:00+01:00",
        "outdated": false
    }
}

The field dateLocal returns the date in the country timezone. Field outdated is returned as true when live data is not currently available.

Emissions of last 24 hours

This endpoint will return the emissions of the last 24 hours for a specific country. Replace {country-id} with the ID returned in Countries endpoint

For example, for Norway a request would be made to https://www.nowtricity.com/api/emissions-previous-24h/norway/

{
    "country": {
        "id": "norway",
        "name": "Norway"
    },
    "emissions": [
        {
            "value": 29,
            "unit": "g CO2eq/kWh",
            "timestamp": 1656680400,
            "dateUTC": "2022-07-01T13:00:00+00:00",
            "dateLocal": "2022-07-01T15:00:00+02:00"
        },
        {
            "value": 30,
            "unit": "g CO2eq/kWh",
            "timestamp": 1656676800,
            "dateUTC": "2022-07-01T12:00:00+00:00",
            "dateLocal": "2022-07-01T14:00:00+02:00"
        },
		[...]
    ]
}

The field dateLocal returns the date in the country timezone.

Emissions per year and month

This endpoint will return the emissions per year and month of a specific country. Replace {country-id} with the ID returned in Countries endpoint and {year} with the desired year

For example, for Germany 2022 a request would be made to https://www.nowtricity.com/api/archive/germany/2022/

{
    "country": {
        "id": "germany",
        "name": "Germany"
    },
    "year": {
        "2022": {
            "value": 380,
            "unit": "g CO2eq/kWh"
        }
    },
    "months": {
        "1": {
            "value": 381,
            "unit": "g CO2eq/kWh"
        },
        "2": {
            "value": 277,
            "unit": "g CO2eq/kWh"
        },
		[...]
    ]
}

If data for a year or month is not available yet, false will be returned.

In case a year in the future or not available in our archive, an error will be returned.

{
	"errors": {
		"status": "200",
		"detail": "No data available"
	}
}

Errors

If the X-Api-Key header is not present, contains an invalid or blocked key, or the request limits of your key were reached, a 429 response is sent with the following data:

{
    "errors": {
        "status": "429",
        "detail": "Too many requests"
    }
}

If a personal key requests data from a country other than the one chosen for that key, a 403 response is sent with the following data:

{
    "errors": {
        "status": "403",
        "detail": "Not authorized"
    }
}