Statistics API: aggregated BLE zone and people counts

The statistics routes compute aggregated people-count metrics directly from the detections table. All calculations use the StatisticsService, which estimates the number of people present by dividing unique BLE device counts by the DEVICES_PER_PERSON ratio (default 1.5, configurable via the DEVICES_PER_PERSON environment variable). Times are handled in the Europe/Madrid timezone unless an explicit ISO timestamp with offset is provided. All endpoints are mounted under /api/v1/statistics.

GET /api/v1/statistics/realtime

Return aggregated statistics for the most recent N minutes. This is the endpoint used by the dashboard for live occupancy display. Query parameters

minutes

number

default:"5"

Width of the time window in minutes. Must be between 1 and 10080 (7 days).

device_id

string

Restrict results to detections recorded by a specific Raspberry Pi node. Omit to aggregate across all devices.

Response

timestamp

string

ISO 8601 server time when the query was executed.

time_window_minutes

number

The minutes value that was applied.

by_zone

object

Per-zone breakdown. Keys are zone names (near, medium, far). Only zones with at least one detection in the window appear.

Show zone object properties

unique_devices

number

Distinct BLE device hashes detected in this zone during the window.

total_detections

number

Total number of detection records in this zone during the window.

estimated_people

number

People estimate for this zone.

avg_rssi

number

Average RSSI in dBm for detections in this zone, rounded to 2 decimal places. null if no detections.

total

object

Totals across all zones.

Show total object properties

unique_devices

number

Total distinct device hashes across all zones.

total_detections

number

Total detection records across all zones.

estimated_people

number

Overall people estimate.

# Stats for the last 10 minutes from device pi-entrance-01
curl "http://localhost:8000/api/v1/statistics/realtime?minutes=10&device_id=pi-entrance-01"

{
  "timestamp": "2026-05-15T10:30:00+02:00",
  "time_window_minutes": 10,
  "by_zone": {
    "near": {
      "unique_devices": 12,
      "total_detections": 58,
      "estimated_people": 8,
      "avg_rssi": -62.4
    },
    "medium": {
      "unique_devices": 7,
      "total_detections": 29,
      "estimated_people": 5,
      "avg_rssi": -73.1
    }
  },
  "total": {
    "unique_devices": 19,
    "total_detections": 87,
    "estimated_people": 13
  }
}

GET /api/v1/statistics/range

Return aggregated statistics for an arbitrary time window defined by explicit start and end timestamps. Useful for historical analysis or exporting a specific period. Query parameters

start_time

string

required

Start of the time range in ISO 8601 format, e.g. 2026-04-23T10:00:00. A timezone offset (+02:00 or Z) is accepted and recommended; if omitted the server treats the value as Europe/Madrid local time.

end_time

string

required

End of the time range in ISO 8601 format. Must be later than start_time; otherwise the server returns HTTP 400.

device_id

string

Restrict results to a specific Raspberry Pi node.

Response Same structure as /realtime — a top-level timestamp, start_time, end_time, by_zone map, and total summary.

If start_time is equal to or later than end_time, the server returns HTTP 400 with the message "La fecha de inicio debe ser anterior a la fecha de fin".

curl "http://localhost:8000/api/v1/statistics/range?start_time=2026-05-15T08:00:00&end_time=2026-05-15T12:00:00"

{
  "timestamp": "2026-05-15T10:30:00+02:00",
  "start_time": "2026-05-15T08:00:00+02:00",
  "end_time": "2026-05-15T12:00:00+02:00",
  "by_zone": {
    "near": {
      "unique_devices": 34,
      "total_detections": 201,
      "estimated_people": 23,
      "avg_rssi": -61.8
    }
  },
  "total": {
    "unique_devices": 34,
    "total_detections": 201,
    "estimated_people": 23,
    "avg_rssi": null
  }
}

GET /api/v1/statistics/hourly

Return per-hour, per-zone statistics for a single calendar day. Results are grouped by truncated hour and ordered chronologically. Query parameters

date

string

Target date in ISO 8601 date format, e.g. 2026-05-15. If omitted, the current date in the Europe/Madrid timezone is used.

Response

date

string

The date that was queried, in YYYY-MM-DD format.

statistics

object[]

Array of per-hour, per-zone stat objects. Each element covers one (hour, zone) combination.

Show statistics array element

period_type

string

Always "hour" for this endpoint.

period_start

string

ISO 8601 timestamp of the start of the hour bucket.

zone

string

Zone name: near, medium, or far.

unique_devices

number

Distinct device hashes in this hour/zone bucket.

total_detections

number

Total detection records in this hour/zone bucket.

estimated_people

number

People estimate for this bucket.

avg_rssi

number

Average RSSI rounded to 2 decimal places, or null.

curl "http://localhost:8000/api/v1/statistics/hourly?date=2026-05-15"

{
  "date": "2026-05-15",
  "statistics": [
    {
      "period_type": "hour",
      "period_start": "2026-05-15T09:00:00+02:00",
      "zone": "near",
      "unique_devices": 8,
      "total_detections": 41,
      "estimated_people": 5,
      "avg_rssi": -63.2
    },
    {
      "period_type": "hour",
      "period_start": "2026-05-15T09:00:00+02:00",
      "zone": "medium",
      "unique_devices": 4,
      "total_detections": 17,
      "estimated_people": 3,
      "avg_rssi": -74.5
    }
  ]
}

GET /api/v1/statistics/daily

Return per-day, per-zone statistics for a date range. When neither start_date nor end_date is provided, the endpoint defaults to the last days days ending today. Query parameters

start_date

string

Start date in ISO 8601 format, e.g. 2026-05-01. When omitted, computed as end_date - days.

end_date

string

End date in ISO 8601 format. When omitted, defaults to today in the Europe/Madrid timezone.

days

number

default:"7"

Number of days to look back when start_date is not supplied.

Response

start_date

string

Effective start date in YYYY-MM-DD format.

end_date

string

Effective end date in YYYY-MM-DD format.

statistics

object[]

Array of per-day, per-zone stat objects. Each element has the same shape as the hourly statistics array element, but with period_type set to "day" and period_start truncated to midnight.

# Last 14 days
curl "http://localhost:8000/api/v1/statistics/daily?days=14"

# Explicit date range
curl "http://localhost:8000/api/v1/statistics/daily?start_date=2026-05-01&end_date=2026-05-15"

{
  "start_date": "2026-05-01",
  "end_date": "2026-05-15",
  "statistics": [
    {
      "period_type": "day",
      "period_start": "2026-05-01T00:00:00+02:00",
      "zone": "near",
      "unique_devices": 120,
      "total_detections": 853,
      "estimated_people": 80,
      "avg_rssi": -62.1
    }
  ]
}

GET /api/v1/statistics/distribution

Return the share of total detections that each proximity zone accounts for over the last N hours. Useful for visualising how foot traffic distributes across near, medium, and far ranges. Query parameters

hours

number

default:"24"

Number of hours to look back from the current time.

Response

start_time

string

ISO 8601 start of the analysis window.

end_time

string

ISO 8601 end of the analysis window.

total

number

Total detection records across all zones in the window.

distribution

object

Per-zone counts and percentages. Keys are zone names (near, medium, far).

Show zone distribution properties

count

number

Number of detection records in this zone.

percentage

number

Fraction of total detections, as a percentage rounded to 2 decimal places.

curl "http://localhost:8000/api/v1/statistics/distribution?hours=48"

{
  "start_time": "2026-05-13T10:30:00+02:00",
  "end_time": "2026-05-15T10:30:00+02:00",
  "total": 1240,
  "distribution": {
    "near": {"count": 496, "percentage": 40.0},
    "medium": {"count": 434, "percentage": 35.0},
    "far": {"count": 310, "percentage": 25.0}
  }
}

Overview

Endpoints

Real-Time

Statistics API: aggregated BLE zone and people counts

GET /api/v1/statistics/realtime

GET /api/v1/statistics/range

GET /api/v1/statistics/hourly

GET /api/v1/statistics/daily

GET /api/v1/statistics/distribution

Build docs developers (and LLMs) love

Overview

Endpoints

Real-Time

Documentation Index

​GET /api/v1/statistics/realtime

​GET /api/v1/statistics/range

​GET /api/v1/statistics/hourly

​GET /api/v1/statistics/daily

​GET /api/v1/statistics/distribution

Build docs developers (and LLMs) love

GET /api/v1/statistics/realtime

GET /api/v1/statistics/range

GET /api/v1/statistics/hourly

GET /api/v1/statistics/daily

GET /api/v1/statistics/distribution