Skip to content

Analytics responses

Typed shapes for /api/analytics (aggregated + raw) responses.

See also

  • Analytics streaming — AnalyticsAccessor on Dhis2Client.analytics covers the streaming /api/analytics* surface (pivots, events, enrollments, outliers) plus the simple query(...) call over the standard aggregate endpoint.
  • Visualizations + dashboards — every saved Visualization is an analytics query with a chart type + axis placement attached. Start from an analytics query you've verified, then wrap it in a VisualizationSpec to persist.
  • Visualizations walkthrough — end-to-end guide showing how to go from a client.analytics.query(...) result to a saved chart + a dashboard slot.

analytics

Typed models for DHIS2 /api/analytics* query responses.

Re-exports the OAS-emitted Grid / GridHeader models as the canonical types for every /api/analytics* response (standard / raw / events / enrollments / outlier / tracked-entity — they all share the Grid envelope). AnalyticsMetaData is a typed parser helper: DHIS2's Grid.metaData is dict[str, Any] on the wire (dimension lookups + item descriptors keyed by UID), and callers that want the structured {items, dimensions} view use AnalyticsMetaData.model_validate(grid.metaData) to lift the raw dict into a typed model.

Classes

Grid

Bases: BaseModel

OpenAPI schema Grid.

Source code in packages/dhis2w-client/src/dhis2w_client/generated/v42/oas/grid.py 
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
class Grid(_BaseModel):
    """OpenAPI schema `Grid`."""

    model_config = _ConfigDict(extra="allow", populate_by_name=True, defer_build=True)

    headerWidth: int | None = None
    headers: list[GridHeader] | None = None
    height: int | None = None
    internalMetaData: dict[str, Object] | None = None
    lastDataRow: bool | None = None
    metaColumnIndexes: list[int] | None = None
    metaData: dict[str, Object] | None = None
    metadataHeaders: list[GridHeader] | None = None
    performanceMetrics: PerformanceMetrics | None = None
    refs: list[Reference] | None = None
    rowContext: dict[str, dict[str, Object]] | None = _Field(
        default=None, description="keys are class java.lang.Integer"
    )
    rows: list[list[Object]] | None = None
    subtitle: str | None = None
    table: str | None = None
    title: str | None = None
    visibleHeaders: list[GridHeader] | None = None
    visibleRows: list[list[Object]] | None = None
    visibleWidth: int | None = None
    width: int | None = None

GridHeader

Bases: BaseModel

OpenAPI schema GridHeader.

Source code in packages/dhis2w-client/src/dhis2w_client/generated/v42/oas/grid_header.py 
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
class GridHeader(_BaseModel):
    """OpenAPI schema `GridHeader`."""

    model_config = _ConfigDict(extra="allow", populate_by_name=True, defer_build=True)

    column: str | None = None
    hidden: bool | None = None
    legendSet: str | None = None
    meta: bool | None = None
    name: str | None = None
    optionSet: str | None = None
    programStage: str | None = None
    repeatableStageParams: str | None = None
    stageOffset: int | None = None
    type: str | None = None
    valueType: ValueType | None = None

AnalyticsMetaData

Bases: BaseModel

Typed view over Grid.metaData — dimension lookups + item descriptors.

DHIS2 returns metaData as a bare JSON object with two stable sub-keys (items and dimensions) plus freeform extras that vary by request. This helper parses the raw dict into those typed fields; callers lift a Grid.metaData dict via AnalyticsMetaData.model_validate(grid.metaData) when they want to walk dimensions["dx"] / look up items[<uid>].name / etc. without writing their own dict-walking.

Source code in packages/dhis2w-client/src/dhis2w_client/analytics.py 
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
class AnalyticsMetaData(BaseModel):
    """Typed view over `Grid.metaData` — dimension lookups + item descriptors.

    DHIS2 returns `metaData` as a bare JSON object with two stable sub-keys
    (`items` and `dimensions`) plus freeform extras that vary by request.
    This helper parses the raw dict into those typed fields; callers lift
    a `Grid.metaData` dict via `AnalyticsMetaData.model_validate(grid.metaData)`
    when they want to walk `dimensions["dx"]` / look up `items[<uid>].name`
    / etc. without writing their own dict-walking.
    """

    model_config = ConfigDict(extra="allow")

    items: dict[str, Any] = Field(default_factory=dict)
    dimensions: dict[str, list[str]] = Field(default_factory=dict)