The lens
The as-of date, data revision, window and filters that fix every read, with their formats, defaults and limits.
Every read model is a projection of one lens: an as-of date, a data revision, a lookback window and visibility filters. Lens-scoped operations accept the lens as query parameters, and their OpenAPI entries list them.
Parameters
| Parameter | Format | Default |
|---|---|---|
asOf | YYYY-MM-DD, from the first data date of the revision to today | The server's current UTC date |
revision | Positive integer, at most the current revision | The current revision |
window | Integer days from 7 to 1830 | 180 |
theme | Theme ID; repeatable, up to 6 | None |
region | Region ID; repeatable, up to 9 | None |
actor | Actor ID; repeatable, up to 50 | None |
Repeat a filter to select several values, such as region=mena®ion=europe. GET /meta lists every theme, region and actor ID, the defaults, and the accepted as-of dates as limits.asOf.
The as-of date
asOf is the date a read is computed for. Nothing dated after it is used, and no statistic released after it is used, even when the statistic describes an earlier period. A read as of a past date therefore sees what was known on that date.
An asOf after today, or before the first day on which any record of the revision is dated, is refused with 400 invalid-request. Keep dates within limits.asOf from GET /meta.
The revision
revision pins the data revision, the set of records the platform held after a given change. A revision above the current one answers 404 not-found. Pass both asOf and revision to make a read reproducible; with neither, a read uses the latest data as of today. See Reproducibility.
The window
The window is a lookback in days, not a filter of the assessment. It selects the reports, and so the developments, a read model shows, and it is the period over which indicator changes and deviations are computed.
Filters
Themes, regions and actors decide which objects a read model shows. They never change a number: assessments depend only on the data revision and the as-of date, and relative measures such as index ranks are always computed over the whole universe. A dossier ignores the visibility filters and always describes its whole actor.
Equivalent lenses
The canonical form of a lens omits defaults and sorts repeated values, so equivalent lenses share one query string, one URL and one cache entry. Build query strings the same way to reuse cached responses.
Read every ID from GET /meta rather than storing them in code. The vocabularies are versioned with the platform, and a theme or region outside them is refused with 400 invalid-request.