[GSOC 2026] Proposal Idea: adding time zone support for timestamps in temporal database

GRASS GRASS developer
1

Hello Devs and Community,

Hope all of you are doing fine.

While surfing thru the repository, solving an unrelated issue, I came across a comment that said the following:

.# TODO: Write time zone support for timestamp

I noticed that the current timestamps do not have any time-zone support. This exact message is in a file called c_libraries_interface.py in python/grass/temporal/.

I opened an issue addressing how this should be implemented … and to understand if this is something the project would like to support. To which, @wenzeslaus replied – There is currently no specification for how this should be implemented. Specification, experimentation, and creating an implementation plan is the work which needs to be done here.

Before suggesting any concrete implementation ideas, I just wanted to know what the requirements are for something like this… things like what are the current design decisions around timestamp handling in grass.

From what I could infer during my time in the repo, I learned that timestamps are curerntly parsed into python datetime objects without explicit timezone implementation… this raises a few questions about how timestamps should behave when datasets originate from multiple different regions.

for example, modern datasets, … especially satellite imagery and other remote sensing data, often use ISO-8601 timestamps such as:

2025-03-10T12:00:00Z  ->  UTC
2025-03-10T12:00:00+05:30   -> IST

at the moment, it is not entirely clear whether these formats are expected to be supported, ignored, or normalized internally.

I also found a post on discourse (from 2014) .. [Temporal: problem parsing when timezone present]
and it seems like sqlite does not support time-zones… and that also raises a few questions about how timezone information should interact with the sqlite backend. (or if we need to look at postgresql for an alternative)

Because of this, I wanted to ask the community a few questions before exploring this idea further.

Questions for the community:

  1. Has timestamps been discussed before?..
  2. Is there a specific reason why timestamps are currently handled without timezone information?
  3. Would supporting ISO-8601 timezone-aware timestamps be desirable for GRASS temporal datasets?
  4. If timezone support were to be implemented, would it make sense to normalize timestamps internally to UTC while accepting timezone-aware input?

My intention isn’t to propose an implementation plan yet, I just want to understand the constraints involved and design decisions before I attempt to explore this further.

If this is an area that could benefit from improvement, it would be my pleasure to investigate the timestamp parsing pipeline and experiment with possible approaches.

Any thoughts, historical context, or pointers to previous discussions would be greatly appreciated.

Thank you for your time.

2

Hello everyone,

This is a follow up post.

I’ve decided to explore this area personally, and hopefully to try and discover where exactly we would need to implement timezone support.

From my initial investigation of the codebase, here is a structured approach I’d like to outline, and get feedback from the community before moving further.

1. Understand the current timestamp pipeline:

My first goal is understanding the full life-cycle of timestamps in grass. I want to answer four critical questions:

  • where timestamps are created
  • how they are parsed
  • how they are stored in the temporal database
  • where timezone information is lost

Based on my exploration so far, timestamps appear to be parsed into python datetime objects without explicit timezone support

2. Code areas under investigation

Some possible places to look for …

For parsing

  • c_libraries_interface.py
  • abstract_map_dataset.py
  • space_time_datasets.py
  • core.py
    all of the above are in the python/grass/temporal/ directory, and I came across them while solving an unrelated issue.

Temporal Database Layer

  • /lib/temporal/SQL

I’m planning to trace how timestamps move thru these layers and exactly where time-zone information is lost…

3. Module-level interaction

I also want to understand how timestamps are written and used across modules. Some of them are here:

  • t.register
  • t.info
  • r.timestamp
  • v.timestamp
  • t.rast.series

4. Possible design direction ( an initial thought )

One potential direction I am considering is accepting timezone aware input … ISO-8061 format, and then we normalize everything to UTC internally. That way don’t have to negotiate with using SQL not accepting timezone aware input…

The only bottleneck here would be when retrieving data back from the database. For that, we could potentially change the schema (if required) to store the timezone part separately in another column.

Any direction or suggestions are really appreciated.

I also made a mock proposal that I’d like to share with the maintainers and the community. It would be of immense help to me if you could direct me in the right direction.

I’ll share the link in case anyone wants to add suggestions.

3

Hei Dasux,

Thanks for your proposal. Some feedback regarding your questions:

  1. I am not aware of a broader discussion of time zones…

  2. My assumption is that the reason for not including time-zone information is the SQLite database backend (as you also analyze).

  3. Being explicit about timezones would be valuable. Not sure how important / useful it would be if tools would return or accept local time, as that may add back confusion… Expecting, storing and providing UTC timestamps would be fully OK with me.

  4. In general, I do agree that storing data in UTC seems the most appropriate way to handle the time-zone issue. In a way, GRASS does this already now, only implicitly. So, from my perspective, the implementation would be to a) to document better that “no-timezone” means UTC. Note that e.g. r.timestamp on the one hand does not even require “time” information, but on the other hand it allows storing data time zone information already… SQLite support is mandatory so any implementaion should be compatible with SQLite. It is similar to Python where datetime.fromisoforamt() does not allow a Z in the string, while +00:00 is OK… Note that incomple “timestamps” are allowed, and that both Python API, C API and database backend need to be considered in any implementation…

Cheers

Stefan

4

Hey @Sefan

Thanks for the feedback and direction.. this genuinely clears up a lot of confusion on my end.

Initially, I was approaching this as just “adding time-zone support for timestamps” … but your point about GRASS already implicitly treating timestamps as UTC helped me reframe it. It now feels like the task is to make this behaviour explicit and consistent, instead of introducing something new.

I’ll do some homework into how timestamps are actually flowing thru the system… especially how parsing is handled (including the z vs +00:00 case you mentioned).

Also I’ll check where inconsistencies show up … ( i ran into one already with r.timestamp and r.info ---- one of them shows timestamps written when raster maps are registered from another mapset. [bug #3394])

I’ll also look into how python, C and the database layer are handling things.

Also, i hadn’t fully considered incomplete timestamps before… I’ll look into how those are treated across the stack.

Still wrapping my head around the full pipeline, but i’ll trace it more carefully … and follow up when i have something more concrete.

Thanks again.
Anirban