Docs
The lens

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

ParameterFormatDefault
asOfYYYY-MM-DD, from the first data date of the revision to todayThe server's current UTC date
revisionPositive integer, at most the current revisionThe current revision
windowInteger days from 7 to 1830180
themeTheme ID; repeatable, up to 6None
regionRegion ID; repeatable, up to 9None
actorActor ID; repeatable, up to 50None

Repeat a filter to select several values, such as region=mena&region=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.