Skip to content

Web API documentation

Protected parts of the Web API is marked with an locked icon. These requests require an Authorization header.

Parts of the API marked with an grouped icon only applies to grouped (hierarchical) connection types.

Parts of the API marked with an updatable icon only applies to updatable connection types.

Accounts

Connections

Email Templates

Spreadsheets

Tables

Time Series

Time Step Data

Feature Collections

Maps

Job Hosts

Tasks

Jobs

Zones

Radar Images

Accounts

Account ID

The unique identifier of an account is a string (e.g. "john.doe" or "john.doe@acme.com")

URIs

POST api/account locked

Adds a new account. Adding a new account automatically activates the account.

Example:

POST api/account
Content-Type: application/json
Authorization: Basic YWRtaW46VGhpc0lzTm90VGhlUmVhbFBhc3N3b3JkIQ==

{
  "Id": "john.doe",
  "Name": "John Doe",
  "Email": "john.doe@acme.com",
  "Password": "password",
  "Roles": "Guest, User"
}

PUT api/account locked

Updates an existing account. The password can be omitted from an update, but all other properties must be present. Otherwise, they will be set to null.

Example:

PUT api/account
Content-Type: application/json
Authorization: Basic YWRtaW46VGhpc0lzTm90VGhlUmVhbFBhc3N3b3JkIQ==

{
  "Id": "john.doe",
  "Name": "John Doe",
  "Email": "john.doe@acme.com",
  "Roles": "Guest, User, Editor"
}

POST api/account/registration

Performs an account registration. An account registration must be followed by an account activation before the account is activated and valid. A one-time activation token is generated and an activation link with the generated reset token is sent to the user account in an email.

Example:

POST api/account/registration
Content-Type: application/json

{
  "Id": "john.doe",
  "Name": "John Doe",
  "Email": "john.doe@acme.com",
  "Password": "password",
}

PUT api/account/activation?&token={token}

Performs an account activation. The necessary activation token must be obtained from e.g. an email or a mobile text message.

Example:

PUT api/account/activation?token=m5Am6dw15dCIGIpCZYpFXL5sHE8=

POST api/account/validation

Performs an account validation. Checks whether the account exists, the password is correct and the account is activated.

Example:

POST api/account/validation
Content-Type: application/json

{
  "Id": "john.doe",
  "Password": "password"
}

POST api/account/passwordreset

Generates a one-time token that allows for a password reset for the account identified by the given email address or account ID. A password reset link with the generated reset token is sent to the user account in an email.

Example:

POST api/account/passwordreset
Content-Type: application/json

"john_doe@acme.com"

PUT api/account/password?token={token}

Updates the password for the user account associated with the given token. The necessary password reset token must be obtained from e.g. an email or a mobile text message.

Example:

PUT api/account/password?token=m5Am6dw15dCIGIpCZYpFXL5sHE8=
Content-Type: application/json

"MyNewPassword"

PUT api/account/me locked

Modifies the account of the calling user. He can modify his Password as well as the Email, PhoneNumber and Company properties. If any of these properties are ommitted in the body, they will be set to null. Other account properties cannot be modified.

Example:

PUT api/account/me 
Content-Type: application/json
Authorization: Basic YWRtaW46VGhpc0lzTm90VGhlUmVhbFBhc3N3b3JkIQ==

{
  "Id": "john.doe",
  "Password": "MyNewPassword",
  "Email": "john_doe@acme.com"
}

GET api/account/{id} locked

Returns an account with the given id.

Example:

GET api/account/John.Doe
Authorization: Basic YWRtaW46VGhpc0lzTm90VGhlUmVhbFBhc3N3b3JkIQ==

GET api/account/list locked

Returns a list of all accounts.

GET api/account/count locked

Returns the total number of accounts.

DELETE api/account/{id} locked

Removes an account with the given id.

Example:

DELETE api/account/John.Doe
Authorization: Basic YWRtaW46VGhpc0lzTm90VGhlUmVhbFBhc3N3b3JkIQ==

Account representation

{
  "Id": "john.doe",
  "Name": "John Doe",
  "Email": "john.doe@acme.com",
  "Company": "Acme",
  "PhoneNumber": "+00199123456",
  "Roles": "Guest, User"
}

Connections

A connection holds information about specific provider types to be used for a specific type of service – e.g. a MIKE res1d repository to be used in a time series service. Furthermore, the connection defines connection information such as a file path or a connection string to a particular database and possible other necessary information for establishing the connection.

Connection ID

The unique identifier of a connection is a string (e.g. "mc-ts" or "dims-ts")

URIs

POST api/connection locked

Adds a new connection. The connection representation must define the connection type using the $type property.

Example:

POST api/connection 
Content-Type: application/json
Authorization: Basic YWRtaW46VGhpc0lzTm90VGhlUmVhbFBhc3N3b3JkIQ==

{
  "$type": "DHI.Services.MapServiceConnection, DHI.Services",
  "MapSourceConnectionString": "C:\\temp\\data\\sample.dfs2",
  "MapSourceProperties": {
    "prop1": "value1",
    "prop2": "value2"
  },
  "MapSourceType": "DHI.Services.Provider.MIKE.Dfs2MapSource, DHI.Services.Provider.MIKE",
  "MapStyleConnectionString": "C:\\temp\\styles.json",
  "MapStyleRepositoryType": "DHI.Services.Provider.MapStyleRepository, DHI.Services.Provider",
  "Name": "Dfs2 map connection",
  "Id": "dfs2-map"
}

PUT api/connection locked

Updates an existing connection. The connection representation must define the connection type using the $type property.

Example:

PUT api/connection 
Content-Type: application/json
Authorization: Basic YWRtaW46VGhpc0lzTm90VGhlUmVhbFBhc3N3b3JkIQ==

{
  "$type": "DHI.Services.MapServiceConnection, DHI.Services",
  "MapSourceConnectionString": "[AppData]sample.dfs2",
  "MapSourceType": "DHI.Services.Provider.MIKE.Dfs2MapSource, DHI.Services.Provider.MIKE",
  "MapStyleConnectionString": "[AppData]styles.json",
  "MapStyleRepositoryType": "DHI.Services.Provider.MapStyleRepository, DHI.Services.Provider",
  "Name": "Dfs2 map connection",
  "Id": "dfs2-map"
}

POST api/connection/verification locked

Verifies that a new connection is valid – i.e. that the connection can be established. The connection representation must define the connection type using the $type property.

Example:

POST api/connection/verification
Content-Type: application/json
Authorization: Basic YWRtaW46VGhpc0lzTm90VGhlUmVhbFBhc3N3b3JkIQ==

{
  "$type": "DHI.Services.MapServiceConnection, DHI.Services",
  "MapSourceConnectionString": "C:\\temp\\data\\sample.dfs2",
  "MapSourceProperties": {
    "prop1": "value1",
    "prop2": "value2"
  },
  "MapSourceType": "DHI.Services.Provider.MIKE.Dfs2MapSource, DHI.Services.Provider.MIKE",
  "MapStyleConnectionString": "C:\\temp\\styles.json",
  "MapStyleRepositoryType": "DHI.Services.Provider.MapStyleRepository, DHI.Services.Provider",
  "Name": "Dfs2 map connection",
  "Id": "dfs2-map"
}

GET api/connection/{id}/verification locked

Verifies that an existing connection with the given is valid – i.e. that the connection can be established.

Example:

GET api/connection/mc-ts/verification
Authorization: Basic YWRtaW46VGhpc0lzTm90VGhlUmVhbFBhc3N3b3JkIQ==

GET api/connection/{id} locked

Returns a connection with the given id.

Example:

GET api/connection/mc-ts
Authorization: Basic YWRtaW46VGhpc0lzTm90VGhlUmVhbFBhc3N3b3JkIQ==

GET api/connection/list locked

Returns a list of all connections.

GET api/connection/count locked

Returns the total number of connections.

DELETE api/connection/{id} locked

Removes a connection with the given id.

Example:

DELETE api/connection/mc-ts
Authorization: Basic YWRtaW46VGhpc0lzTm90VGhlUmVhbFBhc3N3b3JkIQ==

Retrieving connection types

GET api/connection/type/ids locked

Returns a list of connection type identifiers.

GET api/connection/type/list locked

Returns a list of all connection types.

GET api/connection/type/{id} locked

Returns a connection type with the given id.

Example:

GET api/connection/type/MapServiceConnection
Authorization: Basic YWRtaW46VGhpc0lzTm90VGhlUmVhbFBhc3N3b3JkIQ==

Connection representations

Time Series

{
  "ConnectionString": "[AppData]dfs0",
  "RepositoryType": "DHI.Services.Provider.MIKE.Dfs0GroupedTimeSeriesRepository, DHI.Services.Provider.MIKE",
  "Name": "MIKE dfs0 time series connection",
  "Id": "dfs0-ts"
}

Job Service

{
  "JobRepositoryConnectionString": "jobs.json",
  "JobRepositoryType": "DHI.Services.Web.JobRepository, DHI.Services.Web",
  "TaskRepositoryConnectionString": "[AppData]workflows.json",
  "TaskRepositoryType": "DHI.Services.Provider.WF.WorkflowRepository, DHI.Services.Provider.WF",
  "Name": "Workflow jobs",
  "Id": "wf-jobs"
}

Connection Type representation

{
  "ProviderArguments": [
    {
      "Mandatory": true,
      "Name": "MapSourceConnectionString",
      "Type": "System.String, mscorlib"
    },
    {
      "Mandatory": true,
      "Name": "MapStyleConnectionString",
      "Type": "System.String, mscorlib"
    },
    {
      "Mandatory": true,
      "Name": "MapSourceProperties",
      "Type": "DHI.Services.Parameters, DHI.Services"
    }
  ],
  "ProviderTypes": [
    {
      "Mandatory": true,
      "Name": "MapSourceType",
      "Options": [
        "DHI.Services.Provider.NetCDF.MapSource, DHI.Services.Provider",
        "DHI.Services.Provider.MIKE.Dfs2MapSource, DHI.Services.Provider.MIKE",
        "DHI.Services.Provider.MIKE.DfsuMapSource, DHI.Services.Provider.MIKE"
      ]
    },
    {
      "Mandatory": true,
      "Name": "MapStyleRepositoryType",
      "Options": [
        "DHI.Services.Provider.MapStyleRepository, DHI.Services.Provider",
        "DHI.Services.Web.MapStyleRepository, DHI.Services.Web"
      ]
    }
  ],
  "Type": "DHI.Services.Web.MapServiceConnection, DHI.Services.Web",
  "Id": "MapServiceConnection"
}

Email templates

Email Template ID

The unique identifier of an email template is a string (e.g. "MyEmailTemplate").

URIs

POST api/mailtemplate locked

Adds a new email template.

Example:

POST api/mailtemplate
Content-Type: application/json
Authorization: Basic YWRtaW46VGhpc0lzTm90VGhlUmVhbFBhc3N3b3JkIQ==
{
  "Id": "AccountActivation",
  "Name": "Account activation email template",
  "Subject": "DHI WaterData - Signup",
  "Body": "<p style='font-family:verdana;font-size:16'>Hi {0} :-)</p>",
  "From": "noreply@dhigroup.com",
  "FromDisplayName": "DHI WaterData"
}

PUT api/mailtemplate locked

Updates an existing email template.

Example:

PUT api/mailtemplate
Content-Type: application/json
Authorization: Basic YWRtaW46VGhpc0lzTm90VGhlUmVhbFBhc3N3b3JkIQ==
{
  "Id": "AccountActivation",
  "Name": "Account activation email template",
  "Subject": "DHI FloodForecast - Signup",
  "Body": "<p style='font-family:verdana;font-size:16'>Hi {0} :-)</p>",
  "From": "noreply@dhigroup.com",
  "FromDisplayName": "DHI FloodForecast"
}

GET api/mailtemplate/{id}

Returns an email template with the given id.

Example:

GET api/mailtemplate/AccountActivation

GET api/mailtemplate/list

Returns a list of all email templates.

GET api/mailtemplate/ids

Returns a list of all email template identifiers.

GET api/mailtemplate/count

Returns the total number of email templates.

DELETE api/mailtemplate/{id} locked

Removes an email template with the given id.

Example:

DELETE api/mailtemplate/AccountActivation
Authorization: Basic YWRtaW46VGhpc0lzTm90VGhlUmVhbFBhc3N3b3JkIQ==

Email template representation

{
  "Id": "AccountActivation",
  "Name": "Account activation email template",
  "Subject": "DHI FloodForecast - Signup",
  "Body": "<p style='font-family:verdana;font-size:16'>Hi {0} :-)</p>",
  "From": "noreply@dhigroup.com",
  "FromDisplayName": "DHI FloodForecast"
}

Spreadsheets

Spreadsheet ID

The unique identifier of a spreadsheet is the "full-name" of the spreadsheet. The full-name is a combination of the group that the spreadsheet belongs to and the name of the spreadsheet - separated by a forward slash "/". The group itself can be a hierarchy of groups separated by forward slashes. If a spreadsheet does not belong to a group, the unique identifier is the name alone.

Example: MyGoup/MySubgroup/MySpreadSheet

NOTE: in the URIs, the forward slashes ("/") in a full-name identifier must be replaced by a pipe character ("|"). If the full-name identifier itself includes pipe characters ("|"), these must be escaped with another pipe-character – i.e. "|" must be replaced with "||".

Example:

GET api/spreadsheet/mc-sps/mygroup|mysubgroup|spreadsheet1/Sheet1/cell;R7C12

URIs

POST api/spreadsheet/{connectionId} locked

Adds a new spreadsheet.

Example:

POST api/spreadsheet/mclite
Content-Type: application/json
Authorization: Basic YWRtaW46VGhpc0lzTm90VGhlUmVhbFBhc3N3b3JkIQ==

{
  "FullName": "mygroup/spredsheet1",
  "SheetNames": [
    "Catchments",
    "Cities"
  ],
  "Data": [
    [
      [
        "Catchment Name",
        "Area"
      ],
      [
        "MyCatchementName",
        56250.87
      ]
    ],
    [
      [
        "City Name",
        "Population"
      ],
      [
        "Copenhagen",
        1000000
      ],
      [
        "London",
        10000000
      ]
    ]
  ]
}

PUT api/spreadsheet/{connectionId} locked

Updates an existing spreadsheet.

Example:

PUT api/spreadsheet/mclite
Content-Type: application/json
Authorization: Basic YWRtaW46VGhpc0lzTm90VGhlUmVhbFBhc3N3b3JkIQ==

{
  "FullName": "mygroup/spredsheet1",
  "SheetNames": [
    "Catchments"
  ],
  "Data": [
    [
      [
        "Catchment Name",
        "Area"
      ],
      [
        "MyCatchementName",
        56250.88
      ]
    ]
  ]
}

GET api/spreadsheet/{connectionId}/fullnames

Returns a list of spreadsheet full-name identifiers.

GET api/spreadsheet/{connectionId}/fullnames?group={group}

Returns a list of spreadsheet full-name identifiers within the given group (recursive).

Example:

GET api/spreadsheet/mc-sps/fullnames?group=mygroup/mysubgroup

GET api/spreadsheet/{connectionId}/{fullName}

Returns a spreadsheet with the given full-name.

GET api/spreadsheet/{connectionId}/list

Returns a list of all spreadsheets.

GET api/spreadsheet/{connectionId}/list?group={group}

Returns a list of spreadsheets within the given group (recursive).

Example:

GET api/spreadsheet/mc-sps/list?group=mygroup/mysubgroup

GET api/spreadsheet/{connectionId}/count

Returns the total number of spreadsheets.

GET api/spreadsheet/{connectionId}/{fullName}/{sheetName}/cell;{cell}

Returns the cell value for the given cell in the given sheet in the given spreadsheet. A cell is given in the format R{row}C{col}. The row and column indices are zero-based.

Example:

GET api/spreadsheet/mc-sps/mygroup|spreadsheet1/Sheet1/cell;R7C12

GET api/spreadsheet/{connectionId}/{fullName}/{sheetName}/range;{range}

Returns the cell values in the given range in the given sheet in the given spreadsheet. A range is given in the format {cell1},{cell2}. The row and column indices are zero-based.

Example:

GET api/spreadsheet/mc-sps/mygroup|spredsheet1/Sheet1/range;R0C0,R7C12

GET api/spreadsheet/{connectionId}/{fullName}/{sheetName}/namedrange;{rangeName}

Returns the cell values in the given named range in the given sheet in the given spreadsheet.

Example:

GET api/spreadsheet/mc-sps/mygroup|spredsheet1/Sheet1/namedrange;name1

GET api/spreadsheet/{connectionId}/{fullName}/{sheetName}/usedrange

Returns the cell values in the used range in the given sheet in the given spreadsheet.

DELETE api/spreadsheet/{connectionId}/{spreadsheetId} locked

Removes a spreadsheet with the given id.

Example:

DELETE api/spreadsheet/mclite/mygroup|spredsheet1
Authorization: Basic YWRtaW46VGhpc0lzTm90VGhlUmVhbFBhc3N3b3JkIQ==

Spreadsheet representation

{
  "FullName": "/MyGroup/MySubGroup/SpreadSheet1",
  "Group": "/MyGroup/MySubGroup",
  "Id": "1e86908e-ec2f-44c0-ae7f-6d9f6ed272e2",
  "Name": "SpreadSheet1"
}

Tables

Table ID

The unique identifier of a table is a string (the name of the table).

URIs

GET api/table/{connectionId}/ids

Returns a list of table identifiers (table names).

GET api/table/{connectionId}/list

Returns a list of all tables.

GET api/table/{connectionId}/count

Returns the total number of tables.

GET api/table/{connectionId}/{tableId}

Returns a table with the given table ID (name).

Example:

GET api/table/accessdb/Stations

GET api/table/{connectionId}/{tableId}/data

Returns all the data from a table with the given table ID (name).

Example:

GET api/table/accessdb/Stations/data

GET api/table/{connectionId}/{tableId}/data?{col}={value}&...

Returns a subset of data filtered by the given query string from a table with the given table ID (name).

Example:

GET api/table/accessdb/WaterLevels/data?TimeOfMeasurement=2016-05-13T00:00:00

Table representation

{
  "Columns": [
    {
      "Name": "TimeOfMeasurement",
      "DataType": "System.DateTime, mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089",
      "IsKey": false
    },
    {
      "Name": "WaterLevel",
      "DataType": "System.Double, mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089",
      "IsKey": false
    }
  ],
  "Id": "WaterLevels"
}

Time Series

Time series ID

There are two types of time series connections: flat (non-hierarchical) or grouped (hierarchical). The syntax of the unique identifier of a time series depends on the connection type.

Flat time series ID

For a flat time series connection, the unique identifier of a time series is the ID of the time series. This ID will typically be equal to the name of the time series:

Example: MyTimeSeries

Grouped time series ID

For a grouped time series connection, the unique identifier of a time series is the "full-name" of the time series. The full-name is a combination of a group that the time series belongs to and the name of the time series - separated by a forward slash "/".

The group itself can be a hierarchy of groups separated by forward slashes. If a time series does not belong to a group, the unique identifier is the name alone.

Example: MyGroup/MySubgroup/MyTimeSeries

NOTE: in the URIs, the forward slashes ("/") in a full-name identifier must be replaced by a pipe character ("|"). If the full-name identifier itself includes pipe characters ("|"), these must be escaped with another pipe-character – i.e. "|" must be replaced with "||".

Example:

GET api/timeseries/mc-ts/mygroup|mysubgroup|ts1/value/lastbefore/2006-02-15T220000

Depending on the underlying time series provider type (the connection type) the syntax of the time series name might vary. If for example the time series are read from a MIKE by DHI res1d file repository, the time series name will have the following syntax:

<filename>;<itemType>;<elementType>;[<chainage>];<elementId>

Example:

GET api/timeseries/mike-ts/dir1|dir1.1|Exam6Base.res1d;eumIWaterLevel;node;5/values

URIs

POST api/timeseries/{connectionId} locked updatable

Adds a new time series. The only required information in the request body is the FullName. However, some connection types might require additional information such as DataType, Quantity and Unit. If the connection type is not a grouped (hierarchical) connection type, the FullName should be a simple flat time series ID.

NOTE: Only applicable if the connection type is updatable.

Example:

POST api/timeseries/mc-ws1-ts
Content-Type: application/json
Authorization: Basic YWRtaW46VGhpc0lzTm90VGhlUmVhbFBhc3N3b3JkIQ==

{
  "FullName": "CC/My New Time Series",
  "DataType": "Instantaneous",
  "Unit": "m",
  "Quantity": "Water Level",
  "Data": {
    "DateTimes": [
      "2007-02-18T22:15:00",
      "2007-02-18T22:20:00",
      "2007-02-18T22:25:00"
    ],
    "Values": [
      0.22908926,
      0.229103819,
      0.229090463
    ]
  }
}

PUT api/timeseries/{connectionId} locked updatable

Updates an existing time series. The only required information in the request body is the FullName. If the connection type is not a grouped (hierarchical) connection type, the FullName should be a simple flat time series ID. The updated data and/or meta data will depend on the other information given in the request body.

NOTE: Only applicable if the connection type is updatable.

Example:

PUT api/timeseries/mc-ws1-ts
Content-Type: application/json
Authorization: Basic YWRtaW46VGhpc0lzTm90VGhlUmVhbFBhc3N3b3JkIQ==
{
  "FullName": "CC/My New Time Series",
  "DataType": "Mean Step Accumulated",
  "Unit": "m",
  "Quantity": "Water Level",
  "Data": {
    "DateTimes": [
      "2007-02-18T22:15:00",
      "2007-02-18T22:20:00",
      "2007-02-18T22:25:00",
      "2007-02-18T22:30:00"
    ],
    "Values": [
      0.22908926,
      0.229103819,
      0.229070463,
      0.229113819,
    ]
  }
}

DELETE api/timeseries/{connectionId}/{timeseriesId} locked updatable

Removes a time series with the given id.

NOTE: Only applicable if the connection type is updatable.

Example:

DELETE api/timeseries/mc-ws1-ts/CC|My%20New%20Time%20Series
Authorization: Basic YWRtaW46VGhpc0lzTm90VGhlUmVhbFBhc3N3b3JkIQ==

PUT api/timeseries/{connectionId}/{timeseriesId}/values locked

Sets some time series values for the time series with the given ID.

Example:

PUT api/timeseries/waterforecast-ts/Amager-Strandpark/values
Content-Type: application/json
Authorization: Basic YWRtaW46VGhpc0lzTm90VGhlUmVhbFBhc3N3b3JkIQ==
{
    "DateTimes": [
      "2007-02-18T22:15:00",
      "2007-02-18T22:20:00",
      "2007-02-18T22:25:00"
    ],
    "Values": [
      0.22908926,
      0.229103819,
      0.229090463
    ]
}

Retrieving metadata

GET api/timeseries/{connectionId}/ids

Returns a list of time series identifiers.

GET api/timeseries/{connectionId}/fullnames grouped

Returns a list of time series full-name identifiers.

NOTE: Only applicable if the connection type is grouped (hierarchical).

GET api/timeseries/{connectionId}/fullnames?group={group} grouped

Returns a list of time series full-name identifiers within the given group (recursive).

NOTE: Only applicable if the connection type is grouped (hierarchical).

Example:

GET api/timeseries/mc-ts/fullnames?group=mygroup/mysubgroup

GET api/timeseries/{connectionId}/{timeseriesId}

Returns a time series with the given time series ID (ID or full-name).

GET api/timeseries/{connectionId}/list

Returns a list of all time series.

GET api/timeseries/{connectionId}/list?group={group} grouped

Returns a list of time series within the given group (recursive).

NOTE: Only applicable if the connection type is grouped (hierarchical).

Example:

GET api/timeseries/mc-ts/list?group=mygroup/mysubgroup

POST api/timeseries/{connectionId}/list grouped

Returns a list of time series within the given list of groups (recursive).

NOTE: Only applicable if the connection type is grouped (hierarchical).

Example:

POST api/timeseries/mc-ts/list
Content-Type: application/json
[
  "/Group1/SubGroup/530168-23_530168-23_Rainfall Depth",
  "/CC/P_D_9037097_GathiuruForest"
]

GET api/timeseries/{connectionId}/count

Returns the total number of time series.

GET api/timeseries/{connectionId}/{timeseriesId}/datetimes

Returns a list of all datetimes for the given time series.

GET api/timeseries/{connectionId}/{timeseriesId}/datetime/first

Returns the first datetime for the given time series. If the time series does not contain any data, null is returned.

GET api/timeseries/{connectionId}/{timeseriesId}/datetime/last

Returns the last datetime for the given time series. If the time series does not contain any data, null is returned.

Retrieving values from a specific time series

GET api/timeseries/{connectionId}/{timeseriesId}/value/last

Returns the last value (corresponding to the last time step) for the given time series. If the time series does not contain any data, null is returned.

GET api/timeseries/{connectionId}/{timeseriesId}/value/firstafter/{dateTime}

Returns the first value after the given datetime for the given time series. A DateTime value is given as a modified ISO 8601 format (with the ":" separators in the time specification omitted). If the time series does not contain any data, null is returned.

Example:

GET api/timeseries/mc-ts/mygroup|ts1/value/firstafter/2006-02-15T220000

GET api/timeseries/{connectionId}/{timeseriesId}/value/lastbefore/{dateTime}

Returns the last value before the given datetime for the given time series. If the time series does not contain any data, null is returned.

Example:

GET api/timeseries/mc-ts/mygroup|ts1/value/lastbefore/2006-02-15T220000

GET api/timeseries/{connectionId}/{timeseriesId}/value/{dateTime}

Returns the value at the given datetime for the given time series.

GET api/timeseries/{connectionId}/{timeseriesId}/values

Returns a list of all values for the given time series.

GET api/timeseries/{connectionId}/{timeseriesId}/values?from={fromDateTime}

Returns a list of values from the given time for the given time series.

Example:

GET api/timeseries/mc-ts/mygroup|ts1/values?from=2006-02-15T220000

GET api/timeseries/{connectionId}/{timeseriesId}/values?to={toDateTime}

Returns a list of values until the given time for the given time series.

Example:

GET api/timeseries/mc-ts/mygroup|ts1/values?to=2006-02-16T220000

GET api/timeseries/{connectionId}/{timeseriesId}/values?from={fromDateTime}&to={toDateTime}

Returns a list of values within the given time interval for the given time series.

Example:

GET api/timeseries/mc-ts/mygroup|ts1/values?from=2006-02-15T220000&to=2006-02-16T220000

Retrieving values from multiple time series

POST api/timeseries/{connectionId}/list/value/last

Returns the last value (corresponding to the last time step) for the given list of time series.

Example:

POST api/timeseries/mc-ts/list/value/last
Content-Type: application/json
[
  "/Group1/SubGroup/530168-23_530168-23_Rainfall Depth",
  "/CC/P_D_9037097_GathiuruForest"
]

POST api/timeseries/{connectionId}/list/values

Returns a list of all values for the given list of time series.

Example:

POST api/timeseries/mc-ts/list/values
Content-Type: application/json
[
  "/Group1/SubGroup/530168-23_530168-23_Rainfall Depth",
  "/CC/P_D_9037097_GathiuruForest"
]

POST api/timeseries/{connectionId}/list/values?from={fromDateTime}

Returns a list of values from the given time for the given list of time series.

Example:

POST api/timeseries/mc-ts/list/values?from=2006-02-15T220000
Content-Type: application/json
[
  "/Group1/SubGroup/530168-23_530168-23_Rainfall Depth",
  "/CC/P_D_9037097_GathiuruForest"
]

POST api/timeseries/{connectionId}/list/values?to={toDateTime}

Returns a list of values until the given time for the given list of time series.

Example:

POST api/timeseries/mc-ts/list/values?to=2006-02-16T220000
Content-Type: application/json
[
  "/Group1/SubGroup/530168-23_530168-23_Rainfall Depth",
  "/CC/P_D_9037097_GathiuruForest"
]

POST api/timeseries/{connectionId}/list/values?from={fromDateTime}&to={toDateTime}

Returns a list of values within the given time interval for the given list of time series.

Example:

POST api/timeseries/mc-ts/list/values?from=2006-02-15T220000&to=2006-02-16T220000
Content-Type: application/json
[
  "/Group1/SubGroup/530168-23_530168-23_Rainfall Depth",
  "/CC/P_D_9037097_GathiuruForest"
]

Time series analysis

GET api/timeseries/{connectionId}/{timeseriesId}/min?from={fromDateTime}&to={toDateTime}

Returns the minimum value for the given time series within the given time interval. The from and to query parameters can be omitted. If no time interval is given, the analysis is performed on the entire range of time series values.

Example:

GET api/timeseries/mc-ts/mygroup|ts1/min?from=2006-02-15T220000

POST api/timeseries/{connectionId}/list/min?from={fromDateTime}&to={toDateTime}

Returns a list of minimum values for the given list of time series within the given time interval. The from and to query parameters can be omitted. If no time interval is given, the analysis is performed on the entire range of time series values.

Example:

POST api/timeseries/mc-ts/list/min?from=2006-02-15T220000
Content-Type: application/json
[
  "/Group1/SubGroup/530168-23_530168-23_Rainfall Depth",
  "/CC/P_D_9037097_GathiuruForest"
]

GET api/timeseries/{connectionId}/{timeseriesId}/max?from={fromDateTime}&to={toDateTime}

Returns the maximum value for the given time series within the given time interval. The from and to query parameters can be omitted. If no time interval is given, the analysis is performed on the entire range of time series values.

Example:

GET api/timeseries/mc-ts/mygroup|ts1/max?from=2006-02-15T220000

POST api/timeseries/{connectionId}/list/max?from={fromDateTime}&to={toDateTime}

Returns a list of maximum values for the given list of time series within the given time interval. The from and to query parameters can be omitted. If no time interval is given, the analysis is performed on the entire range of time series values.

Example:

POST api/timeseries/mc-ts/list/max?from=2006-02-15T220000
Content-Type: application/json
[
  "/Group1/SubGroup/530168-23_530168-23_Rainfall Depth",
  "/CC/P_D_9037097_GathiuruForest"
]

GET api/timeseries/{connectionId}/{timeseriesId}/sum?from={fromDateTime}&to={toDateTime}

Returns the sum value for the given time series within the given time interval. The from and to query parameters can be omitted. If no time interval is given, the analysis is performed on the entire range of time series values.

Example:

GET api/timeseries/mc-ts/mygroup|ts1/sum?from=2006-02-15T220000

POST api/timeseries/{connectionId}/list/sum?from={fromDateTime}&to={toDateTime}

Returns a list of sum values for the given list of time series within the given time interval. The from and to query parameters can be omitted. If no time interval is given, the analysis is performed on the entire range of time series values.

Example:

POST api/timeseries/mc-ts/list/sum?from=2006-02-15T220000
Content-Type: application/json
[
  "/Group1/SubGroup/530168-23_530168-23_Rainfall Depth",
  "/CC/P_D_9037097_GathiuruForest"
]

GET api/timeseries/{connectionId}/{timeseriesId}/average?from={fromDateTime}&to={toDateTime}

Returns the average value for the given time series within the given time interval. The from and to query parameters can be omitted. If no time interval is given, the analysis is performed on the entire range of time series values.

Example:

GET api/timeseries/mc-ts/mygroup|ts1/average?from=2006-02-15T220000

POST api/timeseries/{connectionId}/list/average?from={fromDateTime}&to={toDateTime}

Returns a list of average values for the given list of time series within the given time interval. The from and to query parameters can be omitted. If no time interval is given, the analysis is performed on the entire range of time series values.

Example:

POST api/timeseries/mc-ts/list/average?from=2006-02-15T220000
Content-Type: application/json
[
  "/Group1/SubGroup/530168-23_530168-23_Rainfall Depth",
  "/CC/P_D_9037097_GathiuruForest"
]

GET api/timeseries/{connectionId}/{timeseriesId}/percentile/{percentage}?from={fromDateTime}&to={toDateTime}

Returns the value (percentile) below below which a given percentage of values within the given time interval fall. The from and to query parameters are optional. If no time interval is given, the analysis is performed on the entire range of time series values.

Example:

GET api/timeseries/mc-ts/mygroup|ts1/percentile/90?from=2006-02-15T220000

POST api/timeseries/{connectionId}/list/percentile/{percentage}?from={fromDateTime}&to={toDateTime}

Returns a list of percentile values for the given list of time series within the given time interval. The from and to query parameters can be omitted. If no time interval is given, the analysis is performed on the entire range of time series values.

Example:

POST api/timeseries/mc-ts/list/percentile/90?from=2006-02-15T220000
Content-Type: application/json
[
  "/Group1/SubGroup/530168-23_530168-23_Rainfall Depth",
  "/CC/P_D_9037097_GathiuruForest"
]

GET api/timeseries/{connectionId}/{timeseriesId}/reduced?tolerance={tolerance}&minimumcount={minimumCount}&from={fromDateTime}&to={toDateTime}

Returns a reduced (simplified) time series using the Ramer–Douglas–Peucker algorithm of the given time series within the given time interval. The tolerance query parameter is optional. The tolerance is a relative tolerance expressed as a percentage of the difference between maximum and minimum value within the analysed time interval. If no tolerance is given, the default value is 2%.

The minimumcount query parameter is optional. The minimumcount defines at threshold value for ignoring the request to reduce the times series. If, for example, the minimum count is set to 1000, and the number of data points within the given time interval is less than 1000, the reduction request will be ignored, and the complete time series will be returned. If no minimum count is given, the default value is 3000 data points.

The from and to query parameters are optional. If no time interval is given, the analysis is performed on the entire range of time series values.

Example:

GET api/timeseries/mc-ts/mygroup|ts1/reduced?tolerance=5&from=2006-02-15T220000

POST api/timeseries/{connectionId}/list/reduced?tolerance={tolerance}&minimumcount={minimumCount}&from={fromDateTime}&to={toDateTime}

Returns a list of reduced (simplified) time series using the Ramer–Douglas–Peucker algorithm of the given list of time series within the given time interval. The tolerance query parameter is optional. The tolerance is a relative tolerance expressed as a percentage of the difference between maximum and minimum value within the analysed time interval. If no tolerance is given, the default value is 2%.

The minimumcount query parameter is optional. The minimumcount defines at threshold value for ignoring the request to reduce the times series. If, for example, the minimum count is set to 1000, and the number of data points within the given time interval is less than 1000, the reduction request will be ignored, and the complete time series will be returned. If no minimum count is given, the default value is 3000 data points.

The from and to query parameters are optional. If no time interval is given, the analysis is performed on the entire range of time series values.

Example:

POST api/timeseries/mc-ts/list/reduced?tolerance=5&from=2006-02-15T220000
Content-Type: application/json
[
  "/Group1/SubGroup/530168-23_530168-23_Rainfall Depth",
  "/CC/P_D_9037097_GathiuruForest"
]

GET api/timeseries/{connectionId}/{timeseriesId}/movingaverage?window={window}from={fromDateTime}&to={toDateTime}

Returns the moving average over the given window for the given time series within the given time interval. The window query parameter is mandatory and is an integer defining the number of data points in the window. The from and to query parameters can be omitted. If no time interval is given, the analysis is performed on the entire range of time series values.

Example:

GET api/timeseries/mc-ts/mygroup|ts1/movingaverage?window=10&from=2006-02-15T220000

GET api/timeseries/{connectionId}/{timeseriesId}/resampled?timespan={timespan}&from={fromDateTime}&to={toDateTime}

Returns a resampled time series within the given time interval with time steps equivalent to the given time span. The time series values are found using interpolation according to the time series data type. The timespan query parameter is mandatory. The from and to query parameters are optional. If no time interval is given, the analysis is performed on the entire range of time series values.

Example:

GET api/timeseries/mc-ts/mygroup|ts1/resampled?timespan=1.00:00:00&from=2006-02-15T220000

Time series representation

{
  "FullName": "/Group1/SubGroup/530168-23_530168-23_Rainfall Depth",
  "Group": "/Group1/SubGroup",
  "Id": "7299875c-ee1f-4f20-bb30-066cc267f1bd",
  "Metadata": {
    "FirstDateTime": "2007-02-15T00:00:00",
    "LastDateTime": "2007-02-19T00:00:00",
    "ValueType": "Instantaneous",
    "IsEquidistant": false,
    "Type": "Rainfall Depth",
    "Unit": "mm"
  },
  "Name": "530168-23_530168-23_Rainfall Depth"
}

The metadata information might or might not be present – depending on the underlying type of time series provider. Furthermore, the format of the metadata information will vary depending on the type of time series provider.

Time series values representation

The time series values representation is a JSON array of data points. A data point is itself an array with a datetime and a value. Furthermore, depending on the underlying type of time series provider, a data point might comprise additional annotations such as a quality flag or a time of forecast.

[
  [
    "2007-02-18T22:15:00",
    0.22908926
  ],
  [
    "2007-02-18T22:20:00",
    0.229103819,
    1
  ],
  [
    "2007-02-18T22:25:00",
    0.229120463
  ],

  ...
]

Multiple time series values representation

The representation of multiple time series values is a JSON object with one name/value pair per time series. The name is the full-name of the time series, and the value is the array of data points as described above.

{
  "ts1": [
    [
      "2007-02-18T22:15:00",
      0.22908926
    ],
    [
      "2007-02-18T22:20:00",
      0.229103819,
      1
    ],
    ...
  ],
  "ts2": [
    [
      "2007-02-18T22:15:00",
      1.22908926
    ],
    [
      "2007-02-18T22:20:00",
      1.229103819
    ],
    ...
  ]
}

Time Step Data

Retrieving data (of arbitrary type) at a certain time step in a time series for a specific item. All items in a connection have equivalent time axis (the same time steps).

URIs

GET api/timestep/{connectionId}/items

Returns a list of items.

GET api/timestep/{connectionId}/datetimes

Returns a list of all datetimes.

GET api/timestep/{connectionId}/datetime/first

Returns the first datetime. If the time series does not contain any data, null is returned.

GET api/timestep/{connectionId}/datetime/last

Returns the last datetime. If the time series does not contain any data, null is returned.

Retrieving data from a time series for a specific item

GET api/timestep/{connectionId}/{item}/data/last

Returns the last data object (corresponding to the last time step) for the given item. If the item time series does not contain any data, null is returned.

Example:

GET api/timestep/mo-ts/MyItem/data/last

GET api/timestep/{connectionId}/{item}/data/firstafter/{dateTime}

Returns the first data object after the given datetime for the given item time series. A DateTime value is given as a modified ISO 8601 format (with the ":" separators in the time specification omitted). If the time series does not contain any data, null is returned.

Example:

GET api/timestep/mo-ts/MyItem/data/firstafter/2006-02-15T220000

GET api/timestep/{connectionId}/{item}/data/lastbefore/{dateTime}

Returns the last data object before the given datetime for the given item time series. If the time series does not contain any data, null is returned.

Example:

GET api/timestep/mo-ts/MyItem/data/lastbefore/2006-02-15T220000

GET api/timestep/{connectionId}/{item}/data/{dateTime}

Returns the data object at the given datetime for the given item time series.

Example:

GET api/timestep/mo-ts/MyItem/data/2006-02-15T220000

Time step data representation

As the data in a time step can be of any type, there is no particular time step data representation. Depending on the time step data provider, the response can contain a JSON representation of an object or a binary stream.

Feature Collections

A feature collection is defined according to the GeoJSON specification.

Feature Collection ID

There are two types of feature collection connections: flat (non-hierarchical) or grouped (hierarchical). The syntax of the unique identifier of a feature collection depends on the connection type.

Flat feature collection ID

For a flat feature collection connection, the unique identifier of a feature collection is the ID of the feature collection. This ID will typically be equal to the name of the feature collection:

Example: Countries

Grouped feature collection ID

For a grouped feature collection the unique identifier of a feature collection is the "full-name" of the feature collection. The full-name is a combination of a group that the feature collection belongs to and the name of the feature collection - separated by a forward slash "/". The group itself can be a hierarchy of groups separated by forward slashes. If a feature class does not belong to a group, the unique identifier is the name alone.

Example: MyGroup/MySubgroup/Countries.

NOTE: in the URIs, the forward slashes ("/") in a full-name identifier must be replaced by a pipe character ("|"). If the full-name identifier itself includes pipe characters ("|"), these must be escaped with another pipe-character – i.e. "|" must be replaced with "||".

Example:

GET api/featurecollection/mc-gis/mygroup|mysubgroup|Countries?name=Denmark

URIs

GET api/featurecollection/{connectionId}/ids

Returns a list of feature collection identifiers.

GET api/featurecollection/{connectionId}/fullnames grouped

Returns a list of feature collection full-name identifiers.

NOTE: Only applicable if the connection type is grouped (hierarchical).

GET api/featurecollection/{connectionId}/fullnames?group={group} grouped

Returns a list of feature collection full-name identifiers within the given group (recursive).

NOTE: Only applicable if the connection type is grouped (hierarchical).

Example:

GET api/spreadsheet/mc-gis/fullnames?group=mygroup/mysubgroup

GET api/featurecollection/{connectionId}/{featureCollectionId}

Returns a feature collection with the given feature collection ID (ID or full-name).

GET api/featurecollection/{connectionId}/{featureCollectionId}?associations=true

Returns a feature collection with the given ID. If the provider supports associations of time series, spreadsheets etc., these associations will be included in the response.

Example:

GET api/featurecollection/mc-gis/Cities?associations=true

GET api/geometrycollection/{connectionId}/{featureCollectionId}

Returns a geometry collection from the feature collection with the given ID.

NOTE: only the feature geometry is returned – no properties (attributes) are included.

GET api/featurecollection/{connectionId}/{featureCollectionId}?{attributeName}={value}&...

Returns a feature collection with the given ID and features filtered by the given query string

Example:

GET api/featurecollection/mc-gis/Cities?Continent=Asia&IsCapitol=true

GET api/featurecollection/{connectionId}/{featureCollectionId}?&associations=true&{attributeName}={value}&...

Returns a feature collection with the given ID and features filtered by the given query string. If the provider supports associations of time series, spreadsheets etc., these associations will be included in the response.

Example:

GET api/featurecollection/mc-gis/Cities?associations=true&Continent=Asia

GET api/geometrycollection/{connectionId}/{featureCollectionId}?{attributeName}={value}&...

Returns a geometry collection from the feature collection with the given ID and features filtered by the given query string.

*NOTE: only the feature geometry is returned – no properties (attributes) are included.

Example:

GET api/geometrycollection/mc-gis/Cities?Continent=Asia&IsCapitol=true

GET api/featurecollection/{connectionId}/list

Returns a list of all feature collections

GET api/featurecollection/{connectionId}/list?group={group} grouped

Returns a list of feature collection within the given group (recursive).

NOTE: Only applicable if the connection type is grouped (hierarchical).

Example:

GET api/featurecollection/mc-gis/list?group=mygroup/mysubgroup

POST api/featurecollection/{connectionId}/list

Returns a list of all feature collections for the given list of feature collection ID"s.

Example:

POST api/featurecollection/mc-gis/list
Content-Type: application/json
[
  "/Group1/Cities",
  "/Group1/Countries"
]

GET api/featurecollection/{connectionId}/count

Returns the total number of feature collections

Feature collection representation

The feature collection representation is compliant with the GeoJSON specification.

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "MultiPolygon",
        "coordinates": [
          [
            [
              [
                -113.210526315789,
                49.9736842105263
              ],
              [
                -80.5263157894737,
                77.4473684210526
              ],
              ...
            ]
          ]
        ]
      },
      "properties": {
        "name": "Denmark",
        "size": 5000000,
      }
    },
    {
      "type": "Feature",
      "geometry": {
        "type": "MultiPolygon",
        "coordinates": [
          [
            [
              [
                31.2631578947368,
                103.5
              ],
              [
                73.8947368421053,
                71.7631578947368
              ],
              ...
            ]
          ]
        ]
      },
      "properties": {
        "name": "Sweden",
        "size": 15000000,
      }
    }
  ]
}

Depending on the capabilities of the underlying provider, the feature properties may include associations to other resources such as time series or spreadsheets:

{
   ...
      "properties": {
        "name": "Sweden",
        "size": 15000000,
        "associations": [
          {
            "Id": "/Group1/ts3",
            "Type": "timestep"
          },
          {
            "Id": "/Group1/3080_SAVA_DOLINKA_BLEJSKI_MOST_Temperature.dfs0 [weighted]",
            "Type": "timestep"
          },
          {
            "Id": "/MyWorkbook",
            "Type": "spreadsheet"
          }
        ]
      }
   ...
}

Geometry collection representation

The geometry collection representation is compliant with the GeoJSON specification.

{
  "type": "GeometryCollection",
  "geometries": [
    {
      "type": "MultiPolygon",
      "coordinates": [
        [
          [
            [
              -113.210526315789,
              49.9736842105263
            ],
            [
              -80.5263157894737,
              77.4473684210526
            ],
            ...
          ]
        ]
      ]
    },
    {
      "type": "MultiPolygon",
      "coordinates": [
        [
          [
            [
              31.2631578947368,
              103.5
            ],
            [
              73.8947368421053,
              71.7631578947368
            ],
            ...
          ]
        ]
      ]
    }
  ]
}

Maps

A map is a bitmap image (png) representing 2D data. Maps are requested using the Open Geospatial Consortium WMS standard protocol for serving georeferenced map images.

URIs

GET api/map?request=GetMap&service=wms&version=…

Returns a bitmap image (png) using the WMS standard protocol.

Example:

GET api/map?request=GetMap&service=wms&version=1.3.0&layers=dfs2-map&item=1&styles=MyStyle&width=500&height=500&crs=EPSG:3857&bbox=11584184.510675031,78271.51696402066,11623320.26915704,117407.27544603013

map

GET api/map?request=GetLegendGraphic&styles={styleId}&width={width}&height={height}&isvertical={true|false}

Returns a bitmap image (png) of a legend representing the map style with the given ID. The isvertical parameter defaults to true.

Example:

GET api/map?request=GetLegendGraphic&styles=MyStyle&width=100&height=500&isvertical=false

mapstyle

Map Styles

A map style defines the rendering when retrieving a Map.

URIs

POST api/mapstyle locked

Adds a new map style

Example:

POST api/mapstyle
Content-Type: application/json
Authorization: Basic YWRtaW46VGhpc0lzTm90VGhlUmVhbFBhc3N3b3JkIQ==
{
  "StyleCode": "0^10:#800080,#5500AB,#2A00D5,#0000FF,#0038E1,#006FC3,#00A6A6,#00C46E...,
  "Name": "My Style",
  "Id": "MyStyle"
}

GET api/mapstyle/{id}

Returns a style with the given id

Example:

GET api/mapstyle/MyStyle

GET api/mapstyle/list

Returns a list of all map styles

GET api/mapstyle/count

Returns the total number of map styles

DELETE api/mapstyle/{id} locked

Removes a map style with the given id

Example:

DELETE api/mapstyle/MyStyle
Authorization: Basic YWRtaW46VGhpc0lzTm90VGhlUmVhbFBhc3N3b3JkIQ==

Map style representation

StyleCode is a string that defines color bands and associated values.

{
  "StyleCode": "0^10:#800080,#5500AB,#2A00D5,#0000FF,#0038E1,#006FC3,#00A6A6,#00C46E,...,
  "Name": "My Style",
  "Id": "MyStyle"
}

Examples:

0:#800080|5:#5500AB|10:#2A00D5|15:#0000FF

4 color bands corresponding to 4 hex colors code. Associated values start from 0 and increase 5 for every color bands. Final color palette is #800080 for 0 to 5, #5500AB for 5 to 10, #2A00D5for 10 to 15 and #0000FF for above 15.

0^5:#800080,#5500AB,#2A00D5,#0000FF

Short syntax indicating 4 color bands with value starting from 0 with increment 5 units.

0~15:#800080,#5500AB,#2A00D5,#0000FF

Short syntax indicating 4 color bands with value starting from 0 to 15. In-between values are automatically calculated based on the number of color bands.

0^5:#800080,#5500AB,#2A00D5,#0000FF|20:#0022FF|25:#00AAFF

Combined syntax indicating 4 color bands from 0 to 25.

Job Hosts

A job host is a resource (machine) for job execution. A job host can represent a cloud instance.

Job Host ID

The unique identifier of a host is a string (e.g. "MyRemoteHost").

URIs

POST api/jobhost locked

Adds a new job host.

Example:

POST api/jobhost
Content-Type: application/json
Authorization: Basic YWRtaW46VGhpc0lzTm90VGhlUmVhbFBhc3N3b3JkIQ==
{
  "Name": "My Cloud Host",
  "Id": "MyCloudHost",
  "Priority": 1,
  "RunningJobsLimit": 10,
  "CloudInstanceParameters": {
    "CloudInstanceHandlerType": "DHI.Services.Provider.NCI.CloudInstanceHandler",
    "StartupParameters": {
      "parameter1": "BlaBla",
      "parameter2": true,
      "parameter3": 23.45
    }
  }
}

PUT api/jobhost locked

Updates an existing job host.

Example:

PUT api/jobhost
Content-Type: application/json
Authorization: Basic YWRtaW46VGhpc0lzTm90VGhlUmVhbFBhc3N3b3JkIQ==
{
  "Name": "My Cloud Host",
  "Id": "MyCloudHost",
  "Priority": 999,
  "RunningJobsLimit": 10,
  "CloudInstanceParameters": {
    "CloudInstanceHandlerType": "DHI.Services.Provider.NCI.CloudInstanceHandler",
    "StartupParameters": {
      "parameter1": "BlaBla",
      "parameter2": true,
      "parameter3": 23.45
    }
  }
}

GET api/jobhost/{id}

Returns a job host with the given id.

Example:

GET api/jobhost/MyCloudHost

GET api/jobhost/list

Returns a list of all job hosts.

GET api/jobhost/ids

Returns a list of all job host identifiers.

GET api/jobhost/count

Returns the total number of job hosts.

DELETE api/jobhost/{id} locked

Removes a job host with the given id.

Example:

DELETE api/jobhost/MyJobHost
Authorization: Basic YWRtaW46VGhpc0lzTm90VGhlUmVhbFBhc3N3b3JkIQ==

Job host representation

{
  "Name": "My Cloud Host",
  "Id": "MyCloudHost",
  "Priority": 1,
  "RunningJobsLimit": 10,
  "CloudInstanceParameters": {
    "CloudInstanceHandlerType": "DHI.Services.Provider.NCI.CloudInstanceHandler",
    "StartupParameters": {
      "parameter1": "BlaBla",
      "parameter2": true,
      "parameter3": 23.45
    }
  }
}

Tasks

A task is a unit of work that can be executed as a job. Some tasks take input parameters.

Task ID

The unique identifier of a task is the "full-name" of the task. The full-name is a combination of a group that the task belongs to and the name of the task - separated by a forward slash "/". The group itself can be a hierarchy of groups separated by forward slashes. If a task does not belong to a group, the unique identifier is the name alone.

Example:

MyGroup/MySubgroup/SomeTask.

NOTE: in the URIs, the forward slashes ("/") in a full-name identifier must be replaced by a pipe character ("|"). If the full-name identifier itself includes pipe characters ("|"), these must be escaped with another pipe-character – i.e. "|" must be replaced with "||".

Example:

GET api/task/mc-task/mygroup|mysubgroup|sometask

URIs

GET api/task/{connectionId}/ids

Returns a list of task identifiers.

GET api/task/{connectionId}/{fullName}

Returns a task with the given id.

Example:

GET api/task/mc-task/tasks|task1

GET api/task/{connectionId}/list

Returns a list of all tasks.

GET api/task/{connectionId}/count

Returns the total number of tasks.

Task representation

{
  "FullName": "/Group1/SubGroup/MyTask",
  "Group": "/Group1/SubGroup",
  "Id": "7299875c-ee1f-4f20-bb30-066cc267f1bd",
  "Name": "MyTask",
  "Parameters": {
    "Param1": "string",
    "Param2": "boolean"
  }
}

Jobs

A job is a task "instance" – i.e. an execution of a task or a task that has been executed.

Job ID

The unique identifier of a job is a GUID (e.g. 7299875c-ee1f-4f20-bb30-066cc267f1bd)

URIs

POST api/job/{connectionId} locked

Requests a job execution. If the specified task requires input parameters, these must be specified. The response includes a Location header with a URL to the created job resource. This link can be used to retrieve the status of the job. A job can be marked with a given tag by including a Tag property in the request. However, this is optional.

Example:

POST api/job/mc-job
Content-Type: application/json
Authorization: Basic YWRtaW46VGhpc0lzTm90VGhlUmVhbFBhc3N3b3JkIQ==
{
  "TaskId": "mygroup/task1",
  "Tag": "MyScenario",
  "Parameters": {
    "Param1": "SomeValue",
    "Param2": false
  }
}

Response:

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8
Location: http://localhost:17510/api/job/mc-job/7299875c-ee1f-4f20-bb30-066cc267f1bd
{
  "Id": "7299875c-ee1f-4f20-bb30-066cc267f1bd",
  "TaskId": "mygroup/task1",
  "Tag": "MyScenario",
  "Requested": "2014-07-03 16:35:45",
  "Status": "Pending",
  "AccountId": "john.doe",
  "Parameters": {
    "Param1": "SomeValue",
    "Param2": false
  }
}

The exact syntax of the Parameters section will vary depending on the underlying job execution provider.

NOTE: The job execution request is added to a job queue. The actual job execution is performed by a Job Runner service, which need to be properly configured and running.

GET api/job/{connectionId}/{id}

Returns the status of a job with the given id.

Example:

GET api/job/mc-job/7299875c-ee1f-4f20-bb30-066cc267f1bd

Retrieving the last job

GET api/job/{connectionId}/last?account={accountId}

Returns the last job executed under the given account.

Example:

GET api/job/mc-job/last?account=john.doe

GET api/job/{connectionId}/last?status={status}

Returns the last job with the given status. Status is either Pending, InProgress, Error or Completed.

Example:

GET api/job/mc-job/last?status=Completed

GET api/job/{connectionId}/last?task={task}

Returns the last job executed with the given task.

Example:

GET api/job/mc-job/last?task=MyTask

GET api/job/{connectionId}/last?tag={tag}

Returns the last job executed with the given tag.

Example:

GET api/job/mc-job/last?tag=MyTag

Any of the above-mentioned query strings can be used in combination. For example, this request returns the last job executed with the given task under the given account:

GET api/job/mc-job/list?task=WriteToFile&account=john.doe

Making queries

GET api/job/{connectionId}/list?account={accountId}

Returns a list of all jobs executed under the given account.

Example:

GET api/job/mc-job/list?account=john.doe

GET api/job/{connectionId}/list?since={dateTime}

Returns a list of all jobs executed since the given datetime. A datetime value is given as a modified ISO 8601 format (with the ":" separators in the time specification omitted).

Example:

GET api/job/mc-job/list?since=2014-02-15T220000

GET api/job/{connectionId}/list?status={status}

Returns a list of all jobs with the given status. Status is either Pending, InProgress, Error or Completed.

Example:

GET api/job/mc-job/list?status=Completed

GET api/job/{connectionId}/list?task={task}

Returns a list of all jobs executed with the given task.

Example:

GET api/job/mc-job/list?task=MyTask

GET api/job/{connectionId}/list?tag={tag}

Returns a list of all jobs executed with the given tag.

Example:

GET api/job/mc-job/list?tag=MyTag

Any of the above-mentioned query strings can be used in combination. For example, this request returns a list of all jobs executed under the given account since the given datetime:

GET api/job/mc-job/list?account=john.doe&since=2014-02-15T220000

Deleting jobs

DELETE api/job/{connectionId}/{id} locked

Removes a job with the given id.

Example:

DELETE api/job/mc-job/7299875c-ee1f-4f20-bb30-066cc267f1bd
Authorization: Basic YWRtaW46VGhpc0lzTm90VGhlUmVhbFBhc3N3b3JkIQ==

DELETE api/job/{connectionId}?before={dateTime} locked

Removes all jobs executed before the given datetime.

Example:

DELETE api/job/mc-job?before=2015-01-20T160000
Authorization: Basic YWRtaW46VGhpc0lzTm90VGhlUmVhbFBhc3N3b3JkIQ==

DELETE api/job/{connectionId}?task={task} locked

Removes all jobs executed for the given task.

Example:

DELETE api/job/mc-job?task=WriteToFile
Authorization: Basic YWRtaW46VGhpc0lzTm90VGhlUmVhbFBhc3N3b3JkIQ==

Any of the above-mentioned query strings can be used in combination. For example, this request removes all jobs executed for the given task before the given datetime:

DELETE api/job?task=WriteToFile&before=2015-01-20T160000
Authorization: Basic YWRtaW46VGhpc0lzTm90VGhlUmVhbFBhc3N3b3JkIQ==

Job representation

{
  "AccountId": "admin",
  "Finished": "2017-04-24T10:07:04.8313653+02:00",
  "HostId": "localhost",
  "Requested": "2017-04-24T10:07:04.4286502+02:00",
  "Started": "2017-04-24T10:07:04.6491354+02:00",
  "Status": "Completed",
  "Tag": "Postman test",
  "TaskId": "WriteToFile",
  "Id": "d5dc76b9-a6d4-42d1-ac5f-934785201ff3"
}

Zones

A zone is a collection of pixels within a raster (radar) image representing either a point, a line or a polygon. Typically, zones are polygons representing for example run-off catchments, but you can also define point zones representing for example a rain gauge.

If a zone is of type point, it is represented by one particular radar image pixel. If a zone is of type line it is represented by a number of pixels with equal weight in zone intensity calculations. If a zone is of type polygon it is represented by a number of radar image pixels – each weighted according to the part of the pixel laying within the polygon in zone intensity calculations (see image below).

zones

Zone ID

The unique identifier of a zone is a string (e.g. "MyCatchment").

URIs

POST api/zone locked

Adds a new zone.

Example:

POST api/zone
Content-Type: application/json
Authorization: Basic YWRtaW46VGhpc0lzTm90VGhlUmVhbFBhc3N3b3JkIQ==
{
  "Name": "My Zone",
  "Id": "MyZone",
  "ImageSize": "240, 240",
  "Type": "Polygon",
  "PixelWeights": [
    {
      "Pixel": {
        "Col": 89,
        "Row": 113
      },
      "Weight": {
        "Value": 1.0
      }
    }
  ]
}

GET api/zone/{id}

Returns a zone with the given id.

Example:

GET api/zone/MyZone

GET api/zone/list

Returns a list of all zones.

GET api/zone/count

Returns the total number of zones.

DELETE api/zone/{id} locked

Removes a zone with the given id.

Example:

DELETE api/zone/MyZone
Authorization: Basic YWRtaW46VGhpc0lzTm90VGhlUmVhbFBhc3N3b3JkIQ==

Zone representation

{
  "Name": "My Catchment",
  "Id": "MyCatchment",
  "ImageSize": "240, 240",
  "Type": "Point",
  "PixelWeights": [
      {
        "Pixel": {
          "Col": 89,
          "Row": 113
        },
        "Weight": {
          "Value": 0.5
        }
      },
      {
        "Pixel": {
          "Col": 89,
          "Row": 114
        },
        "Weight": {
          "Value": 0.5
        }
      }
  ]
}

Radar Images

A radar image is a raster image that contains precipitation data from a weather radar.

Radar Image ID

The unique identifier of a radar image is a datetime (e.g. 2014-04-25T170000).

URIs

Retrieving metadata The metadata of a radar image does not contain the pixel values.

GET api/radarimage/{connectionId}/last

Returns the last available radar image.

GET api/radarimage/{connectionId}/datetime/last

Returns the datetime for the last available radar image.

GET api/radarimage/{connectionId}/{dateTime}

Returns the radar image at the given datetime.

Example:

GET api/radarimage/dims-radar/2014-02-15T220000

GET api/radarimage/{connectionId}/lastbefore/{dateTime}

Returns the last radar image before the given datetime.

Example:

GET api/radarimage/dims-radar/lastbefore/2014-02-15T220000

POST api/radarimage/{connectionId}/list/lastbefore

Returns a list of radar images before the date times specified in the body.

Example:

POST api/timeseries/dims-radar/list/lastbefore
Content-Type: application/json
[
  "2006-02-15T220000",
  "2006-02-16T220000"
]

POST api/radarimage/{connectionId}/datetimes/lastbefore

Returns a list of datetimes before the date times specified in the body.

Example:

POST api/timeseries/dims-radar/datetimes/lastbefore
Content-Type: application/json
[
  "2006-02-15T220000",
  "2006-02-16T220000"
]

GET api/radarimage/{connectionId}/firstafter/{dateTime}

Returns the first radar image after the given datetime.

Example:

GET api/radarimage/dims-radar/firstafter/2014-02-15T220000

POST api/radarimage/{connectionId}/list/firstafter

Returns a list of radar images after the date times specified in the body.

Example:

POST api/timeseries/dims-radar/list/firstafter
Content-Type: application/json
[
  "2006-02-15T220000",
  "2006-02-16T220000"
]

POST api/radarimage/{connectionId}/datetimes/firstafter

Returns a list of date times after the date times specified in the body.

Example:

POST api/timeseries/dims-radar/datetimes/firstafter
Content-Type: application/json
[
  "2006-02-15T220000",
  "2006-02-16T220000"
]

GET api/radarimage/{connectionId}/datetimes?from={fromDateTime}&to={toDateTime}

Returns a list of date times between fromDateTime and toDateTime

Example:

GET api/radarimage/dims-radar/datetimes?from=2006-02-15T220000&to=2006-02-16T220000

Retrieving bitmap images

GET api/radarimage/{connectionId}/{dateTime}/bitmap

Returns a bitmap of the radar image intensity at the given datetime using the default color gradient.

Example:

GET api/radarimage/dims-radar/2013-07-30T124500/bitmap

radarimage default

GET api/radarimage/{connectionId}/{dateTime}/bitmap?style={colorGradient}

Returns a bitmap of the radar image intensity at the given datetime using the IntensityLightYellowToRed color gradient.

Example:

GET api/radarimage/dims-radar/2013-07-30T124500/bitmap?style=IntensityLightYellowToRed

radarimage red

GET api/radarimage/{connectionId}/style/{colorGradient}/bitmap

Returns a bitmap of the given color gradient.

Example:

GET api/radarimage/dims-radar/style/IntensityDefault/bitmap

colorgradient

Retrieving zone rainfall information

Having defined zones within the radar image boundaries, various statistical information for a zone - such as the accumulated rainfall (the depth) or the average rain intensity within a certain time interval - can be calculated and retrieved on the fly.

GET api/radarimage/{connectionId}/depth/{zoneId}?from={from}&to={to}

Calculates the accumulated rainfall (the depth) in the given zone within the given time interval.

Example:

GET api/radarimage/dims-radar/depth/260080?from=2015-11-19T000000&to=2015-11-20T000000

GET api/radarimage/{connectionId}/depth/{zoneId}?hours={hours}

Calculates the accumulated rainfall (the depth) in the given zone within the last given number of hours.

Example:

GET api/radarimage/dims-radar/depth/260080?hours=24

GET api/radarimage/{connectionId}/intensity/max/{zoneId}?from={from}&to={to}

Calculates the maximum intensity (mm/h) in the given zone within the given time interval.

Example:

GET api/radarimage/dims-radar/intensity/max/260080?from=2015-11-19T000000&to=2015-11-20T000000

GET api/radarimage/{connectionId}/intensity/average/{zoneId}?from={from}&to={to}

Calculates the average intensity (mm/h) in the given zone within the given time interval.

Example:

GET api/radarimage/dims-radar/intensity/average/260080?from=2015-11-19T000000&to=2015-11-20T000000

GET api/radarimage/{connectionId}/intensity/average/{zoneId}?hours={hours}

Calculates the average intensity (mm/h) in the given zone within the last given number of hours.

Example:

GET api/radarimage/dims-radar/intensity/average/260080?hours=24

GET api/radarimage/{connectionId}/intensities/{zoneId}?from={from}&to={to}

Returns a time series of mean intensities (mm/h) in the given zone within the given time interval.

Example:

GET api/radarimage/dims-radar/intensities/260080?from=2015-11-19T000000&to=2015-11-20T000000

Radar Image representation

{
  "PixelValueType": {
    "DisplayName": "Reflectivity",
    "Value": 0
  },
  "TimeOfForecastOffset": 0,
  "Type": {
    "DisplayName": "Observation",
    "Value": 0
  },
  "DateTime": "2015-11-24T14:20:00",
  "GeoCenter": {
    "x": 0,
    "y": 0
  },
  "HasValues": true,
  "MaxValue": 28.25,
  "MinPositiveValue": 3,
  "MinValue": 0,
  "PixelSize": "500, 500",
  "PixelValueUnit": "dBZ",
  "ImageSize": "240, 240",
  "Name": "LAWR Radar DHI",
  "Id": "2015-11-24T14:20:00"
}