[Feature] Stats API endpoint

[alexjustesen]

📃 Description

This PR introduces a new /api/v1/stats endpoint that summaries ping, download and upload data.

# all time
curl localhost/api/v1/stats
   -H "Accept: application/json"
   -H "Authorization: Bearer yourtokengoeshere"

By default this endpoint returns "all time" stats butyou can filter these stats by providing a start_at or end_at filter.

# this year
curl localhost/api/v1/stats?filter[start_at]>=2025-01-01
   -H "Accept: application/json"
   -H "Authorization: Bearer yourtokengoeshere"

# between dates
curl localhost/api/v1/stats?filter[start_at]>=2024-01-01&filter[end_at]<=2024-12-31
   -H "Accept: application/json"
   -H "Authorization: Bearer yourtokengoeshere"

🪵 Changelog

➕ Added

• /api/v1/stats endpoint

✏️ Changed

• round return from bytesToBits helper method

👀 Data Dictionary

{
  "data": {
    "ping": {
      "avg": 7.44,
      "min": 6.94,
      "max": 9.41
    },
    "download": {
      "avg": 116652966,
      "avg_bits": 933223730,
      "avg_bits_human": "933.22 Mbps",
      "min": 92564306,
      "min_bits": 740514448,
      "min_bits_human": "740.51 Mbps",
      "max": 117845746,
      "max_bits": 942765968,
      "max_bits_human": "942.77 Mbps"
    },
    "upload": {
      "avg": 115043634,
      "avg_bits": 920349075,
      "avg_bits_human": "920.35 Mbps",
      "min": 96649510,
      "min_bits": 773196080,
      "min_bits_human": "773.20 Mbps",
      "max": 116693460,
      "max_bits": 933547680,
      "max_bits_human": "933.55 Mbps"
    },
    "total_results": 238
  },
  "filters": {
    "start_at": ">=2025-01-01",
    "end_at": "<=2025-01-16"
  },
  "message": "ok"
}

[luckman212]

This is a nice addition! Right now I'm doing my own averaging using jq on the /results endpoint with a filter for the last 12 results (which is 2 days in my setup with tests running every 4 hours)

I'd love to switch to the simpler /stats endpoint but, is there any way to constrain the time period or number of results that go into the calculations?

[alexjustesen]

I'd love to switch to the simpler /stats endpoint but, is there any way to constrain the time period or number of results that go into the calculations?

Docs needs to be updated but you can use the same filters as /results endpoint:

curl localhost/api/v1/stats?filter[start_at]>=2024-01-01&filter[end_at]<=2024-12-31
   -H "Accept: application/json"
   -H "Authorization: Bearer yourtokengoeshere"

[luckman212]

Thanks @alexjustesen

But, when I tried that, I only get all 0 for metrics:

curl --get \
  --data 'filter[start_at]>=2025-01-15' \
  --data 'filter[end_at]<=2025-01-20' \
  --header "Authorization: Bearer xxxxxxxxxx" \
  --header "Accept: application/json" \
  https://my.speedtest.server/api/v1/stats

{
  "data": {
    "ping": {
      "avg": 0,
      "min": 0,
      "max": 0
    },
    "download": {
      "avg": 0,
      "min": 0,
      "max": 0
    },
    "upload": {
      "avg": 0,
      "min": 0,
      "max": 0
    },
    "total_results": 0
  },
  "filters": {
    "start_at": "2025-01-15",
    "end_at": "2025-01-20"
  },
  "message": "ok"
}

Without any filters:

{
  "data": {
    "ping": {
      "avg": 5.98,
      "min": 3.59,
      "max": 33.35
    },
    "download": {
      "avg": 100316192,
      "avg_bits": 802529537,
      "avg_bits_human": "802.53 Mbps",
      "min": 3870203,
      "min_bits": 30961624,
      "min_bits_human": "30.96 Mbps",
      "max": 103669279,
      "max_bits": 829354232,
      "max_bits_human": "829.35 Mbps"
    },
    "upload": {
      "avg": 96025115,
      "avg_bits": 768200923,
      "avg_bits_human": "768.20 Mbps",
      "min": 2628006,
      "min_bits": 21024048,
      "min_bits_human": "21.02 Mbps",
      "max": 103481861,
      "max_bits": 827854888,
      "max_bits_human": "827.85 Mbps"
    },
    "total_results": 544
  },
  "message": "ok"
}