Get permit insights
The aggregate view of an organisation’s permit risk: permit counts by risk band, when the permits that still carry risk expire, and counts by each of the two Street Manager statuses.
Everything is computed from the permits the same filter would list, so a figure here and a page of permits under the same filter describe the same set. The filter carries the organisation and may carry any of the permit list’s other terms to narrow it.
Risk bands are evaluated at read time rather than read from each permit’s stored band. The stored band is written nightly, so a permit closed or cancelled since then would otherwise still be reported as carrying risk.
A sibling collection rather than a sub-resource of a permit, because the figures belong to the organisation rather than to any one permit. The organisation is a filter term rather than a path segment, so that everything selecting the permits travels in one parameter.
Served by a hand-written handler rather than a generated one, because the resource is computed rather than stored.
Authorizations
Session token for authentication.
Query Parameters
Selects the permits the figures are computed over. Required, because it carries the organisation.
eq(organisation,<uuid>): Required. The organisation whose permits the figures cover. Exactly one.eq(id,<uuid>)/in(id,[<uuid>,…]): filter by permit ideq(source_permit.reference,<ref>)/in(source_permit.reference,[…]): filter by the Street Manager work referencein(source_permit.status,[granted,closed,…]): filter by permit statusin(source_permit.work_status,[planned,completed,…]): filter by work statusin(risk.status,[low,medium,high,none]): filter by the permit's stored risk bandnot(…): negates the term it wraps, sonot(in(source_permit.status,[closed,cancelled]))excludes those statuses
Terms are comma separated and combine with AND. The field names are the permit
resource's own, so a nested field is dotted: source_permit.status is the state of
the permit, source_permit.work_status the state of the works. The two are
independent, and either being terminal means the permit carries no risk.
Note that risk.status filters on each permit's stored band, which is written
nightly, whereas bands in the response is evaluated at read time. Combining the
two asks for "permits whose band was X last night, banded as they are now".
assigned_to_me is not offered here. It takes its value from the caller rather
than the query, so it has no expression in this syntax; use the permits list for it.
For more information on filtering, see the docs
"eq(organisation,b951325b-d02a-43f5-ba7f-c08c62ec52e4)"
How many days ahead the expiry series should cover. Permits ending beyond it are still counted in the bands and the status counts; they just have no place on the chart.
1 <= x <= 365Response
The aggregate permit risk figures for the organisation.
JSON API response object
The aggregate view of an organisation's permit risk. A synthetic, read-only resource: it is computed from the permits the caller can see, never stored, and its identifier is the organisation the figures were computed for.
Every figure is derived from the same set of permits in the same read, so the band counts, the expiry series and the status counts always agree with each other. Risk bands are evaluated at read time rather than read from each permit's stored band, so a permit whose status changed since the nightly recalculation is banded on what it is now.