HIV VL - Laboratory

Laboratory-level endpoints for HIV Viral Load (VL) analytics. These endpoints provide testing data grouped by testing facility (laboratory), including sample counts, viral suppression rates, gender and age breakdowns, turnaround times, rejection data, and PMTCT indicators.

Common parameters

Most laboratory endpoints accept the following query parameters for filtering and aggregating data. These parameters allow you to narrow results by date range, geographic location, and level of detail.

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/laboratories/tested_samples/

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

GET/hiv/vl/laboratories/registered_samples/

Registered samples

Returns the total number of VL samples registered per month, with suppression breakdowns by gender. Use this endpoint to monitor monthly sample intake and suppression trends at the laboratory level.

Name
year
Type
integer
Description
The calendar year of the result.
Name
month
Type
integer
Description
The month number (1-12).
Name
month_name
Type
string
Description
The full name of the month.
Name
total
Type
integer
Description
Total number of samples registered.
Name
total_not_null
Type
integer
Description
Total samples with a valid viral load result.
Name
total_null
Type
integer
Description
Total samples without a viral load result.
Name
suppressed
Type
integer
Description
Number of samples with a suppressed viral load.
Name
not_suppressed
Type
integer
Description
Number of samples with a not suppressed viral load.
Name
male_suppressed
Type
integer
Description
Number of suppressed results from male patients.
Name
male_not_suppressed
Type
integer
Description
Number of not suppressed results from male patients.
Name
female_suppressed
Type
integer
Description
Number of suppressed results from female patients.
Name
female_not_suppressed
Type
integer
Description
Number of not suppressed results from female patients.

Request

GET

/hiv/vl/laboratories/registered_samples/

curl -G https://api.openldr.org.mz/hiv/vl/laboratories/registered_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,
    "total_not_null": 14520,
    "total_null": 1320,
    "suppressed": 12450,
    "not_suppressed": 2070,
    "male_suppressed": 4980,
    "male_not_suppressed": 870,
    "female_suppressed": 7470,
    "female_not_suppressed": 1200
  }
]

GET/hiv/vl/laboratories/registered_samples_by_month/

Registered samples by month

Returns the total number of VL samples registered per month with suppression breakdowns by gender, additionally grouped by testing facility.

Name
year
Type
integer
Description
The calendar year of the result.
Name
month
Type
integer
Description
The month number (1-12).
Name
month_name
Type
string
Description
The full name of the month.
Name
testing_facility
Type
string
Description
The name of the testing laboratory.
Name
total
Type
integer
Description
Total number of samples registered.
Name
total_not_null
Type
integer
Description
Total samples with a valid viral load result.
Name
total_null
Type
integer
Description
Total samples without a viral load result.
Name
suppressed
Type
integer
Description
Number of samples with a suppressed viral load.
Name
not_suppressed
Type
integer
Description
Number of samples with a not suppressed viral load.
Name
male_suppressed
Type
integer
Description
Number of suppressed results from male patients.
Name
male_not_suppressed
Type
integer
Description
Number of not suppressed results from male patients.
Name
female_suppressed
Type
integer
Description
Number of suppressed results from female patients.
Name
female_not_suppressed
Type
integer
Description
Number of not suppressed results from female patients.

Request

GET

/hiv/vl/laboratories/registered_samples_by_month/

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

Response

[
  {
    "year": 2025,
    "month": 1,
    "month_name": "January",
    "testing_facility": "Laboratorio Central de Maputo",
    "total": 5230,
    "total_not_null": 4890,
    "total_null": 340,
    "suppressed": 4210,
    "not_suppressed": 680,
    "male_suppressed": 1680,
    "male_not_suppressed": 290,
    "female_suppressed": 2530,
    "female_not_suppressed": 390
  }
]

GET/hiv/vl/laboratories/tested_samples/

Tested samples

Returns the number of VL samples tested grouped by testing facility, with suppression breakdowns.

Name
testing_facility
Type
string
Description
The name of the testing laboratory.
Name
total
Type
integer
Description
Total number of samples tested.
Name
total_not_null
Type
integer
Description
Total samples with a valid viral load result.
Name
total_null
Type
integer
Description
Total samples without a viral load result.
Name
suppressed
Type
integer
Description
Number of samples with a suppressed viral load.
Name
not_suppressed
Type
integer
Description
Number of samples with a not suppressed viral load.

Request

GET

/hiv/vl/laboratories/tested_samples/

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

Response

[
  {
    "testing_facility": "Laboratorio Central de Maputo",
    "total": 48920,
    "total_not_null": 45670,
    "total_null": 3250,
    "suppressed": 39240,
    "not_suppressed": 6430
  },
  {
    "testing_facility": "Laboratorio Provincial de Gaza",
    "total": 32150,
    "total_not_null": 30420,
    "total_null": 1730,
    "suppressed": 26180,
    "not_suppressed": 4240
  }
]

GET/hiv/vl/laboratories/tested_samples_by_month/

Tested samples by month

Returns the number of VL samples tested per month, with suppression breakdowns by gender.

Name
year
Type
integer
Description
The calendar year of the result.
Name
month
Type
integer
Description
The month number (1-12).
Name
month_name
Type
string
Description
The full name of the month.
Name
total
Type
integer
Description
Total number of samples tested.
Name
total_not_null
Type
integer
Description
Total samples with a valid viral load result.
Name
total_null
Type
integer
Description
Total samples without a viral load result.
Name
suppressed
Type
integer
Description
Number of samples with a suppressed viral load.
Name
not_suppressed
Type
integer
Description
Number of samples with a not suppressed viral load.
Name
male_suppressed
Type
integer
Description
Number of suppressed results from male patients.
Name
male_not_suppressed
Type
integer
Description
Number of not suppressed results from male patients.
Name
female_suppressed
Type
integer
Description
Number of suppressed results from female patients.
Name
female_not_suppressed
Type
integer
Description
Number of not suppressed results from female patients.

Request

GET

/hiv/vl/laboratories/tested_samples_by_month/

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

Response

[
  {
    "year": 2025,
    "month": 1,
    "month_name": "January",
    "total": 14520,
    "total_not_null": 13680,
    "total_null": 840,
    "suppressed": 11740,
    "not_suppressed": 1940,
    "male_suppressed": 4690,
    "male_not_suppressed": 820,
    "female_suppressed": 7050,
    "female_not_suppressed": 1120
  }
]

GET/hiv/vl/laboratories/tested_samples_by_gender/

Tested samples by gender

Returns monthly tested sample counts disaggregated by gender and suppression status.

Name
year
Type
integer
Description
The calendar year of the result.
Name
month
Type
integer
Description
The month number (1-12).
Name
month_name
Type
string
Description
The full name of the month.
Name
male_suppressed
Type
integer
Description
Number of suppressed results from male patients.
Name
male_not_suppressed
Type
integer
Description
Number of not suppressed results from male patients.
Name
female_suppressed
Type
integer
Description
Number of suppressed results from female patients.
Name
female_not_suppressed
Type
integer
Description
Number of not suppressed results from female patients.

Request

GET

/hiv/vl/laboratories/tested_samples_by_gender/

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

Response

[
  {
    "year": 2025,
    "month": 1,
    "month_name": "January",
    "male_suppressed": 4690,
    "male_not_suppressed": 820,
    "female_suppressed": 7050,
    "female_not_suppressed": 1120
  },
  {
    "year": 2025,
    "month": 2,
    "month_name": "February",
    "male_suppressed": 4420,
    "male_not_suppressed": 760,
    "female_suppressed": 6680,
    "female_not_suppressed": 1050
  }
]

GET/hiv/vl/laboratories/tested_samples_by_gender_by_lab/

Tested samples by gender by lab

Returns monthly tested sample counts disaggregated by gender and suppression status, additionally grouped by testing facility.

Name
year
Type
integer
Description
The calendar year of the result.
Name
month
Type
integer
Description
The month number (1-12).
Name
month_name
Type
string
Description
The full name of the month.
Name
testing_facility
Type
string
Description
The name of the testing laboratory.
Name
male_suppressed
Type
integer
Description
Number of suppressed results from male patients.
Name
male_not_suppressed
Type
integer
Description
Number of not suppressed results from male patients.
Name
female_suppressed
Type
integer
Description
Number of suppressed results from female patients.
Name
female_not_suppressed
Type
integer
Description
Number of not suppressed results from female patients.

Request

GET

/hiv/vl/laboratories/tested_samples_by_gender_by_lab/

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

Response

[
  {
    "year": 2025,
    "month": 1,
    "month_name": "January",
    "testing_facility": "Laboratorio Central de Maputo",
    "male_suppressed": 1680,
    "male_not_suppressed": 290,
    "female_suppressed": 2530,
    "female_not_suppressed": 390
  }
]

GET/hiv/vl/laboratories/tested_samples_by_age/

Tested samples by age

Returns monthly tested sample counts disaggregated by age group. Age groups follow the standard VL stratification bands.

Name
year
Type
integer
Description
The calendar year of the result.
Name
month
Type
integer
Description
The month number (1-12).
Name
month_name
Type
string
Description
The full name of the month.
Name
age_group
Type
string
Description
The age group band (e.g., "0-14", "15-19", "20-24", "25-29", "30-34", "35-39", "40-44", "45-49", "50+").
Name
total
Type
integer
Description
Total number of samples tested in the age group.

Request

GET

/hiv/vl/laboratories/tested_samples_by_age/

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

Response

[
  {
    "year": 2025,
    "month": 1,
    "month_name": "January",
    "age_group": "0-14",
    "total": 1240
  },
  {
    "year": 2025,
    "month": 1,
    "month_name": "January",
    "age_group": "15-19",
    "total": 890
  },
  {
    "year": 2025,
    "month": 1,
    "month_name": "January",
    "age_group": "20-24",
    "total": 2150
  }
]

GET/hiv/vl/laboratories/tested_samples_by_test_reason/

Tested samples by test reason

Returns monthly tested sample counts disaggregated by the reason for testing, including routine monitoring, treatment failure suspicion, and unspecified reasons.

Name
year
Type
integer
Description
The calendar year of the result.
Name
month
Type
integer
Description
The month number (1-12).
Name
month_name
Type
string
Description
The full name of the month.
Name
routine
Type
integer
Description
Number of samples tested for routine viral load monitoring.
Name
treatment_failure
Type
integer
Description
Number of samples tested due to suspected treatment failure.
Name
reason_not_specified
Type
integer
Description
Number of samples where the test reason was not specified.
Name
total
Type
integer
Description
Total number of samples tested in the month.

Request

GET

/hiv/vl/laboratories/tested_samples_by_test_reason/

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

Response

[
  {
    "year": 2025,
    "month": 1,
    "month_name": "January",
    "routine": 11230,
    "treatment_failure": 1850,
    "reason_not_specified": 1440,
    "total": 14520
  },
  {
    "year": 2025,
    "month": 2,
    "month_name": "February",
    "routine": 10580,
    "treatment_failure": 1720,
    "reason_not_specified": 1310,
    "total": 13610
  }
]

GET/hiv/vl/laboratories/tested_samples_pregnant/

Tested samples pregnant

Returns monthly tested sample counts for pregnant women, with viral suppression breakdowns. Supports PMTCT program monitoring at the laboratory level.

Name
year
Type
integer
Description
The calendar year of the result.
Name
month
Type
integer
Description
The month number (1-12).
Name
month_name
Type
string
Description
The full name of the month.
Name
total
Type
integer
Description
Total number of samples from pregnant women.
Name
suppressed
Type
integer
Description
Number of suppressed results from pregnant women.
Name
not_suppressed
Type
integer
Description
Number of not suppressed results from pregnant women.

Request

GET

/hiv/vl/laboratories/tested_samples_pregnant/

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

Response

[
  {
    "year": 2025,
    "month": 1,
    "month_name": "January",
    "total": 2340,
    "suppressed": 2050,
    "not_suppressed": 290
  },
  {
    "year": 2025,
    "month": 2,
    "month_name": "February",
    "total": 2180,
    "suppressed": 1920,
    "not_suppressed": 260
  }
]

GET/hiv/vl/laboratories/tested_samples_breastfeeding/

Tested samples breastfeeding

Returns monthly tested sample counts for breastfeeding women, with viral suppression breakdowns. Supports PMTCT program monitoring at the laboratory level.

Name
year
Type
integer
Description
The calendar year of the result.
Name
month
Type
integer
Description
The month number (1-12).
Name
month_name
Type
string
Description
The full name of the month.
Name
total
Type
integer
Description
Total number of samples from breastfeeding women.
Name
suppressed
Type
integer
Description
Number of suppressed results from breastfeeding women.
Name
not_suppressed
Type
integer
Description
Number of not suppressed results from breastfeeding women.

Request

GET

/hiv/vl/laboratories/tested_samples_breastfeeding/

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

Response

[
  {
    "year": 2025,
    "month": 1,
    "month_name": "January",
    "total": 1870,
    "suppressed": 1650,
    "not_suppressed": 220
  },
  {
    "year": 2025,
    "month": 2,
    "month_name": "February",
    "total": 1740,
    "suppressed": 1540,
    "not_suppressed": 200
  }
]

GET/hiv/vl/laboratories/rejected_samples/

Rejected samples

Returns the total number of rejected VL samples grouped by testing facility.

Name
testing_facility
Type
string
Description
The name of the testing laboratory.
Name
total
Type
integer
Description
Total number of rejected samples at the laboratory.

Request

GET

/hiv/vl/laboratories/rejected_samples/

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

Response

[
  {
    "testing_facility": "Laboratorio Central de Maputo",
    "total": 2340
  },
  {
    "testing_facility": "Laboratorio Provincial de Gaza",
    "total": 1520
  }
]

GET/hiv/vl/laboratories/rejected_samples_by_month/

Rejected samples by month

Returns the number of rejected VL samples per month, useful for monitoring sample quality trends over time.

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

Request

GET

/hiv/vl/laboratories/rejected_samples_by_month/

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

Response

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

GET/hiv/vl/laboratories/tat_by_lab/

TAT by lab

Returns turnaround time (TAT) averages for each stage of the sample processing pipeline, grouped by testing facility.

Name
testing_facility
Type
string
Description
The name of the testing laboratory.
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/laboratories/tat_by_lab/

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

Response

[
  {
    "testing_facility": "Laboratorio Central de Maputo",
    "collection_reception": 3.5,
    "reception_registration": 0.8,
    "registration_analysis": 2.1,
    "analysis_validation": 0.5
  },
  {
    "testing_facility": "Laboratorio Provincial de Gaza",
    "collection_reception": 4.8,
    "reception_registration": 1.2,
    "registration_analysis": 3.0,
    "analysis_validation": 0.7
  }
]

GET/hiv/vl/laboratories/tat_by_month/

TAT by month

Returns monthly turnaround time (TAT) averages for each stage of the sample processing pipeline at the laboratory level.

Name
year
Type
integer
Description
The calendar year of the result.
Name
month
Type
integer
Description
The month number (1-12).
Name
month_name
Type
string
Description
The full 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/laboratories/tat_by_month/

curl -G https://api.openldr.org.mz/hiv/vl/laboratories/tat_by_month/ \
  -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/laboratories/suppression/

Suppression

Returns monthly viral suppression data at the laboratory level, showing total tested, suppressed, and not suppressed counts over time.

Name
year
Type
integer
Description
The calendar year of the result.
Name
month
Type
integer
Description
The month number (1-12).
Name
month_name
Type
string
Description
The full name of the month.
Name
total
Type
integer
Description
Total number of samples tested in 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/laboratories/suppression/

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

Response

[
  {
    "year": 2025,
    "month": 1,
    "month_name": "January",
    "total": 14520,
    "suppressed": 12450,
    "not_suppressed": 2070
  },
  {
    "year": 2025,
    "month": 2,
    "month_name": "February",
    "total": 13610,
    "suppressed": 11720,
    "not_suppressed": 1890
  }
]