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.
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>
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.
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:
Renewablesapi/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=csvapi/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=jsonChoices: 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.
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:
merra2) uses a 0.625 by 0.5 degrees grid.sarah) uses a 0.05 by 0.05 degrees grid.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.
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.
Choices: true or false (default: false)
Returns extra columns with the raw weather data alongside.
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.
Endpoint api/limits returns your API request limits.
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'
See here for a detailed example on using Python to request and process data obtained via the API.
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.
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.
