API

The API can be accessed anonymously or as a registered user, subject to the same usage limitations as the website.

To authenticate, you need to use the API token displayed on your user profile page, as explained below.

Using token-based authentication

Your API token is displayed on your account page, where you can also generate a new random token in case your current token has been compromised.

To use token-based authentication, all your requests must contain an authorization header of the following form:

Authorization: Token <your_token_here>

API endpoints

There are two primary ways of using the api: api/data/.../... to run custom site-level simulations for a given location and parameters, and api/countries/... to return aggregated country-level data.

The API can return data in the JSON format or in the CSV format to read in spreadsheets. More details on the data format are given on our Datasets page.

Site-level data

Endpoint api/models gives metadata and required parameters for the available simulation models.

Endpoint api/data/{modelname} requests data for the given simulation model. Example requests:

  • PV in CSV format: api/data/pv?lat=45&lon=22&date_from=2014-01-01&date_to=2014-01-31&dataset=merra2&capacity=1&system_loss=0.1&tracking=0&tilt=35&azim=180&format=csv
  • Wind in JSON format: api/data/wind?&lat=56&lon=-3&date_from=2014-01-01&date_to=2014-02-28&capacity=1&dataset=merra2&height=100&turbine=Vestas+V80+2000&format=json

Additional parameters for site-level data

header

Choices: true or false (default: true)

If true, three comment lines of metadata are included at the top of CSV files, and JSON responses are split into top-level data and metadata keys. If false, CSV files contain no metadata comment lines at all, and JSON responses contain only the data, with no other top-level keys.

interpolate

Choices: true or false (default: true)

If set to false, spatial interpolation to the desired coordinates is disabled, instead, data from the closest grid cell (by centroid) is returned. Useful to speed up requests and increase consistency when querying the API to obtain a gridded dataset.

Gridding of available datasets:

  • MERRA-2 (merra2) uses a 0.625 by 0.5 degrees grid.
  • SARAH (sarah) uses a 0.05 by 0.05 degrees grid.
local_time

Choices: true or false (default: false for direct API use, but set to true from web interface)

If true, an extra local_time column is added to the result with a timestamp in the requested location's local time.

mean

Choices: year, month or day (default: none)

Deliver annual, monthly or daily averages instead of hourly data. Note that internally, hourly values are still computed, so this does not speed up processing time, but reduces the amount of data transferred if you do not require hourly precision.

Example use: https://www.renewables.ninja/api/data/pv?lat=45&lon=22&date_from=2014-01-01&date_to=2014-03-31&dataset=merra2&capacity=1&system_loss=0.1&tracking=0&tilt=35&azim=180&format=csv&mean=month

raw

Choices: true or false (default: false)

Returns extra columns with the raw weather data alongside.

Country-level data

Endpoint api/countries lists all countries for which country-level data is available.

Endpoint api/countries/{country_id} gives metadata for the data available for the given country, where {country_id} is a two-letter ISO country code such as DE. This includes a listing of the pre-generated datasets available for download as well as the aggregated data displayed in the country overview chart. If all you need is average annual country-level data, accessing this data directly via the api/countries/{country_id} endpoint will be the fastest approach.

API limits

Endpoint api/limits returns your API request limits.


Examples

CURL example

To request data in JSON format with token-based authorization:

curl -H 'Authorization: Token <your_token_here>' -X GET 'https://www.renewables.ninja/api/data/wind?&lat=56&lon=-3&date_from=2014-01-01&date_to=2014-02-28&capacity=1&dataset=merra2&height=100&turbine=Vestas+V80+2000&format=json'


Python example

See here for a detailed example on using Python to request and process data obtained via the API.

R examples

See here for a detailed example on using R to request and process data obtained via the API.

The Ninja Automator is a pre-made script which can download wind and solar output data for multiple locations. You can either supply vectors of input parameters (e.g. multiple latitude and longitude coordinates), or a CSV file of input parameters.

Excel interface

See our Github project for an Excel workbook that can run API simulations and deliver results directly into the spreadsheet. You can download the spreadsheet directly here.