Add timezone parameter to Stats API endpoints

[jon-mercer]

Changes

This PR adds a timezone parameter to the Stats API endpoints (timeseries, breakdown, and aggregate). This allows API consumers to customize the time zone in which the date boundaries should apply for the data returned, and in the case of the timeseries endpoint, which time zone the time buckets are referring to. This parameter is optional, and the current behavior of using the site's defined time zone will be the default if this parameter is not supplied.

For more details on my use-case, see the discussion topic opened here: https://github.com/plausible/analytics/discussions/4365

Tests

• [ :heavy_check_mark: ] Automated tests have been added

Changelog

• [ :heavy_check_mark: ] Entry has been added to changelog

Documentation

• [ :heavy_check_mark: ] Docs have been updated - https://github.com/plausible/docs/pull/522

Dark mode

• [ :heavy_check_mark: ] This PR does not change the UI

[CLAassistant]

All committers have signed the CLA.

[macobo]

Hi @jon-mercer, thanks for taking the time to improve the product. I’ve taken a look at the code and it looks great!

However we internally to discussed the feature and decided not to do it for now as it could interfere with future plans like pre-calculating aggregates and we haven’t had other clients ask for this feature yet.

However this is not final - you open up a request over at https://feedback.plausible.io/ and it gets enough traction we’d be happy to build this.

Sorry for the sour note and hope you can continue using your forked version.

Related: The API you’re using is not going away, but we will be releasing a new Stats API soon (https://plausible.io/docs/stats-api-v2). I experimented with adding the same feature to it so feel free to reuse the code in your fork in the future (https://github.com/plausible/analytics/pull/4571).

[mattcameron]

Hi @macobo, we would also like this feature!

As a global business, we need to display our users' analytics in their own time zone, or the data appears incorrect to the user - which makes everyone unhappy.

I'm a big fan of Plausible and I appreciate that your team makes decisions in the best interests of all its users (and with your future plans in mind), but I wonder if there's not a middle ground here?

Perhaps pre-aggregating could still happen for the default site timezone, and requests for non-default timezones would aggregate on the fly?

It's sad to discover that the code to fix a very real issue for us has been written, but rejected because it might have future implications.

Is there any chance that this could be added to the V1 API now that V2 is out?