New API format and model upgrades go live

Published: 25 Jul 2019

Earlier last month we announced that the API format is going to change to make the ninja platform more consistent and easier to deal with. These changes have gone live today.

If you use the maps on our the web interface then you won’t be affected by this, and can carry on working as you have done before. If you access through other programs and scripting languages, then you will need to change the way you handle data returned by our models.

If you use the API, these are the relevant changes:

  • The format of the returned CSV and JSON files has changed (see below).
  • system_loss is now a fractional parameter ranging from 0-1 instead of a percentage ranging from 0-100%.
  • The deprecated metadata parameter is no longer accepted.

The CSV file format now always starts with three comment lines:

# Solar PV (Point API) - 42.812, -8.086 - Version: 1.1 (using GSEE v0.3.1) - License: - Reference:
# Units: time in UTC, local_time in Europe/Madrid, electricity in kW
# {"units": {"time": "UTC", "local_time": "Europe/Madrid", "electricity": "kW"}, "params": {"local_time": true, "lat": "42.8115217450979", "lon": "-8.0859375", "date_from": "2014-01-01", "date_to": "2014-12-31", "dataset": "merra2", "capacity": "1", "system_loss": "0.1", "tracking": "0", "tilt": "35", "azim": "180"}}
2014-01-01 00:00,2014-01-01 01:00,0

The comment lines give (1) the dataset, license and citation, (2) human readable information on the columns and units, and (3) machine-readable information on the units and simulation parameters. The files then have a single row giving the column headers, and then the data. No more multi-row headers!

In addition, the JSON return format is changed and now includes two top-level keys by default: metadata (which mirrors exactly the machine-readable metadata from the 3rd comment line in CSV files) and data (which contains the same data format as previously delivered by JSON).

This is the new default behaviour for the API. If you need to, you can explicitly turn off the three comment lines in CSV or the insertion of metadata and top-level keys into JSON by passing header=false with your request.

We have updated the online documentation with new examples for Python and R code to access the, and our Excel interface has been updated on GitHub.

We hope this change doesn’t cause you any disruption, and in the long term makes it easier to work with the ninja!

This update also includes a couple of fixes. Firstly, the weather model now displays a chart of your data when you run it through the online interface. For example, the US polar vortex of 2014 is clearly visible in Chicago's temperature data (-20 degrees Celsius daily average in January):

Weather model.png

Secondly, we corrected a bug in the solar model which led to a misestimation when using 1-axis tilt with non-horizontal tilt axes (fixed in GSEE v0.3.1). An error in angle calculation led to an underestimation on low axis tilt angles and overestimation on high axis tilt angles, with an error of up to about 5% on average over a year. The error did not occur with horizontal tilt axes, by far the most common case for 1-axis tilt systems. Thanks to Julien Armijo from the IEA for notifying us of this issue!