HIV VL - Summary

System-wide summary and dashboard endpoints for HIV Viral Load (VL) analytics. These endpoints provide aggregated indicators, viral suppression trends, turnaround times, and provincial breakdowns across all facilities.

Common parameters

Most summary endpoints accept a common set of query parameters for filtering data by date range, geographic location, and facility attributes.

Name
interval_dates
Type
JSON array
Description
Date range filter as a JSON array with two dates in YYYY-MM-DD format: ["2025-01-01","2025-12-31"]. Defaults to the last 12 months if not provided.
Name
province
Type
string
Description
Filter by province name. Supports multi-select by passing the parameter multiple times.
Name
district
Type
string
Description
Filter by district name. Supports multi-select by passing the parameter multiple times.
Name
health_facility
Type
string
Description
Filter by a specific health facility name.
Name
facility_type
Type
string
Description
Grouping level for aggregated results. Accepted values: "province", "district", "health_facility".
Name
disaggregation
Type
string
Description
Enable or disable data disaggregation. Accepted values: "True" or "False".

Request with parameters

GET

/hiv/vl/summary/header_indicators/

curl -G https://api.openldr.org.mz/hiv/vl/summary/header_indicators/ \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  --data-urlencode 'interval_dates=["2025-01-01","2025-12-31"]' \
  --data-urlencode "province=Maputo Cidade" \
  --data-urlencode "district=KaMpfumo" \
  --data-urlencode "facility_type=district" \
  --data-urlencode "disaggregation=True"

GET/hiv/vl/summary/header_indicators/

Header indicators

Returns a single object with the main VL indicators for the selected period, including total registered, tested, suppressed, not suppressed, and rejected sample counts.

Name
registered
Type
integer
Description
Total number of samples registered in the system.
Name
tested
Type
integer
Description
Total number of samples that have been tested.
Name
suppressed
Type
integer
Description
Total number of samples with a suppressed viral load result.
Name
not_suppressed
Type
integer
Description
Total number of samples with a not suppressed viral load result.
Name
rejected
Type
integer
Description
Total number of samples that were rejected.

Request

GET

/hiv/vl/summary/header_indicators/

curl -G https://api.openldr.org.mz/hiv/vl/summary/header_indicators/ \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  --data-urlencode 'interval_dates=["2025-01-01","2025-12-31"]'

Response

{
  "registered": 185420,
  "tested": 172350,
  "suppressed": 148920,
  "not_suppressed": 23430,
  "rejected": 7840
}

GET/hiv/vl/summary/number_of_samples/

Number of samples

Returns an array of monthly sample counts, providing a time-series view of total samples processed.

Name
year
Type
integer
Description
The year of the record.
Name
month
Type
integer
Description
The month number (1-12).
Name
month_name
Type
string
Description
The name of the month.
Name
total
Type
integer
Description
Total number of samples in the month.

Request

GET

/hiv/vl/summary/number_of_samples/

curl -G https://api.openldr.org.mz/hiv/vl/summary/number_of_samples/ \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  --data-urlencode 'interval_dates=["2025-01-01","2025-12-31"]'

Response

[
  {
    "year": 2025,
    "month": 1,
    "month_name": "January",
    "total": 15840
  },
  {
    "year": 2025,
    "month": 2,
    "month_name": "February",
    "total": 14920
  }
]

GET/hiv/vl/summary/viral_suppression/

Viral suppression

Returns an array of monthly viral suppression data, showing the breakdown of suppressed and not suppressed results over time.

Name
year
Type
integer
Description
The year of the record.
Name
month
Type
integer
Description
The month number (1-12).
Name
month_name
Type
string
Description
The name of the month.
Name
suppressed
Type
integer
Description
Number of suppressed results in the month.
Name
not_suppressed
Type
integer
Description
Number of not suppressed results in the month.

Request

GET

/hiv/vl/summary/viral_suppression/

curl -G https://api.openldr.org.mz/hiv/vl/summary/viral_suppression/ \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  --data-urlencode 'interval_dates=["2025-01-01","2025-12-31"]'

Response

[
  {
    "year": 2025,
    "month": 1,
    "month_name": "January",
    "suppressed": 12450,
    "not_suppressed": 1980
  },
  {
    "year": 2025,
    "month": 2,
    "month_name": "February",
    "suppressed": 11870,
    "not_suppressed": 1840
  }
]

GET/hiv/vl/summary/tat/

TAT

Returns an array of monthly turnaround time (TAT) averages broken down by each stage of the sample processing pipeline, from collection through validation.

Name
year
Type
integer
Description
The year of the record.
Name
month
Type
integer
Description
The month number (1-12).
Name
month_name
Type
string
Description
The name of the month.
Name
collection_reception
Type
float
Description
Average days from sample collection to laboratory reception.
Name
reception_registration
Type
float
Description
Average days from laboratory reception to sample registration.
Name
registration_analysis
Type
float
Description
Average days from sample registration to analysis.
Name
analysis_validation
Type
float
Description
Average days from analysis to result validation.

Request

GET

/hiv/vl/summary/tat/

curl -G https://api.openldr.org.mz/hiv/vl/summary/tat/ \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  --data-urlencode 'interval_dates=["2025-01-01","2025-12-31"]'

Response

[
  {
    "year": 2025,
    "month": 1,
    "month_name": "January",
    "collection_reception": 4.2,
    "reception_registration": 1.3,
    "registration_analysis": 2.8,
    "analysis_validation": 0.7
  },
  {
    "year": 2025,
    "month": 2,
    "month_name": "February",
    "collection_reception": 3.9,
    "reception_registration": 1.1,
    "registration_analysis": 2.5,
    "analysis_validation": 0.6
  }
]

GET/hiv/vl/summary/suppression_by_province/

Suppression by province

Returns an array of viral suppression data grouped by province, showing suppressed and not suppressed counts for each province.

Name
province
Type
string
Description
The name of the province.
Name
suppressed
Type
integer
Description
Number of suppressed results in the province.
Name
not_suppressed
Type
integer
Description
Number of not suppressed results in the province.

Request

GET

/hiv/vl/summary/suppression_by_province/

curl -G https://api.openldr.org.mz/hiv/vl/summary/suppression_by_province/ \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  --data-urlencode 'interval_dates=["2025-01-01","2025-12-31"]'

Response

[
  {
    "province": "Maputo Cidade",
    "suppressed": 18450,
    "not_suppressed": 2870
  },
  {
    "province": "Gaza",
    "suppressed": 14320,
    "not_suppressed": 2150
  }
]

GET/hiv/vl/summary/samples_history/

Samples history

Returns an array of monthly sample totals providing a historical view of testing volume over time. Useful for long-term trend analysis and capacity planning.

Name
year
Type
integer
Description
The year of the record.
Name
month
Type
integer
Description
The month number (1-12).
Name
month_name
Type
string
Description
The name of the month.
Name
total
Type
integer
Description
Total number of samples in the month.

Request

GET

/hiv/vl/summary/samples_history/

curl -G https://api.openldr.org.mz/hiv/vl/summary/samples_history/ \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  --data-urlencode 'interval_dates=["2025-01-01","2025-12-31"]'

Response

[
  {
    "year": 2025,
    "month": 1,
    "month_name": "January",
    "total": 16230
  },
  {
    "year": 2025,
    "month": 2,
    "month_name": "February",
    "total": 15180
  }
]