The SolarPosition Endpoint Tutorial

Note

This tutorial assumes you have already set up a Python environment on your machine. If not, see Setting up a Python Environment for help on how to set this up.

Definition

See the SolarPosition Endpoint for a definition of this endpoint.

Tutorial

This is some sample code to use the SolarPosition endpoint to calculate solar positions at 3 times for a given location on earth (Sydney Opera House, Australia. This is +10 hours ahead of UTC). The 3 times are sunrise, sunset and solar noon for 17 August 2021 (taken from https://www.timeanddate.com/sun/australia/sydney).

1. Create a new empty folder

2. Create an empty text file in that folder and copy and paste the following Python code into the file and save it as a Python file (e.g. as "SolarPositionEndpointTutorial.py").

   """
   Request the solar positions for a given location and list of times
   """
   
   # import external libraries
   import requests   # to send the request to SF-API and get the response
   
   sf_web_api_url = 'https://solarfarmer.dnv.com/api'
   api_token = 'ENTER YOUR API TOKEN HERE!!!'
   
   # Set up the API url to call 
   solarPosition_request_url = sf_web_api_url + '/SolarPosition'
   try:
       # Set up the headers for the POST API request - setting the API token and content type
       headers = {
           'Authorization': f'Bearer {api_token}',
           'ContentType': 'application/json'}
   
       # Set up the input request, which is an object of type SolarPositionRequest
       # (Sydney Opera House, Australia. Which is +10 UTC)
       request = { 
           "latitude": -33.856186,
           "longitude": 151.215316,
           "elevation": 3,
           "timestamp": [
               "2021-08-17T06:32:00+10:00",
               "2021-08-17T11:59:00+10:00",
               "2021-08-17T17:26:00+10:00"
           ]
       }
   
       # Call the POST request to the API
       response = requests.post(
           solarPosition_request_url,
           headers = headers,
           json = request)
   
       # Handle the response that is returned
       if (response.ok):
           json_response_text = response.json()
           print('POST Request: ' + solarPosition_request_url)
           print('Full JSON response: ' + str(json_response_text))
           solar_position_list = json_response_text
           print('Number of solar positions returned: ' + str(len(solar_position_list)))
           for i, solar_position in enumerate(solar_position_list):
               print(
                   f'Solar position {str(i)}:' +
                   f'  Time: {request["timestamp"][i]}' + 
                   f'  Az: {str(round(solar_position["azimuthInDegrees"],6))}' + 
                   f'  Zen: {str(round(solar_position["zenithInDegrees"],6))}')
       else:
           print(f"API request {solarPosition_request_url} failed.")
   
       # check for any status >400 and print out the reason and text as these can be useful
       if (response.status_code == 401):
           # Unauthorized - API token not valid or out of date
           print(f"Your API token is not valid for the web API url {sf_web_api_url}.")
       elif (response.status_code >= 400):
           print(f"Error status code: {response.status_code}\n" +
               f"Reason: {response.reason}\n" + f"Message: {response.text}")
   
   except Exception as exc:
       print(f"Exception thrown when calling {solarPosition_request_url}")
       print(str(exc))
   

3. Replace the text 'ENTER YOUR API TOKEN HERE!!!' with your personal API token (encase it in single quotes)

4. Open a command prompt in the folder

5. Type python SolarPositionEndpointTutorial.py and hit Return to run the script.

6. It should return very quickly, giving some output similar to the following:

   POST Request: https://solarfarmer.dnv.com/api/SolarPosition
   Full JSON response: [{'azimuthInDegrees': 74.3145184778762, 'zenithInDegrees': 90.23105446991804}, {'azimuthInDegrees': 0.08421513912691125, 'zenithInDegrees': 47.22664850040786}, {'azimuthInDegrees': 285.6365357247847, 'zenithInDegrees': 90.07842010731149}]
   Number of solar positions returned: 3
   Solar position 0:  Time: 2021-08-17T06:32:00+10:00  Az: 74.314518  Zen: 90.231054
   Solar position 1:  Time: 2021-08-17T11:59:00+10:00  Az: 0.084215  Zen: 47.226649
   Solar position 2:  Time: 2021-08-17T17:26:00+10:00  Az: 285.636536  Zen: 90.07842