Get a performance metric for a location

get

https://demo.vizionapi.com/performance/location/{namespace}/{code}/metric/{metric}

Returns one performance metric for one location over a date range, scoped to your organization.

Supported namespaces are unlocode, country, continent, region, and smdg. Supported metrics are import_dwell, export_dwell, berth_time, arrival_to_berth, import_teu, export_teu, and average_delay; unit in the response is teu for the two TEU metrics and days for the rest.

An empty data[] means there was no measurement for this location and metric in the requested window — it is not an error. Coverage reflects locations with observed activity in the requested window and is not a fixed list.

Terminal locations (the smdg namespace) are not supported and return a 422 with code: "unsupported_location_type". Depot and rail locations are not addressable through this endpoint at all. Industry benchmark comparisons are not currently exposed by this endpoint.

A 403 is returned when Performance is not enabled for your organization. A 404 is returned for an unknown namespace (code: "unknown_namespace") or an unknown location code (code: "unknown_location"). A 422 is returned for an unknown metric (code: "unknown_metric"), an unsupported location type (code: "unsupported_location_type"), an unknown grain (code: "unknown_grain"), an unknown compare (code: "unknown_comparison"), the prior_year + grain pairing (code: "unsupported_comparison_combination"), or a query parameter that fails validation. Switch on code rather than on the message text — the two 404 cases are distinguishable only by it.

start and end are both required and there is no cap on how far apart they may be. Without grain, a very wide window does not return more rows — it returns the same single row over a longer period — but it does take longer to compute, and may time out.

Rows in data[] are ordered by period_start ascending, then by value descending, and paginated with page and limit — 25 per page by default. Pass include_metadata=true for the metadata envelope carrying item_count, the total across all pages.

is_partial on a row means the period had not fully elapsed when the figure was computed, so it rests on fewer days than the period length. With grain it can only be the last row of a series: the leading bucket is not returned at all, so a series always begins with a whole period. Without grain it is always false.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Path Params

namespace

string

enum

required

Allowed:

code

string

required

metric

string

enum

required

Allowed:

Query Params

start

date

required

Start of the date range (inclusive).

end

date

required

End of the date range (inclusive).

grain

string

enum

Bucket the result into a period series instead of a single figure. Omit for one row spanning the whole range.

Buckets are aligned to calendar weeks and months, so start will usually fall partway through one. The series begins at the first whole period instead — start=2026-04-01 with grain=week gives a first row of 2026-04-06, not the 2026-03-30 week that date falls inside. Up to six days at the front (or a month at grain=month) are not represented by a row. If your whole window fits inside one such bucket, nothing is left — a three-day window at grain=week returns an empty data[]. Drop grain to get a single figure over exactly the range you asked for.

The end behaves differently: the final row is returned even when its calendar period runs past end, flagged is_partial: true. Its label therefore covers more than its value does, so clamp that one label to your own end if you are plotting a time axis.

The series is the same length regardless of which other optional parameters you pass.

Allowed:

compare

string

enum

Add a comparison_value to each row. prior_period compares each row to the row before it. prior_year compares the whole range to the same range a year earlier.

Adding compare does not change which rows come back — a series has the same length and start with or without it, so the two line up row-for-row.

prior_year cannot be combined with grain — that pairing returns a 422 with code: "unsupported_comparison_combination". Use prior_year on its own for a single year-over-year figure, or prior_period with grain for a period-over-period series.

Allowed:

page

integer

≥ 1

Defaults to 1

Which page of data[] to return. A page past the end returns an empty data[] rather than an error.

limit

integer

1 to 500

Defaults to 25

Rows per page. Defaults to 25 and is capped at 500.

Note this applies to data[] only. Without grain there is a single row, so paging is only meaningful once you bucket the result.

include_metadata

boolean

Defaults to false

Include the pagination envelope in the response. When false (the default) metadata is omitted entirely. See pagination.

Responses

200A performance metric for one location

4XXInvalid request