Events

Nexus events API returns raw or reduced (thinned out) timeseries events, or seasonal statistics of these events.

GET /events/?world={world_alias}&timeseries_id={timeseries_id}&token={web_api_token}

Parameters¶

Parameter	Mandatory	Meaning	Default value
`world`	Yes	Alias of world	-
`timeseries_id`	Yes	ID of timeseries in Nexus (retrieve through WFS `timeseries` feature type)	-
`view`	No	Type of view: `raw`, `reduced` or `seasonal_stats`	`raw`
`count`	No	Number of events to return	`100000`
`startindex`	No	Starting point for counting events (normally combined with `count`)	`0`
`sortby`	No	Sort property and order. Options: `timestamp d`, `timestamp a`, `value d`, `value a`	`timestamp d`
`range`	No	Applicable time domain, specified as `<start>/<end>`. Mandatory with `reduced` and `seasonal_stats`.	-
`bucket_interval`	No	Bucket size, specified as for example `P1D`. Mandatory with `reduced` and `seasonal_stats` view.	-
`stats`	No	Only for the `seasonal_stats` view, comma separated statistics: `mean`, `min`, `max` or percentiles	-

Example

Request:

curl "https://nexus.stellaspark.com/api/v1/events/?world=sandbox&timeseries_id=13&count=3&token={web_api_token}"

Response:

timestamp,value
2025-10-21 00:00:00+00,16.1
2025-10-20 00:00:00+00,17.1
2025-10-19 00:00:00+00,14.2

Views¶

By default, the API returns all events of a timeseries (raw view). In addition, there is a reduced view, which returns a thinned out set of events. The data reduction algorithm divides the original raw timeseries in a certain amount of time buckets, defined by bucket_interval. For each time bucket two events are selected: the one with highest and with the lowest value. The left-most bucket is aligned with the left side of the range. So for example, for a range 2025-01-01T12:00:00Z/2025-01-02T12:00:00Z and bucket interval P2H, the initial bucket is between 2025-01-01T12:00:00Z and 2025-01-01T14:00:00Z.

If a bucket does not contain any events, logically nothing is returned for that bucket. In case the event with highest value within a bucket is the same as the event with lowest value, the event is returned only once (no duplicates).

Seasonal statistics¶

The seasonal_stats view returns statistics of the events per time bucket, calculated over the events within range. For example, with bucket_interval=P1M and range=-P5Y/+P0D, it returns for each month of the year the statistics of that month over the last 5 years. The season follows from the bucket interval:

`bucket_interval`	Bucket	Season
`P1Y`	Year	Year
`P1M`	Month of year	Year
`P1W`	Week of year	Year
`P1D`	Day of month	Week
`PT1H`	Hour of day	Day

Specify the statistics to calculate with stats, as a comma separated list of mean, min, max and percentiles, such as p12.5 or p50 (the median). The current season is left out, since it is not complete yet. At least 3 seasons of events are needed, otherwise only the header is returned.

Example

Request:

curl "https://nexus.stellaspark.com/api/v1/events/?world=sandbox&timeseries_id=13&view=seasonal_stats&bucket_interval=P1M&range=-P5Y/%2BP0D&stats=mean,p12.5,p87.5&token={web_api_token}"

Response:

bucket,mean,p12.5,p87.5
1,62.3,31.2,95.4
2,51.8,24.9,80.1
3,48.6,22.0,77.3

Data chunking¶

Be aware that data volumes in Nexus can be huge. If you request all events of a timeseries at once, it may result in a truly large output file (especially for long series and/or high-frequency data). A core concept when you are working with the API is therefore to iterate over the content to gather everything that you are interested in.

This means that when you access data, you will retrieve it in parts. With the count parameter, you tell the API how much data you want to see at once. Together with the offset you can tell the API from where it should start counting in order to get the next chunk of data.

Example

Request:

curl "https://nexus.stellaspark.com/api/v1/events/?world=sandbox&timeseries_id=13&count=3&startindex=10&token={web_api_token}"

Response:

timestamp,value
2025-10-11 00:00:00+00,16.2
2025-10-10 00:00:00+00,17.5
2025-10-09 00:00:00+00,16.7

Note

By default, Nexus limits the number of returned rows to 100000.

Range¶

Optionally, a range can be specified as <start>/<end> to only select timeseries events in a limited window. The range may be defined as a static set of dates, timestamps, or relative offsets. Time range must be specified according to ISO 8601 standard. An ISO 8601 period string prefixed with a '+' or '-' indicates an offset relative from now, whereas an ISO 8601 period string without prefix indicates a relative offset from either the start or end of the range.

Example

Examples of valid ranges (unencoded):

- -P3D/+P1D (from 3 days ago until 1 day ahead)
- -P5M/P2M (from 5 months ago until 3 months ago)
- 2020-01-03T13:00/P3D (from January 3rd, 2020 until January 6th, 2020)
- 2020-01-03/2020-02-05 (static dates)

Bucket interval¶

The bucket_interval is specified as an ISO 8601 duration. For the reduced view, supported durations are weeks, days, hours, minutes and seconds. Durations don't need to be whole numbers, decimals are allowed. For the seasonal_stats view, supported durations are P1Y, P1M, P1W, P1D and PT1H.

Example

Examples of valid bucket intervals:

- P3D (3 days)
- PT6H (6 hours)
- P2DT6H30M (2 days, 6 hours and 30 minutes; this is equivalent to `P2DT6.5H`)