How to call the API

There are multiple ways to interact with the Renewables.Architect Integrate API.

A typical workflow involved interacting directly with the Analysis Service and is described below.

Note

Aside from the Analysis Service, users can also interact with the Run Service. However, this is most typically done by desktop Renewables.Architect users who are running a Renewables.Archtiect driver locally and have passed it the RunServiceRunner runner type component to allow it to send runs the the cloud. This is done on the command line by using the ra compute command.

1. Authenticate with the API to obtain an access token.

2. Queue your analysis by sending a Renewables.Architect application definition file (app.json).

   You can get application definition payloads in the Applications Library - copy and place them in a new file with a .json extension somewhere on your computer.

   When queuing your analysis you receive an analysis ID, with which you can then trace progress and results.

   Bash

   terminal

   curl --request POST https://ra.dnv.com/api/analysis/analyses \
        --header "Content-Type: application/json" \
        --header "Authorization: Bearer YOUR_TOKEN_HERE" \
        --silent --show-error \
        -d "@{PATH_TO_APP_HERE}"

   Python

   queue_analysis.py

   import requests
   import json
   
   def queue_analysis(token: str, json_path: str):
       with open(json_path, "r") as file:
           json_data = json.load(file)
   
       url = "https://ra.dnv.com/api/analysis/analyses"
   
       headers = {
           "Content-Type": "application/json",
           "Authorization": f"Bearer {token}",
       }
   
       response = requests.post(url, headers=headers, json=json_data)
   
       if response.ok:
           print("Analysis queued successfully:")
           print(response.json())
       else:
           print(f"Error {response.status_code}: {response.text}")
   
   if __name__ == "__main__":
       my_json_path = "PATH_TO_APP_HERE"    # Replace with the path to your application definition file
       my_token = "YOUR_TOKEN_HERE"         # Replace with your actual token
       queue_analysis(token=my_token, json_path=my_json_path)

3. Check analysis progress and logs. To check on the state of your analysis, use the following command and the analysis ID you received after queuing.

   Bash

   terminal

   curl --request GET https://ra.dnv.com/api/analysis/analyses/YOUR_ANALYSIS_ID_HERE/state \
        --header "Content-Type: application/json" \
        --header "Authorization: Bearer YOUR_TOKEN_HERE" \
        --silent --show-error

   Python

   get_analysis_state.py

   import requests
   
   
   def get_analysis_state(token: str, analysis_id: str):
       url = ("https://ra.dnv.com/api/analysis"
           f"/analyses/{analysis_id}/state")
   
       headers = {
           "Content-Type": "application/json",
           "Authorization": f"Bearer {token}",
       }
   
       response = requests.get(url, headers=headers)
   
       if response.ok:
           print("Analysis state obtained successfully:")
           if response.text:
               print(response.json())
       else:
           print(f"Error {response.status_code}: {response.text}")
   
   
   if __name__ == "__main__":
       my_token = "YOUR_TOKEN_HERE"              # Replace with your actual token
       my_analysis_id = "YOUR_ANALYSIS_ID_HERE"  # Replace with actual analysis ID
   
       get_analysis_state(token=my_token, analysis_id=my_analysis_id)

4. Get summary and detailed results. The overview results for an entire analysis can be obtained with the following commands. More detailed results for every individual run can be accessed as well, corresponding commands are listed below

   Bash

   terminal

   curl --request GET https://ra.dnv.com/api/analysis/analyses/YOUR_ANALYSIS_ID_HERE/runs/results \
        --header "Content-Type: application/json" \
        --header "Authorization: Bearer YOUR_TOKEN_HERE" \
        --silent --show-error

   Python

   get_analysis_results.py

   import requests
   
   
   def get_analysis_results(token: str, analysis_id: str):
       url = ("https://ra.dnv.com/api/analysis"
           f"/analyses/{analysis_id}/runs/results")
   
       headers = {
           "Content-Type": "application/json",
           "Authorization": f"Bearer {token}",
       }
   
       response = requests.get(url, headers=headers)
   
       if response.ok:
           print("Analysis results obtained successfully:")
           if response.text:
               print(response.json())
       else:
           print(f"Error {response.status_code}: {response.text}")
   
   
   if __name__ == "__main__":
       my_analysis_id = "YOUR_ANALYSIS_ID_HERE"  # Replace with actual analysis ID
       my_token = "YOUR_TOKEN_HERE"              # Replace with your actual token
       get_analysis_results(token=my_token, analysis_id=my_analysis_id)

5. Terminate/cancel a running analysis if required. Cancelling an analysis will allow running runs to finish, whereas terminating stops all runs immediately.

   Bash

   terminal (cancel)

   curl --request PUT https://ra.dnv.com/api/analysis/analyses/YOUR_ANALYSIS_ID_HERE/state \
        --header "Content-Type: application/json" \
        --header "Authorization: Bearer YOUR_TOKEN_HERE" \
        --silent --show-error \
        --data '{"state": "Cancelled"}'

   Python

   cancel_analysis.py

   import requests
   
   
   def cancel_analysis(token: str, analysis_id: str):
       url = f"https://ra.dnv.com/api/analysis/analyses/{analysis_id}/state"
   
       headers = {
           "Content-Type": "application/json",
           "Authorization": f"Bearer {token}",
       }
   
       response = requests.put(url, headers=headers, json={"state": "Cancelled"})
   
       if response.ok:
           print("Analysis successfully cancelled:")
           if response.text:
               print(response.json())
       else:
           print(f"Error {response.status_code}: {response.text}")
   
   
   if __name__ == "__main__":
       my_analysis_id = "YOUR_ANALYSIS_ID_HERE"  # Replace with actual analysis ID
       my_token = "YOUR_TOKEN_HERE"              # Replace with your actual token
   
       cancel_analysis(token=my_token, analysis_id=my_analysis_id)

   Bash

   terminal (terminate)

   curl --request PUT https://ra.dnv.com/api/analysis/analyses/YOUR_ANALYSIS_ID_HERE/state \
        --header "Content-Type: application/json" \
        --header "Authorization: Bearer YOUR_TOKEN_HERE" \
        --silent --show-error \
        --data '{"state": "Terminated"}'

   Python

   terminate_analysis.py

   import requests
   
   
   def terminate_analysis(token: str, analysis_id: str):
       url = f"https://ra.dnv.com/api/analysis/analyses/{analysis_id}/state"
   
       headers = {
           "Content-Type": "application/json",
           "Authorization": f"Bearer {token}",
       }
   
       response = requests.put(url, headers=headers, json={"state": "Terminated"})
   
       if response.ok:
           print("Analysis successfully terminated:")
           if response.text:
               print(response.json())
       else:
           print(f"Error {response.status_code}: {response.text}")
   
   
   if __name__ == "__main__":
       my_analysis_id = "YOUR_ANALYSIS_ID_HERE"  # Replace with actual analysis ID
       my_token = "YOUR_TOKEN_HERE"              # Replace with your actual token
   
       terminate_analysis(token=my_token, analysis_id=my_analysis_id)

6. Delete analysis data when no longer needed (optional).

   Bash

   terminal

   curl --request DELETE https://ra.dnv.com/api/analysis/analyses/YOUR_ANALYSIS_ID_HERE \
        --header "Content-Type: application/json" \
        --header "Authorization: Bearer YOUR_TOKEN_HERE" \
        --silent --show-error

   Python

   delete_analysis.py

   import requests
   
   
   def delete_analysis(token: str, analysis_id: str):
       url = ("https://ra.dnv.com/api/analysis"
           f"/analyses/{analysis_id}")
   
       headers = {
           "Content-Type": "application/json",
           "Authorization": f"Bearer {token}",
       }
   
       response = requests.delete(url, headers=headers)
   
       if response.ok:
           print("Analysis successfully deleted:")
           if response.text:
               print(response.json())
       else:
           print(f"Error {response.status_code}: {response.text}")
   
   
   if __name__ == "__main__":
       my_analysis_id = "YOUR_ANALYSIS_ID_HERE"  # Replace with actual analysis ID
       my_token = "YOUR_TOKEN_HERE"              # Replace with your actual token
   
       delete_analysis(token=my_token, analysis_id=my_analysis_id)

Get overview over analyses / Retrieve analysis IDs

To get an overview over all analyses listed with your user, please use the following. The received analysis ID(s) will then allow you to follow the steps 3 to 6 above, additional information about the analysis state and submit time allows identification.

Bash

terminal

curl --request GET https://ra.dnv.com/api/analysis/analyses \
     --header "Content-Type: application/json" \
     --header "Authorization: Bearer YOUR_TOKEN_HERE" \
     --silent --show-error

Python

get_user_analyses.py

import requests


def get_user_analyses(token: str):
    url = "https://ra.dnv.com/api/analysis/analyses"

    headers = {
        "Content-Type": "application/json",
        "Authorization": f"Bearer {token}",
    }

    response = requests.get(url, headers=headers)

    if response.ok:
        print("Analyses for this user obtained successfully:")
        if response.text:
            print(response.json())
    else:
        print(f"Error {response.status_code}: {response.text}")


if __name__ == "__main__":
    my_token = "YOUR_TOKEN_HERE"              # Replace with your actual token

    get_user_analyses(token=my_token)

Access individual runs

Get run IDs for an analysis

In order to look into an analysis in more detail, it is often helpful to investigate the individual runs. To access them, their run IDs are required, which can be obtained with the following command.

Bash

terminal

curl --request GET https://ra.dnv.com/api/analysis/analyses/YOUR_ANALYSIS_ID_HERE/runs \
     --header "Content-Type: application/json" \
     --header "Authorization: Bearer YOUR_TOKEN_HERE" \
     --silent --show-error

Python

get_analysis_run_ids.py

import requests


def get_analysis_run_ids(token: str, analysis_id: str):
    url = ("https://ra.dnv.com/api/analysis"
        f"/analyses/{analysis_id}/runs")

    headers = {
        "Content-Type": "application/json",
        "Authorization": f"Bearer {token}",
    }

    response = requests.get(url, headers=headers)

    if response.ok:
        print("Run IDs for this analysis obtained successfully:")
        if response.text:
            print(response.json())
    else:
        print(f"Error {response.status_code}: {response.text}")


if __name__ == "__main__":
    my_token = "YOUR_TOKEN_HERE"              # Replace with your actual token
    my_analysis_id = "YOUR_ANALYSIS_ID_HERE"  # Replace with actual analysis ID
    get_analysis_run_ids(token=my_token, analysis_id=my_analysis_id)

Get run states for an analysis

To not only obtain the run IDs, but also the corresponding state of the run, please use the following.

Bash

terminal

curl --request GET https://ra.dnv.com/api/analysis/analyses/YOUR_ANALYSIS_ID_HERE/runs/state \
     --header "Content-Type: application/json" \
     --header "Authorization: Bearer YOUR_TOKEN_HERE" \
     --silent --show-error

Python

get_analysis_run_states.py

import requests


def get_analysis_run_states(token: str, analysis_id: str):
    url = ("https://ra.dnv.com/api/analysis"
        f"/analyses/{analysis_id}/runs/state")

    headers = {
        "Content-Type": "application/json",
        "Authorization": f"Bearer {token}",
    }

    response = requests.get(url, headers=headers)

    if response.ok:
        print("Run states for this analysis obtained successfully:")
        if response.text:
            print(response.json())
    else:
        print(f"Error {response.status_code}: {response.text}")


if __name__ == "__main__":
    my_token = "YOUR_TOKEN_HERE"              # Replace with your actual token
    my_analysis_id = "YOUR_ANALYSIS_ID_HERE"  # Replace with actual analysis ID

    get_analysis_run_states(token=my_token, analysis_id=my_analysis_id)

Get run logs for an analysis

In order to understand why a run has failed, or what has happened during the modelling, the run logs can provide useful insight. Use the run ID obtained with one of the methods above.

Bash

terminal

curl --request GET https://ra.dnv.com/api/analysis/analyses/YOUR_ANALYSIS_ID_HERE/runs/YOUR_RUN_ID_HERE/logs \
     --header "Content-Type: application/json" \
     --header "Authorization: Bearer YOUR_TOKEN_HERE" \
     --silent --show-error

Python

get_run_logs.py

import requests


def get_run_logs(token: str, analysis_id: str, run_id: str):
    url = ("https://ra.dnv.com/api/analysis"
        f"/analyses/{analysis_id}/runs/{run_id}/logs")

    headers = {
        "Content-Type": "application/json",
        "Authorization": f"Bearer {token}",
    }

    response = requests.get(url, headers=headers)

    if response.ok:
        print("Run logs obtained successfully:")
        if response.text:
            import json
            print(json.dumps(response.json(), indent=2))
    else:
        print(f"Error {response.status_code}: {response.text}")


if __name__ == "__main__":
    my_token = "YOUR_TOKEN_HERE"              # Replace with your actual token
    my_analysis_id = "YOUR_ANALYSIS_ID_HERE"  # Replace with actual analysis ID
    my_run_id = "YOUR_RUN_ID_HERE"            # Replace with actual run ID

    get_run_logs(token=my_token, analysis_id=my_analysis_id, run_id=my_run_id)

Get results for an individual run

Results for an individual run can be retrieved using the following commands.

Bash

terminal

curl --request GET https://ra.dnv.com/api/analysis/analyses/YOUR_ANALYSIS_ID_HERE/runs/YOUR_RUN_ID_HERE/results \
     --header "Content-Type: application/json" \
     --header "Authorization: Bearer YOUR_TOKEN_HERE" \
     --silent --show-error

Python

get_run_results.py

import requests


def get_run_results(token: str, analysis_id: str, run_id: str):
    url = ("https://ra.dnv.com/api/analysis"
        f"/analyses/{analysis_id}/runs/{run_id}/results")

    headers = {
        "Content-Type": "application/json",
        "Authorization": f"Bearer {token}",
    }

    response = requests.get(url, headers=headers)

    if response.ok:
        print("Run results obtained successfully:")
        if response.text:
            import json
            print(json.dumps(response.json(), indent=2))
    else:
        print(f"Error {response.status_code}: {response.text}")


if __name__ == "__main__":
    my_token = "YOUR_TOKEN_HERE"              # Replace with your actual token
    my_analysis_id = "YOUR_ANALYSIS_ID_HERE"  # Replace with actual analysis ID
    my_run_id = "YOUR_RUN_ID_HERE"            # Replace with actual run ID

    get_run_results(token=my_token, analysis_id=my_analysis_id, run_id=my_run_id)

Get figures for an individual run

Figures for an individual run can be retrieved using the following commands.

Bash

terminal

curl --request GET https://ra.dnv.com/api/analysis/analyses/YOUR_ANALYSIS_ID_HERE/runs/YOUR_RUN_ID_HERE/figures \
     --header "Content-Type: application/json" \
     --header "Authorization: Bearer YOUR_TOKEN_HERE" \
     --silent --show-error

Python

get_run_figures.py

import requests


def get_run_figures(token: str, analysis_id: str, run_id: str):
    url = ("https://ra.dnv.com/api/analysis"
        f"/analyses/{analysis_id}/runs/{run_id}/figures")

    headers = {
        "Content-Type": "application/json",
        "Authorization": f"Bearer {token}",
    }

    response = requests.get(url, headers=headers)

    if response.ok:
        print("Run figures obtained successfully:")
        if response.text:
            import json
            print(json.dumps(response.json(), indent=2))
    else:
        print(f"Error {response.status_code}: {response.text}")


if __name__ == "__main__":
    my_token = "YOUR_TOKEN_HERE"              # Replace with your actual token
    my_analysis_id = "YOUR_ANALYSIS_ID_HERE"  # Replace with actual analysis ID
    my_run_id = "YOUR_RUN_ID_HERE"            # Replace with actual run ID

    get_run_figures(token=my_token, analysis_id=my_analysis_id, run_id=my_run_id)

API Cheat Sheet

Action	curl command
Queue analysis	POST https://todo-api-url.dnv.com/analyses
Analysis overview	GET https://todo-api-url.dnv.com/analyses
Analysis state	GET https://todo-api-url.dnv.com/analyses/YOUR_ANALYSIS_ID_HERE/state
Analysis results	GET https://todo-api-url.dnv.com/analyses/YOUR_ANALYSIS_ID_HERE/runs/results
Cancel analysis	PUT https://todo-api-url.dnv.com/analyses/YOUR_ANALYSIS_ID_HERE/state data state: Cancelled
Terminate analysis	PUT https://todo-api-url.dnv.com/analyses/YOUR_ANALYSIS_ID_HERE/state data state: Terminated
Delete analysis	DELETE https://todo-api-url.dnv.com/analyses/YOUR_ANALYSIS_ID_HERE
Get run IDs	GET https://todo-api-url.dnv.com/analyses/YOUR_ANALYSIS_ID_HERE/runs
Get run states	GET https://todo-api-url.dnv.com/analyses/YOUR_ANALYSIS_ID_HERE/runs/state
Get run logs	GET https://todo-api-url.dnv.com/analyses/YOUR_ANALYSIS_ID_HERE/runs/YOUR_RUN_ID_HERE/logs
Get run results	GET https://todo-api-url.dnv.com/analyses/YOUR_ANALYSIS_ID_HERE/runs/YOUR_RUN_ID_HERE/results
Get run figures	GET https://todo-api-url.dnv.com/analyses/YOUR_ANALYSIS_ID_HERE/runs/YOUR_RUN_ID_HERE/figures