API Documentation

Welcome to the documentation for communicating with Tiseda. In this documentation you'll find how to create and manage the configuration, all the methods to add data into Tiseda and of course how to retrieve the raw or aggregated data.

Choose your flavour

Using the following libraries you can communicate with Tiseda directly from your application. The fully featured libraries offer all the functionality while the other libraries are still in development. The syntax and function calls of all libraries are built to be very similar to each other while also incorporating the native objects of the programming language.

Language Features Package Manager/Url Download/Url
.NET Fully featured NuGet TisedaConnection.dll
JavaScript Fully featured - Tiseda.min.js
Rest API Fully featured Swagger/OpenAPI -
Python Some data features - Coming soon
PHP Some data features - Coming soon

Configuration

Structure

The configuration in Tiseda is defined in tree of data points. Each data point is a container under which time series data values are stored (Moment, Value). These data points have properties to describe the data and the aggregation which needs to be done on the data.

Data point structure:

Retrieve

Retrieve all data points matching the filter. The filter searches on tags and supports the wildcard ? (Match any character) and * (Match everything following). The filter also has support for And operators && and Or operators ||. Optionally the parameters limit and skip can be used to control the amount of results. 

    var dataPoints = tiseda.Select("Filter").Retrieve();
tiseda.Select("Filter").Retrieve(0, 0, function(dataPoints) {
  // dataPoints contains a list of the data points
});
GET https://api.tiseda.com/Configuration/Retrieve?filter=Filter

CreateOrUpdate

Pass a data point configuration to Tiseda. If the Id is 0, a new data point will be created in Tiseda. Otherwise the existing data point will be updated with the new configuration.

    var dataPoint = new TisedaDataPoint()
    {
        Id = 0,
        DataType = DataType.Consumption,
        AggregationOperationType = OperationType.None,
        StreamingAggregationType = AggregationType.Sum,
        ValuesPeriod = 3600,
        Links = new List<TisedaLink>(),
        Tags = new List<string>() { "Tag 1", "Tag 2" }
    };

    // Setting the second parameter to true will update the dataPoint object with the new Id after saving
    tiseda.CreateOrUpdate(dataPoint, true);
var dataPoint = new Tiseda.TisedaDataPoint();
dataPoint.Id = 0;
dataPoint.DataType = Tiseda.DataType.Consumption;
dataPoint.AggregationOperationType = Tiseda.OperationType.None;
dataPoint.StreamingAggregationType = Tiseda.AggregationType.Sum;
dataPoint.ValuesPeriod = 3600;
dataPoint.Links = [];
dataPoint.Tags = ["Tag 1","Tag 2"];

// Setting the second parameter to true will update the dataPoint object with the new Id after saving
tiseda.CreateOrUpdate(dataPoint, true, function() {
    // Created or updated
});
POST https://api.tiseda.com/Configuration/CreateOrUpdate
{
    "Id": 0,
    "DataType": 0,
    "AggregationOperationType": 0,
    "StreamingAggregationType": 0,
    "ValuesPeriod": 3600,
    "Links": [],
    "Tags": ["Tag 1", "Tag 2"]
}

CreateOrSelectExisting

Select a data point using the tag as a filter, if it doesn't exist, create one with the given configuration added and return it. If the parameter updateChanges is true, it will overwrite the configuration if a data point is found.

    var dataPoint = new TisedaDataPoint()
    {
        Id = 0,
        DataType = DataType.Consumption,
        AggregationOperationType = OperationType.None,
        StreamingAggregationType = AggregationType.Sum,
        ValuesPeriod = 3600,
        Links = new List<TisedaLink>(),
        Tags = new List<string>() { "Tag 1", "Tag 2" }
    };
    // Setting the third to true will update an existing datapoint with the new settings
    tiseda.CreateOrSelectExisting(dataPoint, "Tag 3", false);
    
var dataPoint = new Tiseda.TisedaDataPoint();
dataPoint.Id = 0;
dataPoint.DataType = Tiseda.DataType.Consumption;
dataPoint.AggregationOperationType = Tiseda.OperationType.None;
dataPoint.StreamingAggregationType = Tiseda.AggregationType.Sum;
dataPoint.ValuesPeriod = 3600;
dataPoint.Links = [];
dataPoint.Tags = ["Tag 1","Tag 2"];

// Setting the third to true will update an existing datapoint with the new settings
tiseda.CreateOrSelectExisting(dataPoint, "Tag 3", false, function() {
    
});
POST https://api.tiseda.com/Configuration/CreateOrSelectExisting
{
    "DataPoint": {
        "Id": 0,
        "DataType": 0,
        "AggregationOperationType": 0,
        "StreamingAggregationType": 0,
        "ValuesPeriod": 3600,
        "Links": [],
        "Tags": ["Tag 1", "Tag 2"]
    },
    "Tag": "Tag 3",
    "UpdateChanges": false
}

ApplyFormula

Apply a math formula to the data point. Multiple formulas can be applied using the optional From/Till parameters. When overlapping, the last applied formula will be used in the overlapping period. The formula will be executed for each unique value moment in the referenced data points.

Syntax help:
Use a hash tag followed by a number to reference a data point.
Round brackets are supported as well as the math functions SIN, TAN, LOG, SQRT, ACOS, ASIN, ATAN, COSH, SINH, TANH, EXP, LOG10, CEIL, FLOOR, ABS.
Using :Seconds after a data point will apply a time shift to the retrieved data. Example to use data from an hour earlier: #123:-3600
Using :Seconds after another number will turn this number into a consumption per [Seconds] time. For example, when you want to add 25 consumption per minute to data point #123, use #123 + 25:60
Inline if's are possible using the syntax (ValueOrDataPointA Comparison ValueOrDatapointB ? ValueWhenTrue : ValueWhenFalse), For example to turn all values higher than 5 into 5: (#123 > 5 ? 5 : #123)
Using #DataPointA||#DataPointB an alternative can be defined for when the first data point does not have data.
By using ! anywhere in the formula, the formula will stop and return Missing if there was no value at that point during execution. Use this to mark required variables, for example: (#123!) / (#456!) will make sure this formula only returns values if there is data for both #123 and #456.
Note: The order of executing is always from left to right. The standard mathematic precedence rules do not apply here! Groups are executed first and can be used to force precedence. 

    var dataPoint = tiseda.Select(789).Retrieve().First();
    dataPoint.ApplyFormula("#123 * (15 + #456)", new DateTime(2010,01,01), new DateTime(2030,01,01));    
    tiseda.CreateOrUpdate(dataPoint, false);
tiseda.Select(789).Retrieve(0,0,function(dps) {
    var dataPoint = dps[0];

    dataPoint.ApplyFormula("#123 * (15 + #456)", new Date("2010-01-01").getTime(), new Date("2030-01-01").getTime());    
    tiseda.CreateOrUpdate(dataPoint, false, function() {
        
    });
});
POST https://api.tiseda.com/Configuration/ApplyFormula
{    
    "DataPointId": 789,
    "Formula": "#123 * (15 + #456)",
    "From": "2010-01-01T00:00:00Z",
    "Till": "2030-01-01T00:00:00Z"
}

ApplyCounterToConsumption

This aggregation converts counter values (like electricity meter readings) to consumption values. The following parameters are optionally available to support working with the raw data: 

    var dataPoint = tiseda.Select(456).Retrieve().First();
    dataPoint.ApplyCounterToConsumption(123, counterMax: 10000);    
    tiseda.CreateOrUpdate(dataPoint, false);
tiseda.Select(456).Retrieve(0,0,function(dps) {
    var dataPoint = dps[0];

    // Parameters: sourceDataPointId, maxReversable?, counterMax?, counterMin?, maxConsumption?, factor?
    dataPoint.ApplyCounterToConsumption(123, null, 10000);    
    tiseda.CreateOrUpdate(dataPoint, false, function() {
        
    });
});
POST https://api.tiseda.com/Configuration/ApplyCounterToConsumption
{    
    "DataPointId": 456,
    "SourceDataPointId": 123,
    "CounterMax": 10000
}

ApplyGaps

Reports about the source datapoints and store a value on the exact moment when there is data in the source or no data. This aggregation will first check the first source data point, if this one has no data, it will continue with the next ones using the same method. This will change the ValuesPeriod of this data point to 1. The optional parameter resultValues can be used to define what value needs to be stored at the moment when data is detected. By default it will use the index (starting with 1) of the data point in the source data point array. 

    var dataPoint = tiseda.Select(456).Retrieve().First();
    dataPoint.ApplyGaps(new uint[] { 123 }, new double[] { 100 });
    tiseda.CreateOrUpdate(dataPoint, false);
tiseda.Select(456).Retrieve(0,0,function(dps) {
    var dataPoint = dps[0];

    // Parameters: sourceDataPointIds[], resultValues[]?
    dataPoint.ApplyGaps([123], [100]);    
    tiseda.CreateOrUpdate(dataPoint, false, function() {
        
    });
});
POST https://api.tiseda.com/Configuration/ApplyGaps
{    
    "DataPointId": 456,
    "SourceDataPointId": [123],
    "ResultValues": [100]
}

ApplySummary

Combine multiple data points and apply an aggregation. Note that the ValuesPeriod for this data point needs to be lower than -1 or higher than 1. The parameter 'aggregationType' is used to decide what aggregation to do (Sum/Min/Max/Average).

    var dataPoint = tiseda.Select(456).Retrieve().First();
    dataPoint.ApplySummary(new uint[] { 123 }, AggregationType.Avg);
    tiseda.CreateOrUpdate(dataPoint, false);
tiseda.Select(456).Retrieve(0,0,function(dps) {
    var dataPoint = dps[0];

    // Parameters: sourceDataPointIds[], aggregationType?
    dataPoint.ApplySummary([123], Tiseda.AggregationType.Avg);    
    tiseda.CreateOrUpdate(dataPoint, false, function() {
        
    });
});
POST https://api.tiseda.com/Configuration/ApplySummary
{    
    "DataPointId": 456,
    "SourceDataPointId": [123],
    "AggregationType": 3
}

Delete

Delete specific data points. By default this call will do nothing if the data point is used in aggregations by other data points. Use the parameter 'force' to override this check and always delete this datapoint.

    var dataPoint = tiseda.Select(456).Delete(true);
tiseda.Select(456).Delete(true,function() {
    // Finished deleting
});
POST https://api.tiseda.com/Configuration/Delete
{    
    "DataPointId": 456,
    "Force": true
}

Insert Data

Using code

Insert one or multiple values to data points using their Id or Tag. When committing the values are send to Tiseda using the specified InsertMethod. The following InsertMethods are available:

    tiseda.AddValue(new DateTime(2020,01,01), 1234, "Tag 1");
    tiseda.AddValue(new DateTime(2020,01,02), 5678, "Tag 1");
    tiseda.CommitValues(InsertMethod.InsertOnlyNewerValues);
tiseda.AddValue(new Date("2020-01-01").getTime(), 1234, "Tag 1");
tiseda.AddValue(new Date("2020-01-02").getTime(), 5678, "Tag 1");
tiseda.CommitValues(Tiseda.InsertMethod.InsertOnlyNewerValues);
POST https://api.tiseda.com/Value/Add
{
    "Filter": "Tag 1",
    "Values": [
        { "Moment": "2020-01-01T00:00:00Z", "Value": 1234 },
        { "Moment": "2020-01-02T00:00:00Z", "Value": 5678 },
    ],
    "InsertMethod": 5
}

Streaming

Stream data into a buffer in Tiseda. The StreamingAggregationType and ValuesPeriod will be used to calculate the actual value to be saved.

Retrieve Data

RetrieveValues

Used to retrieve aggregated data. Use the From/Till parameters to select what period to retrieve. The parameter 'interval' is used to decide how to divide the period (None 0, Seconds 1, Minutes 2, FifteenMinutes 3, Hour 4, Day 5, Month 6, Year 8).
Alternatively an array of Moments can be passed to exactly decide what period needs to be retrieved with what exact divide moments. [Start Moment, Divide moment, Divide moment, .., End moment].
The following aggregation types are available:

    var values = tiseda.Select("Filter")
        .RetrieveValues(new DateTime(2010,01,01), new DateTime(2020,01,01), IntervalType.Year, AggregationType.Automatic);
tiseda.Select("Filter")
    .RetrieveValues([new Date("2010-01-01").getTime(), new Date("2020-01-01").getTime()], "Year", Tiseda.AggregationType.Automatic, function(values) {
        // values contains a dictionary with data point Id as key, and an array of { Moment: Epoch, Value: Number } as value.
    });
GET https://api.tiseda.com/Value/Retrieve?filter=Filter&from=2010-01-01T00:00:00Z&till=2020-01-01T00:00:00Z&interval=8&aggregation=60

RetrieveRawValues

The underlying raw data for a data point can be received using this method. If the parameter 'expand' is set to true, the From and Till moments will be automatically expanded till it finds a value before and value after the period given.

    var values = tiseda.Select("Filter")
        .RetrieveRawValues(new DateTime(2010,01,01), new DateTime(2020,01,01), true);
tiseda.Select("Filter")
    .RetrieveRawValues(new Date("2010-01-01").getTime(), new Date("2020-01-01").getTime(), function(values) {
        // values contains a dictionary with data point Id as key, and an array of { Moment: Epoch, Value: Number } as value.
    });
GET https://api.tiseda.com/Value/RetrieveRaw?filter=Filter&from=2010-01-01T00:00:00Z&till=2020-01-01T00:00:00Z&expand=true

Changes

Tiseda keeps track of the exact moment when data points are changed and what period is changed (Default these changes are only stored a week). Use this method to retrieve those changes. Store and use the 'position' parameter to only retrieve changes since the previous call to this method.

    ulong position = 0;
    var changes = tiseda.RetrieveChanges(ref position, "Filter*");
    // position is now updated with a high number
tiseda.RetrieveChanges(0, "Filter*", true, function(journalLines, newPosition) {

});
GET https://api.tiseda.com/Value/RetrieveChanges?filter=Filter*&position=0

Manage Users

RetrieveUsers

CreateUser

DeleteUser