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 token:

Go to the web API website homepage (https://solarfarmer.dnv.com/) and copy your API token 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 token)
  
  Important
  It is important you type Bearer {YOURAPIKEY} and don't just paste your API token 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 token 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.208.0",
  "solarFarmerApiVersion": "0.2.242"
}
```
  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, type OpenAPIJson or CSharpClient. 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.