Openwind Online Help

HTTP server mode allows OpenWind to be controlled by external program using HTTP requests.

HTTP mode is started using commandline parameter -server with optional number specifying TCP/IP port (default is 8833). This starts a server session. Server session acts as single instance of OpenWind that can be controlled and queried for results and data over HTTP.

Where possible, OpenWind HTTP API follows REST design. That in practice means:

•Data are represented by content of HTTP message and formatted as JSON. URL designates the type of data and if necessary, id of element (e.g. id of layer). Additional parameters can be passed passed as url query fields.

•GET HTTP verb is used to retrieve the element data (as content of reply). GET is guaranteed to never modify the workbook.

•PUT verb is used to update (change) the element with content of HTTP query.

•GET and PUT usually come in pairs and the JSON format of content and url used to identify the element is always the same

•DELETE verb is used to delete the element. URL used to identify the element is the same as for GET and PUT.

•POST is used to add a new element to the workbook. The format of content of query is sometimes the same as the one for GET/PUT, but sometimes the elements is created from different resources (e.g. loading the image from the filesystem). This can be described by url query fields (e.g. there can be 'path' field with file path of source data).

•In addition, whenever there are commands that do not match REST design well, POST is used too here - example is starting the energy capture.

Another specific issue is the fact that some operations, like energy capture, cannot be finished within HTTP request timeout period. For this reason HTTP requests are just start the operation and return immediately. Any subsequent request returns HTTP code 202 processing until the operation is finished. In this case, the content of reply can also contain the description of operation in progress and also the actual progress of the operation as FP number:

HTTP/1.1 102 Processing

Date: Tue, 5 Mar 2019 11:31:11 +0100

Server: U++ based server

Connection: close

Content-Length: 81

Content-Type: application/json; charset=utf-8

 

{"status":"BUSY","operation":"Server energy capture","progress":0.38330518018018}

 

Recommended approach is to use active wait with /info request (repeated e.g. after 1 second) until it returns 200 OK, then continue with further operations.

Examples of HTTP requests:

This request returns current workbook settings:

GET /settings HTTP/1.1

URL: http://localhost:8833/settings

Host: localhost:8833

Connection: close

Accept: */*

Accept-Encoding: gzip

User-Agent: U++ HTTP request

OpenWind reply:

HTTP/1.1 200 OK

Date: Mon, 6 Aug 2018 19:23:49 +0200

Server: U++ based server

Connection: close

Content-Length: 142

Content-Type: application/xml; charset=utf-8

 

{"WorkBook":{"EPSG":32610,"AirLapseRate":-0.113 …

 

This request changes the EPSG value of the workbook:

PUT /settings HTTP/1.1

URL: http://localhost:8833/settings

Host: localhost:8833

Connection: close

Accept: */*

Accept-Encoding: gzip

User-Agent: U++ HTTP request

Content-Length: 16

Content-Type: application/x-www-form-urlencoded

 

{"WorkBook":{"EPSG":"32610"}}

 

Available requests

GET /info

This command is form of "ping" to server and just returns JSON with "status:OK". It is useful to check that server is running and also for active waiting loops. If some longer process (energy capture, cost calculation or optimisation) is running on server, returns information about the process in “info” field.

PUT /stop

Initiates stop of long running proces (capture, optimisation). Not that stop is not immediate, server might reply 102 for some more time after stop was initiated.

GET /settings

Returns the global settings of workbook. The format is equivalent to menu command Settings / Save Settings to File..

PUT /settings

Changes the workbook settings

POST /clear

Sets workbook to empty initial state.

POST /load

Loads the workbook from the file identified by 'path' url query field.

GET /save

Saves the workbook to the file identified by 'path' url query field.

GET /layers

Returns the complete tree of all layers with basic information about each layer (id, name, type).

GET /layer/id

Returns the information about layer identified by id as JSON. Format depends on layer type, but is equivalent to the format obtained from layer context menu in JSON format:

 

GET layer/save/id

Saves the layer to the file identified by 'path' url query field in format based on extension of “path”. Generally all of formats supported by GUI OpenWind in layer export are available here too as long as the layer is compatible with it. In addition, OpenWind’s internal format “.bly” can be used.

 

GET layer/export_ti/id

Exports turbulence intensity from Meteorological Mast Layer  to the file identified by 'path' url query field in format based on extension of “path”. Supported extensions are .json, .xml, .csv and .txt.

 

GET layer/image/id

If there is raster image representation of layer, exports this image in PNG format. If there is 'path' url query field, image is saved to that path, otherwise it is returned as HTTP response.

 

PUT /layer/id

Updates the layer identified by id. New settings are represented by request content and are in the same format as returned by GET. Moving layer to another parent can be achieved by setting new parent_id in JSON.

 

DELETE /layer/id

Removes the layer identified by id.

 

POST /layer

This adds a new layer to the workbook. New layer can either be a copy of existing layer or be created by importing the file.

Optional URL query fields:

source_id - id of source layer (if present, command creates a copy of source layer).

path - path of source file to load into newly created layer for specific types (see below).

parent_id - if present, new layer is created as child of parent_id, if not present, it is created at root level.

epsg - epsg code layer. If not present, it is deducted from the associated .prj file.

type - if present, specifies type of layer to be created. If empty, type is deducted based on file extension. Following types are created by loading from the path (if type is not present and path exists, layers can be created based on path extension):

Another set of types is created from request content JSON (same format as for PUT and GET). These types can also be used on loading or copying to eventually convert the layer to destination type (this mostly concerns conversions from and to PointLayer):

Yet another specials set of types makes server load data from AWS:

If none of above types is matched, the default type is Raster layer loaded from the path.

Request returns JSON with id of the new layer.

 

PUT /layer/adjust_to_masts/id

This command is specific to wind resource grid layers and is equivalent to “Adjust To Mast” layer operation. Content can contain JSON with settings, format is equivalent to Save/Load JSON format in “Adjust To Mast” dialog.

 

POST:layer/create_validity/id

Creates validity rasters for metmasts. id must represent WRG layer with metmasts

 

POST:layer/create_uncertainty/id

Creates uncertainty rasters for metmasts. id must represent WRG layer with metmasts

 

GET layer/adjust_to_masts_explore/id

This retrieves an equivalent data to tables in Adjust To Mast dialog after Explore parameters button is pressed:

Setup of metmast dialog can be specified as url query fields: adjust_down_only, elevation_adjustment, overwrite_probabilities, elevation_pc, maximum_adjustment, switch_ratios, elev_adj_max, lowest, ratios, all.

 

 

PUT /layer/autoplace_turbines/id

This command is specific to site layers and is equivalent to “Autoplace” action of Site layer properties, with option to specify the turbine type. The command changes the number of turbines in site layer to specific count, either removing turbines or adding new turbines at random positions. 'count' url query field specifies the required number of turbines. Turbine type can be specfied either by 'type_id' url query field or 'name' url query field, if not present the default turbine type for layer is used. 'mode' url query field is only relevant if count of turbines is less than actual number of turbines in the layer and specifies the method to remove turbines:  'random' ,  'last' or  'first'. If not specified, 'first' is assumed.

 

PUT /layer/replace_all_tables/id

This command is specific to meteorologic mast layer and is equivalent to "Replace all tables" function.

 

 

GET /layer/turbine_availability/id

Stores turbine availability data from SiteLayer (used for operational assessment) in csv format to file specified by 'path' url query field.

 

PUT /layer/turbine_availability/id

Loads SiteLayer turbine availability         data (used for operational assessment) from csv file specified by 'path' url query field.

 

GET /layer/turbine_production/id

Stores turbine production data from SiteLayer (used for operational assessment) in csv format to file specified by 'path' url query field.

 

PUT /layer/turbine_production/id

Loads SiteLayer turbine production data (used for operational assessment) from csv file specified by 'path' url query field.

 

GET /layer/nacelle_windspeeds/id

Stores nacelle windspeeds data from SiteLayer (used for operational assessment) in csv format to file specified by 'path' url query field.

 

PUT /layer/nacelle_windspeeds/id

Loads SiteLayer nacelle windspeeds data (used for operational assessment) from csv file specified by 'path' url query field.

 

GET /layer/nacelle_temperatures/id

Stores nacelle temperatures data from SiteLayer (used for operational assessment) in csv format to file specified by 'path' url query field.

 

PUT /layer/nacelle_temperatures/id

Loads SiteLayer nacelle temperatures data (used for operational assessment) from csv file specified by 'path' url query field.

 

GET /turbine_types

Returns JSON with all turbine types in the workbook.

 

PUT /turbine_type

This command updates or replaces the existing turbine type. Turbine type is indentified by either name or id query fields. Turbine type can be in .wtg, .json, .owtg or .tbn format. Data can be transfered as HTTP content or can be loaded from path URL query field. Format is decided based on path extension or can be explictly specified in format URL query field.

 

POST /turbine_type

Adds a new turbine type. Turbine type can be in .wtg, .json, .owtg or .tbn format. Data can be transfered as HTTP content or can be loaded from path URL query field. Format is decided based on path extension or can be explictly specified in format URL query field. Returns id of new turbine type.

 

PUT /turbine_type_rename

Renames the turbine type. Turbine type is indentified by either 'name' or 'id' query fields. Another query field, 'newname', specifies the new name of turbine type.

 

PUT /global_ice_losses

Sets global ice losses table. Data can be transfered as HTTP JSON content or can be loaded from path URL query field. If path is use, then the file is loaded as JSON if it has JSON extension, otherwise csv format same as the one used in GUI is expected.

 

GET /global_ice_losses

Returns global ice losses table as JSON.

 

GET /turbines

Returns JSON that lists all turbines (name, type_id, position x and y) of all turbines, grouped by site layers.

 

PUT /turbines

Replaces turbines. The content must be the JSON in the same format as for GET /turbines.

 

 

GET /noise_reduced_modes

PUT /noise_reduced_modes

Reads / writes settings equivalent to "Noise Reduced Operating Modes" dialog.

 

GET/effective_ti

PUT/effective_ti

Reads / writes settings equivalent to "Effective Turbulence Intensity" dialog.

 

GET/rotor_equivalent_ws

PUT/rotor_equivalent_ws

Reads / writes settings equivalent to "Rotor Equivalent Wind Speed" dialog.

 

GET/uncertainty

PUT/uncertainty

Reads / writes settings equivalent to "Uncertainty" dialog.

 

GET/shadow_flicker

PUT/shadow_flicker

Reads / writes settings equivalent to "Shadow Flicker" dialog.

 

GET/noise

PUT/noise

Reads / writes settings equivalent to "Noise" dialog.

 

 

GET/zvi

PUT/zvi

Reads / writes settings equivalent to "Visual Impact" dialog.

 

GET /energy_capture_parameters

Returns energy capture paremeters.

 

PUT /energy_capture_parameters

Sets energy capture parameters. The content must be the JSON in the same format as for GET /energy_capture_parameters.

 

GET /cost_parameters

Returns parameters for cost based capture / optimization (like cable costs etc).

 

PUT /cost_parameters

Sets cost parameters. The content must be the JSON in the same format as for GET /cost_parameters.

 

GET /optimiser_parameters

Returns optimiser options.

 

PUT /optimiser_parameters

Sets optimiser options. The content must be the JSON in the same format as for GET /optimiser_parameters.

 

POST /energy_capture

Starts energy capture. Until the energy capture is finished, all subsequent requests to server fail with code 202 "processing". Can be aborted using POST /stop command.

 

POST /cost_of_energy

Starts cost of energy capture. Until the energy capture is finished, all subsequent requests to server fail with code 202 "processing". Can be aborted using POST /stop command.

 

POST /energy_optimiser

Starts optimization for maximum energy. All subsequent requests to server fail with code 202 "processing". GET /info request returns some basic information about the optimization process. Can be stopped using POST /stop command.

 

POST /cost_optimiser

Starts cost/revenue based optimization. All subsequent requests to server fail with code 202 "processing". GET /info request returns some basic information about the optimization process. Can be stopped using POST /stop command.

 

GET /report

Returns the report of latest energy capture or cost of energy capture. Query field 'format' can specify the output format, possible values are 'json' (which is default), 'xml', 'csv' and 'text'.

 

GET /timeseries_default_settings

Returns the default settings of GET /timeseries request. This also serves for documentation purposes as it presents the JSON structure to be used with GET /timeseries

 

GET /timeseries

POST /timeseries

Returns the timeseries report. The body can contain JSON with report description with the same format as the one retrieved by GET /timeseris_default_settings. Note: POST variant is the same and is provided because not all HTTP clients allow to send body in GET request.

 

GET /suitability_inflow_angles

Returns report corresponding to File / Reports.. / Suitability – Inflow Angles. Output format is defined by format query parameter with possible values "json" (default), "xml",  "text" and "csv".

 

GET /suitability_weibulls

Returns report corresponding to File / Reports.. / Suitability – Weibulls. Output format is defined by format query parameter with possible values "json" (default), "xml",  "text" and "csv".

 

GET /suitability_turbine_types

Returns report corresponding to File / Reports.. / Suitability – Turbine Types. Output format is defined by format query parameter with possible values "json" (default), "xml",  "text" and "csv".

 

GET /suitability_effective_ti

Returns report corresponding to File / Reports.. / Suitability – Effective TI. Output format is defined by format query parameter with possible values "json" (default), "xml",  "text" and "csv".

 

GET /suitability_total_ti

Returns report corresponding to File / Reports.. / Suitability – Total TI. Output format is defined by format query parameter with possible values "json" (default), "xml",  "text" and "csv".

 

GET /suitability_shear_coefficients

Returns report corresponding to File / Reports.. / Suitability – Shear Coefficients. Output format is defined by format query parameter with possible values "json" (default), "xml",  "text" and "csv".

 

GET /suitability_probabilities

Returns report corresponding to File / Reports.. / Suitability – Probabilities. Output format is defined by format query parameter with possible values "json" (default), "xml",  "text" and "csv". Report settings are passed as query parameters sectors (1-360), waked (0/1), split (0/1), centers (0/1).

 

GET /suitability_pseudo_equivalent_loads

Returns report corresponding to File / Reports.. / Pseudo-Equivalent Loads. Output format is defined by format query parameter with possible values "json" (default), "xml",  "text" and "csv".

 

GET /suitability_IEC61400

Returns report corresponding to File / Reports.. / Suitability - IEC61400-1 Section 11. Output format is defined by format query parameter with possible values "json" (default), "xml",  "text" and "csv".

 

GET /suitability_suitability_vref_mis

Returns report corresponding to File / Reports.. / Suitability - Vref (MIS Gumbel). Output format is defined by format query parameter with possible values "json" (default), "xml",  "text" and "csv". Report setting is passed with query parameter speedups (0/1).

 

GET /suitability_suitability_vref_ewst

Returns report corresponding to File / Reports.. / Suitability - Vref (MIS Gumbel). Output format is defined by format query parameter with possible values "json" (default), "xml",  "text" and "csv". Report setting is passed with query parameter method ("exact" / "gumbel" / "davenport").

 

GET /report_by_windspeed

Returns report corresponding to File / Reports.. / Report By Windspeed. Output format is defined by format query parameter with possible values "json" (default), "xml",  "text" and "csv". Report settings are passed as query parameters sectors (1-360), waked (0/1), step ( >= 1), field ("gross", "array", "net").

 

GET /report_speedups

Returns report corresponding to File / Reports.. / Speed Ups. Output format is defined by format query parameter with possible values "json" (default), "xml",  "text" and "csv".

 

GET /report_free_stream_windspeeds

Returns report corresponding to File / Reports.. / Free-Stream Windspeeds [m/s]. Output format is defined by format query parameter with possible values "json" (default), "xml",  "text" and "csv".

 

GET /report_waked_windspeeds

Returns report corresponding to File / Reports.. / Waked-Affected Windspeeds [m/s]. Output format is defined by format query parameter with possible values "json" (default), "xml",  "text" and "csv".

 

GET /report_probabilities

Returns report corresponding to File / Reports.. / Probabilities. Output format is defined by format query parameter with possible values "json" (default), "xml",  "text" and "csv".

 

GET /report_hours_per_year

Returns report corresponding to File / Reports.. / Hours Per Year. Output format is defined by format query parameter with possible values "json" (default), "xml",  "text" and "csv".

 

GET /report_power

Returns report corresponding to File / Reports.. / Power [kW]. Output format is defined by format query parameter with possible values "json" (default), "xml",  "text" and "csv".

 

GET /report_array_energy

Returns report corresponding to File / Reports.. / Array Energy [kWh] (gross-wakes). Output format is defined by format query parameter with possible values "json" (default), "xml",  "text" and "csv".

 

GET /report_array_efficiency

Returns report corresponding to File / Reports.. / Array Efficiency (array/gross). Output format is defined by format query parameter with possible values "json" (default), "xml",  "text" and "csv".

 

GET /report_gross_energy

Returns report corresponding to File / Reports.. / Gross Energy [kWh]. Output format is defined by format query parameter with possible values "json" (default), "xml",  "text" and "csv".

 

GET /report_net_energy

Returns report corresponding to File / Reports.. / Net Energy [kWh]. Output format is defined by format query parameter with possible values "json" (default), "xml",  "text" and "csv".

 

GET /report_ambient_ti

Returns report corresponding to File / Reports.. / Ambient Turbulence Intensity [%]. Output format is defined by format query parameter with possible values "json" (default), "xml",  "text" and "csv".

 

GET /report_wake_loss_tables

Returns report corresponding to File / Reports.. / Wake Loss Tables. Output format is defined by format query parameter with possible values "json" (default), "xml",  "text" and "csv". Optional bool parameter fractional corresponds to

 

GET /report_total_ti

Returns report corresponding to File / Reports.. / Total Turbulence Intensity [%]. Output format is defined by format query parameter with possible values "json" (default), "xml",  "text" and "csv".

GET /report_site_layer_power_curves

Returns report corresponding to File / Reports.. / Site Layer Power Curves. Output format is defined by format query parameter with possible values "json" (default), "xml",  "text" and "csv".

 

POST /calc_noise

Starts calculation of noise map(s). All subsequent requests to server fail with code 202 "processing". GET /info request returns some basic information about the optimization process. Can be stopped using POST /stop command. This process creates new layers in workbook; IDs of these layers can be obtained, after the calculation is finished, with GET /calc_layers request.

 

POST /calc_zvi

Starts calculation of visual impact map(s). All subsequent requests to server fail with code 202 "processing". GET /info request returns some basic information about the optimization process. Can be stopped using POST /stop command. This process creates new layers in workbook; IDs of these layers can be obtained, after the calculation is finished, with GET /calc_layers request.

 

POST /calc_sf

Starts calculation of shadow flicker map(s). All subsequent requests to server fail with code 202 "processing". GET /info request returns some basic information about the optimization process. Can be stopped using POST /stop command. This process creates new layers in workbook; IDs of these layers can be obtained, after the calculation is finished, with GET /calc_layers request.

 

GET /calc_layers

Returns IDs of layers created as results of calc_noise, calc_zvi, calc_sf requests as JSON map with keys:

 

POST /quit

Stops the server (OpenWind terminates)