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. Request throttling is implemented to avoid overloading the server.

Cite the data source as Nowtricity. A link back would be awesome, if possible.

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/' -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 or contains an invalid key a 403 response is sent with the following data:

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

If too many requests are made, request throttling will be activated and subsequent requests will return a 403 response with the following data:

{
    "errors": {
        "status": "403",
        "detail": "Too many requests, over quota"
    }
}