Try the endpoints on the website
The SolarFarmer web API has various endpoints that you can use, depending on the task you want to do.
An endpoint is the point of entry in the communication between an API and a server. See https://en.wikipedia.org/wiki/Web_API for a bit of background information on web APIs.
Authorizing the endpoints on the website
To try the various endpoints on the web API website (without having to write any scripts!) you first have to authorize yourself on the website using your API key:
- Go to the web API website homepage (https://solarfarmer.dnv.com/) and copy your API key to the clipboard
- Go to the 'Docs' section of the website (https://solarfarmer.dnv.com/docs)
Click on the 'Authorize' button (green button on the right, with an open lock on it)
In the Value edit box, type
Bearer {YOURAPIKEY}
(replacing YOURAPIKEY with your pasted API key)Important
It is important you type
Bearer {YOURAPIKEY}
and don't just paste your API key directly, otherwise it won't successfully authorize you.Click on the Authorize button
- Click on the Close button
- You should see all the padlocks next to the endpoints go black and look closed. You've used your API key to authorize the endpoints from the website.
Trying the About endpoint on the website
The About
endpoint requires no inputs and returns the version number of the libraries used by the web API.
- Make sure you have performed the authorization step above
- Click on the blue
About
endpoint to expand the contents - Click the 'Try it out' button
Click the long blue 'Execute' button (this endpoint doesn't require any input parameters)
It should immediately return and the server response should contain a response body similar to:
{ "solarFarmerCoreVersion": "0.2.197.0", "solarFarmerApiVersion": "0.2.222" }
These are the internal version numbers of the libraries that are used by the web API. Useful to know and keep track of which version you are currently using.
Trying the OpenApi endpoint
The OpenApi
endpoint returns the OpenAPI (see https://www.openapis.org/ and https://swagger.io/specification/) specification
used by the web API. You may find this useful for your own coding using the API. The C# client version may be useful if you wish
to code your own C# application against the web API.
- Make sure you have performed the authorization step above
- Click on the blue
OpenApi
endpoint to expand the contents - Click the 'Try it out' button
- In the
fileType
input, typeOpenAPIJson
orCSharpClient
. This is the type of the file that will be returned. - Click the blue 'Execute' button.
- In the server response section, click the 'Download file' link to download the specification file.
Note
You can also download these specification files directly using the links at the top of the web API website (https://solarfarmer.dnv.com/docs).
Trying the SolarPosition endpoint
The SolarPosition
endpoint returns the solar position (zenith and azimuth) for a given location (longitude, latitude
and elevation) and date and time.
- The azimuth is in decimal degrees. 0 degrees is due north, angle going clockwise (so 90 degrees is east).
- The zenith is in decimal degrees. 0 degrees is vertically overhead. 90 degrees is horizontal.
- (See Sun Position for more detail on solar zenith and azimuth).
- Make sure you have performed the authorization step above
- Click on the green
SolarPosition
endpoint to expand the contents - Click the 'Try it out' button
In the request body, there is a large white edit box containing the request, looking something like this:
{ "latitude": 0, "longitude": 0, "elevation": 0, "timestamp": [ "2021-08-17T14:34:42.874Z" ] }
- This is editable and you need to edit the contents to change the input
- Set the values for the location's latitude and longitude (decimal degrees)
- Change the elevation value to the elevation above sea level (in metres)
- Carefully change the timestamp to the date and time that you're interested in. This is in ISO 8601 format (see https://en.wikipedia.org/wiki/ISO_8601).
Basically YYYY-MM-DDThh:mm:sstimeoffset, where timeoffset is the offset from UTC in hours.
- Note, this is a list, so you can set more than one timestamp.
E.g. for Alcatraz Island near San Francisco (latitude: 37.826599° longitude: -122.422817°, elevation 50m), which has a -7 hour offset from UTC during daylight savings time, for sunrise, solar noon and sunset (times got from https://www.timeanddate.com/sun/usa/san-francisco) on 17 August 2021:
{ "latitude": 37.826599, "longitude": -122.422817, "elevation": 50, "timestamp": [ "2021-08-17T06:27:00-07:00", "2021-08-17T13:13:00-07:00", "2021-08-17T19:59:00-07:00" ] }
This returns the following response:
[ { "azimuthInDegrees": 72.44203390604113, "zenithInDegrees": 90.24871065999514 }, { "azimuthInDegrees": 179.62634634906587, "zenithInDegrees": 24.677174871485803 }, { "azimuthInDegrees": 287.2197896105249, "zenithInDegrees": 90.14401334867406 } ]
The azimuth and zenith solar positions, one for each time in the timestamp list.
Trying the ModelChain endpoint
The ModelChain
endpoint runs the energy calculation in a synchronous way. You POST the message to the endpoint
and must wait for it to return whilst the calculation is running in the cloud. It is fairly lightweight and intended to be used
for all but the most complex 2D calculations. 3D calculations and very complex 2D calculations will use an asynchronous version
of this endpoint, available in a future release.
- Make sure you have performed the authorization step above
- Click on the green
ModelChain
endpoint to expand the contents - Click the 'Try it out' button
See the ModelChain Endpoint Tutorial to access some files that you can used to use the ModelChain endpoint on the website.