Analytics
APEX's 18 analytics endpoints for market intelligence, corridor analysis, pricing, data-quality alerts, time series, and strategic insight. Shared query parameters, period semantics anchored to the newest data, and a price sanity filter.
APEX provides 18 analytics endpoints for market intelligence, corridor analysis, and
strategic insight. All are GET /api/v1/analytics/* and require an
X-API-Key.
Common parameters
Most analytics endpoints accept:
| Parameter | Type | Default | Description |
|---|---|---|---|
period | string | 90d | Time window: 30d, 90d, 180d (any <N>d), or all. |
period_days | number | — | Plain day count — takes precedence over period=<N>d. |
shipment_type | string | FTL | Shipment-type filter. |
min_quality | number | 0 | Minimum data-quality threshold (0.0–1.0). |
limit | number | 20 | Maximum results returned. |
period requires the d suffix — period=30 (without d) silently falls back to the 90-day
default. Use period=30d or period_days=30.
Period semantics
All time windows are anchored to the newest observation in the database, not the wall
clock. So period=30d means "the 30 days up to the latest ingested data" — relative periods
keep working even when ingestion is delayed, and results don't slowly empty out between syncs.
Price sanity filter
Analytics aggregates exclude implausible rates: only price_per_km between 0.5 and 5.0
EUR/km enters averages and percentiles. Rows with no price still count toward offer and
volume totals.
Market & geographic
Market overview — GET /analytics/market/overview
Country-pair freight flows with trend data. Extra parameter: sort_by (default orders).
{
"routes": [
{
"loading_country": "DE",
"unloading_country": "PL",
"route_name": "DE → PL",
"total_offers": 15234,
"priced_offers": 12891,
"avg_price_per_km": 1.42,
"turnover_eur": 18500000,
"avg_distance_km": 720,
"price_trend_pct": -2.3,
"price_quality": "HIGH"
}
],
"period": "30d",
"sort_by": "orders"
}price_quality: HIGH (≥80% priced offers), MEDIUM (40–80%), LOW (under 40%).
Overview — GET /analytics/overview
Global KPIs: total observations and average EUR/km, filtered by period and shipment type.
Geographic heatmap — GET /analytics/geographic/heatmap
Geo-coordinates for map visualization. Extra parameters: direction (loading or
unloading), metric (default avg_price_per_km).
Corridor analysis
Rankings — GET /analytics/corridors/rankings
Rank corridors by volume, price, or volatility.
Corridor trends — GET /analytics/corridors/:id/trends
Daily price trends (avg/median/p25/p75/min/max per day) plus a period summary and trend direction for one corridor.
Corridor statistics — GET /analytics/corridors/:id/statistics
Statistical summary (mean, median, percentiles, volatility) for one corridor.
Pricing & equipment
Price bands — GET /analytics/price-bands
Price-distribution bands across the market.
Equipment type comparison — GET /analytics/equipment-types/comparison
Compare pricing by equipment type. Extra parameter: corridor_id.
Shipment type comparison — GET /analytics/shipment-types/comparison
Compare FTL against other shipment types.
Data quality & alerts
Source quality — GET /analytics/sources/quality
Data-quality metrics broken down by month and data source.
Price movement alerts — GET /analytics/alerts/price-movements
Corridors with a >10% price change in the current period.
Stale data alerts — GET /analytics/alerts/stale-data
Corridors where data hasn't updated in 72+ hours.
Time series & rankings
Quarterly statistics — GET /analytics/quarterly
Quarterly aggregates and quarter-over-quarter trends.
Country rankings — GET /analytics/countries
Rank countries by loading or unloading activity.
Location rankings — GET /analytics/locations
Rank cities by freight activity.
Strategic analysis
Route flows — GET /analytics/routes/flows
Freight-flow patterns across routes — volume, direction, seasonal patterns.
Route comparison — GET /analytics/routes/comparison
Compare routes side by side by orders, revenue, distance, or other metrics.
Regional imbalance — GET /analytics/regions/imbalance
Supply/demand imbalances by region — useful for finding repositioning opportunities.
Empty arrays mean nothing matched the filters — widen the period (or use period=all), lower
min_quality, or drop shipment_type. See Errors.
Corridors
GET /corridors lists every known directed corridor. It is a bulk, unpaginated export of the full inventory — treat it as a download and cache it, not a browsing API.
Errors
The APEX error catalog — a consistent JSON envelope with a stable machine-readable code, the full list of estimation and admin codes, the responses that look like errors but aren't, and retry guidance.