WindFarmer Services API - getting started
Here we explain a recommended way to setup and check that the web API is running.
We walk you through getting your access key, then calling the API from either Postman or a Python script.
Access keys
To make a request to the API you need to provide a valid access key.
The access key is a time limited JWT token, it appears as a long random string of characters. When making calls to the API this is included in the request header as a bearer token.
Please keep this access key secure and treat it like a password.
WindFarmer services portal
To access and manage your access key for the WindFarmer API visit the WindFarmer Services Portal.
A veracity account is required to access the portal. Once a veracity account is created the WindFarmer team can grant access to the API key for a company admin user.
The Company admin user will be able to log in with their veracity credentials and access their company API key. Expand the Primary access token section then click Copy to get the key on your clipboard.
Please note that all access keys expire automatically after 1 year or less for security reasons.
The company admin can also regenerate new access keys.
Regenerating an access key will revoke the old access key. You may wish to do this if you suspect the key has been taken outside your company.
Environment variable to store API access key
A recommended secure way to store and use the access key is by saving it in an environment variable associated with your user profile. We will assume you have saved the key in an environment variable in any of the WindFarmerAutomation demos. You can set an environment variable as follows:
- Open edit system environment variables
- Go to Advanced > Environment variables
- Click New for User variables:
- Give the variable a name: “WINDFARMER_ACCESS_KEY”
- Paste in your access key
- Click OK to close and save the token.
From python…
You can now access the environment variable as a string from any python script importing the os
package and calling os.environ['WINDFARMER_ACCESS_KEY']
Note
You may need to restart your python environment to get updated environment variables.
Convenient generation of inputs
The simulation inputs are passed to the API as json, conforming to OpenAPI specification defined separately for each version of the API.
It is possible to compile such a file from scratch, following the specification. This is likely needed in the context of embedding
WindFarmer Services API in a custom, automated workflow (for example: layout optimisation).
However, to get started, it is easier to produce the json based on an exisiting WindFarmer:Analyst workbook
that contains the definitions of the wind farm, the wind climate and the modeling settings.
There is a Scripting method, which has been designed for that purpose: Toolbox.ExportWindFarmerEnergyJson()
.
Once the file is generated, it can be easily modified (programmatically or manually) or used straightaway to make an API call using Postman. The Python examples referenced below also start off from a json file pre-generated using WindFarmer:Analyst which then is modified to alter the simulation settings.
Python examples
Multiple python examples are provided in the automation examples repository. You may need to install some packages described below.
General packages required
From python you can call the API directly, using the urllib3
or requests
packages. Our examples use the requests package. You can simply install and use our wf_auto conda environment as described in the WindFarmerAutomation/README.md to reliably run our examples.
Alternatively you may install libraries into your own environment. To install requests, open a python command prompt for your chosen environment and install:
Installation using Pip:
$ python -m pip install requests
Installation using Conda:
conda install -c anaconda requests
The examples also use the following packages:
- os for accessing environment variables
- Json for reading the json response from API
- Time for timing certain functions
- Pandas for parsing in text data
- Matplotlib for plotting and checking some inputs
Jupyter notebooks
Jupyter notebooks [.ipynb files] can be run in several IDEs to provide an interactive python environment interspersed with documentation. It will take you through the process of accessing the API step-by-step. Compatible IDEs include Jupyter Notebook, Jupyter Lab, Visual Studio Code (with an extension), or Spyder with the notebook plugin.
Python scripts [.PY files]:
Other examples are provided as Python scripts (.Py files). These can be run in any python environment with the necessary packages.