--- title: "Download the statistics page's KPIs as rows of metric, period, dimension and value" method: GET path: "/feed/kpis" tags: ["BI feeds"] --- # Download the statistics page's KPIs as rows of metric, period, dimension and value `GET /feed/kpis` ## Request - Base URL: `https://trackberry.com/api/v1` - URL: `https://trackberry.com/api/v1/feed/kpis` - Auth: HTTP bearer Use this to chart the same KPIs the Statistics page shows, without rebuilding them: shipments per month, by carrier, lane and country, arrival punctuality, port dwell percentiles, on-time percentage, CO2 and produce. Metrics, with the dimension each one uses: `shipments_created` (monthly, `transport_type`: ocean or air); `shipments_by_carrier` (`carrier`), `shipments_by_lane` (`lane`), `shipments_by_origin_country` and `shipments_by_destination_country` (the country): shipments in the window; `arrivals_on_time`, `arrivals_late_up_to_5_days` and `arrivals_late_over_5_days` (by `carrier` and by `lane`): arrivals against the original ETA; `port_dwell_median_days`, `port_dwell_p10_days`, `port_dwell_p90_days`, `port_dwell_q1_days`, `port_dwell_q3_days` and `port_dwell_containers` (`destination_port`): days containers sit in the destination port; `on_time_arrival_pct` and `arrivals_measured` (monthly, no dimension); `co2_tonnes` (monthly, no dimension); `shipments_by_produce` (monthly, `produce`); `shipments_by_supplier` (monthly, `supplier`); `incidents` (monthly, `incident_type`: delay, rollover, free_time_breach, document_error or customs_hold, unit `incidents`); and for each of `carrier`, `forwarder` and `supplier`, over the window, `incidents_by_` (unit `incidents`), `shipments_with_incidents_by_` (unit `shipments`) and `incident_rate_by_` (unit `per_100_shipments`). Incidents are derived from delays, rollovers, free time breaches, document corrections and customs holds, counted in the month their shipment was created. Ranked metrics keep their top entries as the page does (10 carriers, 10 lanes, 10 ports, 8 produce, 8 suppliers, 10 carriers, forwarders and suppliers by incidents); use the shipments feed for the full list. Append `.csv` or `.json`. Every period is the month a shipment was created in, not the month it sailed or arrived, and the figures include archived and orphaned shipments, exactly as the Statistics page does. ## Query parameters - `from` string ## Headers - `Trackberry-Version` string ## Response `200` The whole table. Append `.csv` to the path for CSV, `.json` or nothing for JSON. - object - `object` 'feed', required: Always `feed`. - `name` 'kpis', required: Which feed this is. - `columns` string[], required: The column names, in order. Stable across requests. - `data` KpiFeedRow[], required: One flat object per row, keyed by the column names. - `metric` string, required: The measure. See the list of metrics in the endpoint description. - `period_start` string, date, required: First day of the period. For monthly metrics the first day of the month; for ranked metrics the first day of the first month in the window. - `period_end` string, date, required: Last day of the period. For monthly metrics the last day of the month; for ranked metrics today. - `dimension` string, nullable, required: What `dimension_value` names: `transport_type`, `carrier`, `lane`, `origin_country`, `destination_country`, `destination_port`, `produce`, `supplier`, `forwarder` or `incident_type`. Null for totals. - `dimension_value` string, nullable, required: The carrier, lane (`Valencia > Rotterdam`), country, port, produce, supplier, forwarder or incident type (`delay`, `rollover`, `free_time_breach`, `document_error`, `customs_hold`) this row is about. Null for totals. - `value` number, nullable, required: The number. Null when it cannot be computed, such as an on-time percentage for a month with no arrivals. - `unit` 'shipments' | 'containers' | 'days' | 'percent' | 'tonnes' | 'incidents' | 'per_100_shipments', required: What `value` counts. ## Other responses - `400`: A parameter or header is invalid (`invalid_parameter`, with `param` naming it), a customer link cannot be made for this shipment (`not_shareable`), an uploaded file is empty, over 50 MB or of a type Trackberry does not read (`file_empty`, `file_too_large`, `unsupported_file_type`), an upload's container number is on more than one live shipment (`ambiguous_container`), an `Idempotency-Key` was already used for a different request (`idempotency_key_reused`) or `Trackberry-Version` names an unpublished version (`invalid_version`, with `param` set to `Trackberry-Version`). A parameter that must be a single value but was sent as an array or hash (`status[]=x`, `q[a]=1`) is also a 400. - `401`: No token was sent (`missing_token`) or the token is wrong, expired, revoked, or its user left the organization (`invalid_token`). The response has a `WWW-Authenticate` header. - `403`: The token may not do this. `insufficient_scope`: a write endpoint was called with a read-only token. `read_only_member`: a write endpoint was called by a token whose owner is now a read-only member of the organization. `revoke_not_allowed`: the link can only be revoked by an admin or by the member who made it. `billing_blocked`: an upload needed a new shipment and the organization's billing does not allow one. - `429`: A rate limit was hit (`rate_limited`). Wait the number of seconds in `Retry-After`. A BI feed answers the same way (`feed_in_progress`) when another feed for the organization is still being produced. --- [API](https://skmtc.dev/trackberry/apis/trackberry-api.md) · [All operations](https://skmtc.dev/trackberry/apis/trackberry-api/llms.txt) · [OpenAPI document](https://skmtc.dev/trackberry/apis/trackberry-api/revisions/be06ee7c17f3?raw)