Skip to main content
GET
/
api
/
v1
/
metrics
/
aggregate
Aggregate numeric data
curl --request GET \
  --url https://data.kushiro.app/api/v1/metrics/aggregate
{
  "source": "kushiro_population_by_town",
  "group_by": "town",
  "agg": "latest",
  "buckets": [
    {
      "value": "中央町",
      "aggregated_value": 1234,
      "count": 264,
      "unit": "persons",
      "metric": "population_total",
      "period": {
        "granularity": "month",
        "start_date": "2026-04-01",
        "end_date": "2026-04-30",
        "label": "2026-04"
      }
    }
  ],
  "total": 67000,
  "truncated": false
}

Query Parameters

​
source
string
required

Source ID to query.

Minimum string length: 1
​
group_by
enum<string>
required

Aggregation axis.

Available options:
town,
age_bucket,
category,
metric,
period
​
agg
enum<string>
default:latest

Aggregation function. latest returns the value of the most recent period within each bucket; delta returns (latest - previous) and adds previous_value / previous_period / delta_pct to each bucket.

Available options:
sum,
avg,
min,
max,
latest,
delta
​
order
enum<string>
default:desc

Sort direction for aggregated_value. desc returns the top N.

Available options:
asc,
desc
​
metric
string[]

Pre-filter by metric name (exact). Repeat the parameter to match any of several metrics. Takes precedence over metric_prefix.

Maximum array length: 20
Minimum string length: 1
​
metric_prefix
string

Pre-filter by metric name prefix. Ignored when metric is also supplied.

Minimum string length: 1
​
from
string

Inclusive lower bound for period.start_date in YYYY-MM-DD format.

Pattern: ^\d{4}-\d{2}-\d{2}$
Example:

"2026-04-01"

​
to
string

Inclusive upper bound for period.end_date in YYYY-MM-DD format.

Pattern: ^\d{4}-\d{2}-\d{2}$
Example:

"2026-04-01"

​
town
string

Pre-filter by exact town name.

Minimum string length: 1
​
age
string

Pre-filter by exact age label.

Minimum string length: 1
​
category_kind
string

Pre-filter by dim_category.kind.

Minimum string length: 1
​
category_code
string

Pre-filter by dim_category.code.

Minimum string length: 1
​
limit
integer
default:100

Maximum number of buckets to return. Defaults to 100.

Required range: 1 <= x <= 1000

Response

Metric aggregation result.

​
source
string
required
​
group_by
string
required
​
agg
string
required
​
buckets
object[]
required
​
total
integer
required

Total matching rows after filtering, before aggregation.

Required range: x >= 0
​
truncated
boolean
required

True when bucket cardinality exceeded limit.