HIV VL - Health Facilities

Health facility-level endpoints for HIV Viral Load (VL) analytics. These endpoints provide data grouped by requesting facility (health facility that sent the sample), including sample counts, viral suppression, gender and age breakdowns, turnaround times, rejection data, and PMTCT indicators.

Common parameters

Most facility-level VL endpoints accept a common set of query parameters for filtering results by date range, geography, and aggregation level.

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/facilities/

curl -G https://api.openldr.org.mz/hiv/vl/facilities/registered_samples/ \
  -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=health_facility" \
  --data-urlencode "disaggregation=True"

GET/hiv/vl/facilities/registered_samples/

Registered samples

Returns the total number of registered VL samples per month at the facility level, 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 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/facilities/registered_samples/

curl -G https://api.openldr.org.mz/hiv/vl/facilities/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/facilities/tested_samples_by_month/

Tested samples by month

Returns the number of VL samples tested per month at the facility level, 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/facilities/tested_samples_by_month/

curl -G https://api.openldr.org.mz/hiv/vl/facilities/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/facilities/tested_samples_by_facility/

Tested samples by facility

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

Name
requesting_facility
Type
string
Description
The name of the requesting health facility.
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/facilities/tested_samples_by_facility/

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

Response

[
  {
    "requesting_facility": "CS Mavalane",
    "total": 8420,
    "total_not_null": 7890,
    "total_null": 530,
    "suppressed": 6780,
    "not_suppressed": 1110
  },
  {
    "requesting_facility": "CS Bagamoyo",
    "total": 6350,
    "total_not_null": 5980,
    "total_null": 370,
    "suppressed": 5140,
    "not_suppressed": 840
  }
]

GET/hiv/vl/facilities/tested_samples_by_gender/

Tested samples by gender

Returns monthly tested sample counts at the facility level, 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/facilities/tested_samples_by_gender/

curl -G https://api.openldr.org.mz/hiv/vl/facilities/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/facilities/tested_samples_by_gender_by_facility/

Tested samples by gender by facility

Returns monthly tested sample counts disaggregated by gender and suppression status, additionally grouped by requesting health 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
requesting_facility
Type
string
Description
The name of the requesting health facility.
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/facilities/tested_samples_by_gender_by_facility/

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

Response

[
  {
    "year": 2025,
    "month": 1,
    "month_name": "January",
    "requesting_facility": "CS Mavalane",
    "male_suppressed": 1250,
    "male_not_suppressed": 210,
    "female_suppressed": 1890,
    "female_not_suppressed": 310
  }
]

GET/hiv/vl/facilities/tested_samples_by_age/

Tested samples by age

Returns monthly tested sample counts at the facility level, disaggregated by age group.

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/facilities/tested_samples_by_age/

curl -G https://api.openldr.org.mz/hiv/vl/facilities/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/facilities/tested_samples_by_age_by_facility/

Tested samples by age by facility

Returns monthly tested sample counts disaggregated by age group, additionally grouped by requesting health 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
requesting_facility
Type
string
Description
The name of the requesting health facility.
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/facilities/tested_samples_by_age_by_facility/

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

Response

[
  {
    "year": 2025,
    "month": 1,
    "month_name": "January",
    "requesting_facility": "CS Mavalane",
    "age_group": "0-14",
    "total": 340
  },
  {
    "year": 2025,
    "month": 1,
    "month_name": "January",
    "requesting_facility": "CS Mavalane",
    "age_group": "15-19",
    "total": 210
  }
]

GET/hiv/vl/facilities/tested_samples_by_test_reason/

Tested samples by test reason

Returns monthly tested sample counts at the facility level, disaggregated by the reason for testing.

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/facilities/tested_samples_by_test_reason/

curl -G https://api.openldr.org.mz/hiv/vl/facilities/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/facilities/tested_samples_pregnant/

Tested samples pregnant

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

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/facilities/tested_samples_pregnant/

curl -G https://api.openldr.org.mz/hiv/vl/facilities/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/facilities/tested_samples_breastfeeding/

Tested samples breastfeeding

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

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/facilities/tested_samples_breastfeeding/

curl -G https://api.openldr.org.mz/hiv/vl/facilities/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/facilities/rejected_samples_by_month/

Rejected samples by month

Returns the number of rejected VL samples per month at the facility 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 rejected samples in the month.

Request

GET

/hiv/vl/facilities/rejected_samples_by_month/

curl -G https://api.openldr.org.mz/hiv/vl/facilities/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/facilities/rejected_samples_by_facility/

Rejected samples by facility

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

Name
requesting_facility
Type
string
Description
The name of the requesting health facility.
Name
total
Type
integer
Description
Total number of rejected samples from the facility.

Request

GET

/hiv/vl/facilities/rejected_samples_by_facility/

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

Response

[
  {
    "requesting_facility": "CS Mavalane",
    "total": 340
  },
  {
    "requesting_facility": "CS Bagamoyo",
    "total": 210
  }
]

GET/hiv/vl/facilities/tat_by_month/

TAT by month

Returns monthly turnaround time (TAT) averages for each stage of the sample processing pipeline at the facility 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/facilities/tat_by_month/

curl -G https://api.openldr.org.mz/hiv/vl/facilities/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/facilities/tat_by_facility/

TAT by facility

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

Name
requesting_facility
Type
string
Description
The name of the requesting health facility.
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/facilities/tat_by_facility/

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

Response

[
  {
    "requesting_facility": "CS Mavalane",
    "collection_reception": 3.8,
    "reception_registration": 1.0,
    "registration_analysis": 2.3,
    "analysis_validation": 0.5
  },
  {
    "requesting_facility": "CS Bagamoyo",
    "collection_reception": 4.5,
    "reception_registration": 1.4,
    "registration_analysis": 2.9,
    "analysis_validation": 0.8
  }
]