TimeSeries Walkthrough¶

This page shows how to add TimeSeries endpoints to an existing Domain Services Web API project. By the end you will have a working /api/timeseries/{connectionId} that reads from a CSV folder, with Swagger showing all available endpoints.

Choosing a Service Class¶

TimeSeries has a hierarchy of service classes. Pick the one that matches your data model:

Connection class	Service class	Use when…
`TimeSeriesServiceConnection`	`TimeSeriesService<TId,TValue>`	Basic named time series, read and update
`DiscreteTimeSeriesServiceConnection`	`DiscreteTimeSeriesService<TId,TValue>`	Read-only listing of all series (`GetAll`, `Count`)
`GroupedDiscreteTimeSeriesServiceConnection`	`GroupedDiscreteTimeSeriesService<TId,TValue>`	Series organised into groups/projects
`UpdatableTimeSeriesServiceConnection`	`UpdatableTimeSeriesService<TId,TValue>`	Full CRUD on series (add/remove/update)
`GroupedUpdatableTimeSeriesServiceConnection`	`GroupedUpdatableTimeSeriesService<TId,TValue>`	Group-aware full CRUD

Default type parameters are TId = string, TValue = double. Most use cases work with TimeSeriesService<string, double>.

Step 1 — Install the Package¶

dotnet add package DHI.Services.TimeSeries.WebApi

This also brings in DHI.Services.TimeSeries (which includes the built-in CSV provider).

Step 2 — Register the Converters¶

In Program.cs, inside .AddJsonOptions(...):

options.JsonSerializerOptions.AddConverters(
    DHI.Services.TimeSeries.WebApi.SerializerOptionsDefault.Options.Converters
);

Warning: Forgetting this step causes NotSupportedException at runtime when the API tries to serialize TimeSeries or DataPoint objects.

Step 3 — Add a Connection Entry¶

Option A — Declarative (`connections.json`)¶

Add an entry in App_Data/connections.json. The CSV provider is built into DHI.Services.TimeSeries:

{
  "$type": "System.Collections.Generic.Dictionary`2[[System.String, mscorlib],[DHI.Services.IConnection, DHI.Services]], mscorlib",
  "ts-csv": {
    "$type": "DHI.Services.TimeSeries.WebApi.TimeSeriesServiceConnection, DHI.Services.TimeSeries.WebApi",
    "ConnectionString": "[AppData]timeseries",
    "RepositoryType": "DHI.Services.TimeSeries.CSV.TimeSeriesRepository, DHI.Services.TimeSeries",
    "Name": "TimeSeries (CSV)",
    "Id": "ts-csv"
  }
}

The ConnectionString points to a folder containing your .csv files. Each .csv file is treated as a named time series (the file name without extension becomes the series ID).

Option B — Imperative (code)¶

ServiceLocator.Register(
    new DHI.Services.TimeSeries.TimeSeriesService<string, double>(
        new DHI.Services.TimeSeries.CSV.TimeSeriesRepository(
            "[AppData]timeseries".Resolve()
        )
    ),
    "ts-csv"
);

Step 4 — SignalR Prerequisite¶

TimeSeries Web API controllers require IFilterRepository in DI. Register it in Program.cs:

builder.Services.AddSingleton<IFilterRepository>(
    new FilterRepository("[AppData]signalr-filters.json".Resolve())
);
builder.Services.AddSignalR();

The signalr-filters.json file does not need to exist on disk; the registration just satisfies DI.

Step 5 — Add Sample CSV Data¶

Create App_Data/timeseries/ and add a CSV file, for example WaterLevel.csv:

DateTime,Value
2024-01-01T00:00:00Z,1.23
2024-01-01T01:00:00Z,1.45
2024-01-01T02:00:00Z,1.67
2024-01-01T03:00:00Z,1.52

The first column must be parseable as DateTime; the second as double.

Step 6 — Verify in Swagger¶

Start the API and open Swagger. You should see a /api/timeseries/... group. Common calls:

Get all series IDs

GET /api/timeseries/ts-csv

Get all data points for a series

GET /api/timeseries/ts-csv/WaterLevel/values

Get the last data point

GET /api/timeseries/ts-csv/WaterLevel/values/last

Key Data Types¶

Type	Description
`TimeSeries<TId, TValue>`	The series entity — holds `Id`, metadata, and column definitions
`TimeSeriesData<TValue>`	A collection of `DataPoint<TValue>` values for a series
`DataPoint<TValue>`	A single `(DateTime Timestamp, TValue Value)` pair

Using Other Providers¶

Swap RepositoryType in connections.json to use a different backend:

Provider	NuGet package	`RepositoryType` assembly
CSV (built-in)	`DHI.Services.TimeSeries`	`DHI.Services.TimeSeries`
USGS (live data)	`DHI.Services.Provider.USGS`	`DHI.Services.Provider.USGS`
PostgreSQL	`DHI.Services.Provider.PostgreSQL`	`DHI.Services.Provider.PostgreSQL`
MIKE DFS files	`DHI.Services.MIKECore`	`DHI.Services.MIKECore`

See domain_services/references/time_series/ for provider-specific documentation.

Summary¶

Install DHI.Services.TimeSeries.WebApi to get REST endpoints for time series data.
Register DHI.Services.TimeSeries.WebApi.SerializerOptionsDefault.Options.Converters in Program.cs.
Add a TimeSeriesServiceConnection entry in connections.json and point ConnectionString at your data folder.
The CSV provider is built-in — no extra package needed for local development.
Switch providers by changing RepositoryType only; the service and endpoints stay the same.

Next: Jobs