Time series

Sarkoa can show how something changed over time, and there are two different ways to do it. Which one you want depends on how your data arrived.

Your data looks like Use
Many files, one per date. Monthly drone flights, weekly snapshots, a run of satellite scenes Time series
One file with a date column in it. A survey table, an events export, sensor readings Timeline

The distinction is worth getting right at upload, because switching later means reprocessing.

Time series

A Time series is a container holding dated entries. Each entry is a whole file: one orthophoto, one snapshot of a boundary layer, one day's readings. The map shows one entry at a time and swaps between them as you move the scrubber.

This is the option for rasters. A time-lapse of drone flights or satellite passes has to be a series, because each date is genuinely a separate image.

Building a series

At upload, set Time to Time series, then either pick an existing series or start a new one. You set the capture time for each file. Sarkoa suggests one from the filename when the filename has a recognisable date in it, which most exports do.

From the CLI:

sarkoa series create "Site flights 2026"
sarkoa series append SERIES_ID ./2026-03-14.tif --captured-at 2026-03-14
sarkoa series append SERIES_ID ./2026-04-11.tif --captured-at 2026-04-11
sarkoa series list

--captured-at takes an ISO date or timestamp. If an entry covers a span rather than an instant, add --period-start and Sarkoa treats it as a range.

Appends are safe to retry. Pass --idempotency-key and a repeated call will not create a duplicate entry. Large files resume if the connection drops.

Vector entries: turn the in-file timeline off

A vector upload looks for a date column and, when it finds one, builds a timeline inside that file. For a series entry that is usually the wrong layer of time: --captured-at already says where the frame sits on the scrubber, and a column like updated or acquired_at describes the features, not the frame. Add --temporal-mode off so each entry stays an ordinary snapshot:

sarkoa series append SERIES_ID ./perimeters_2026-03-14.geojson \
  --captured-at 2026-03-14T12:00:00Z --temporal-mode off

Leave it on only when one entry genuinely holds its own span of feature timestamps.

Styling a series

Style the series itself, not the individual entries. The style applies to every frame, so the colours stay put while you scrub instead of flickering as the map swaps files.

That means a series works best when its entries are alike: all rasters of the same kind, or all vectors with the same attributes. A series mixing rasters and vectors will style from the most recent entry that can be styled, which is rarely what you want.

Putting one on a map

Add the series to a custom map the same way you add any other layer. The scrubber appears automatically. Filters and thresholds you set on the series keep working as the frames change.

In the layers panel, the eye on the series row turns the whole series off. Hiding a different layer next to it leaves the series on. Expand the series if you want to pin one frame; that does not hide your other layers.

Choosing your dates

A scrubber is only as good as its spacing. Twelve monthly flights read well. Twelve monthly flights plus one scene from four years ago mostly gives you a long empty stretch and a jump at the end.

If you have a sparse historical archive and a dense recent run, they usually belong in two series rather than one.

Timeline

A Timeline puts time inside a single file. Sarkoa reads a date field from your data, and the map lets you scrub through the file, showing only the features that fall inside the current window.

Use it when one file already contains the time dimension: an incident log with a reported date, a wildlife survey with observation timestamps, a table of readings.

Timeline uploads need an Essential plan or above. Playback of a file that already has a timeline is not restricted, so anyone you share the map with can use the scrubber regardless of their plan.

Turning one on

At upload, set Time to Timeline. Sarkoa looks for date and time fields in the file and prepares the layer for playback.

If your file has more than one date column, say created_at and resolved_at, name the one you want. Automatic detection has to pick something, and it will not always pick the field your map is about.

Vector formats only. To put a timeline on imagery, use a Time series instead.

Which one, in practice

Both end up as a scrubber on the map, so it can be hard to tell from the outside which you are looking at. The rule of thumb:

  • Separate files that arrived on separate days are a Time series.
  • One file with a date column is a Timeline.
  • Rasters are always a Time series.
  • If you would have to merge your files into one before uploading, do not. That is what a series is for.