HIV EID - Laboratory

Laboratory-level endpoints for HIV Early Infant Diagnosis (EID/DPI) analytics. These endpoints provide testing data grouped by testing facility, including sample counts, positivity rates, turnaround times, equipment usage, and geographic sample routing.

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, facility type, 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".
Name
lab_type
Type
string
Description
Filter by laboratory type. Accepted values: "conventional", "poc", "all".

Request with parameters

GET

/hiv/eid/laboratories/tested_samples/

curl -G https://api.openldr.org.mz/hiv/eid/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" \
  --data-urlencode "lab_type=conventional"

GET/hiv/eid/laboratories/tested_samples_by_month/

Tested samples by month

Returns the number of EID samples tested per month, broken down by result (positive/negative) and sex. Use this endpoint to track monthly testing volume and positivity 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 tested in that month.
Name
positive
Type
integer
Description
Number of samples with a positive (HIV-detected) result.
Name
negative
Type
integer
Description
Number of samples with a negative (HIV-not-detected) result.
Name
female
Type
integer
Description
Number of samples from female patients.
Name
male
Type
integer
Description
Number of samples from male patients.

Request

GET

/hiv/eid/laboratories/tested_samples_by_month/

curl -G https://api.openldr.org.mz/hiv/eid/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": 1842,
    "positive": 87,
    "negative": 1755,
    "female": 934,
    "male": 908
  },
  {
    "year": 2025,
    "month": 2,
    "month_name": "February",
    "total": 1763,
    "positive": 72,
    "negative": 1691,
    "female": 891,
    "male": 872
  }
]

GET/hiv/eid/laboratories/registered_samples_by_month/

Registered samples by month

Returns the total number of EID samples registered (received) at laboratories per month. Use this endpoint to monitor sample intake volume over time.

Name
year
Type
integer
Description
The calendar year of registration.
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 in that month.

Request

GET

/hiv/eid/laboratories/registered_samples_by_month/

curl -G https://api.openldr.org.mz/hiv/eid/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",
    "total": 1956
  },
  {
    "year": 2025,
    "month": 2,
    "month_name": "February",
    "total": 1874
  }
]

GET/hiv/eid/laboratories/tested_samples/

Tested samples

Returns the total number of EID samples tested per testing facility, with positive and negative breakdowns. Use this endpoint to compare testing output and positivity rates across laboratories.

Name
testing_facility
Type
string
Description
The name of the testing laboratory.
Name
total
Type
integer
Description
Total number of samples tested at the facility.
Name
positive
Type
integer
Description
Number of samples with a positive (HIV-detected) result.
Name
negative
Type
integer
Description
Number of samples with a negative (HIV-not-detected) result.

Request

GET

/hiv/eid/laboratories/tested_samples/

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

Response

[
  {
    "testing_facility": "INS Marracuene",
    "total": 5214,
    "positive": 243,
    "negative": 4971
  },
  {
    "testing_facility": "Hospital Central de Maputo",
    "total": 3867,
    "positive": 178,
    "negative": 3689
  }
]

GET/hiv/eid/laboratories/tat/

TAT

Returns turnaround time (TAT) averages per testing facility, broken down by each segment of the sample transport and processing chain. Values represent the average number of days for each segment.

Name
testing_facility
Type
string
Description
The name of the testing laboratory.
Name
collection_receiveHub
Type
float
Description
Average days from sample collection to hub reception.
Name
receiveHub_registrationHub
Type
float
Description
Average days from hub reception to hub registration.
Name
registrationHub_receiveLab
Type
float
Description
Average days from hub registration to laboratory reception.
Name
receiveLab_registrationLab
Type
float
Description
Average days from laboratory reception to laboratory registration.
Name
registrationLab_analyseLab
Type
float
Description
Average days from laboratory registration to sample analysis.
Name
analyseLab_validationLab
Type
float
Description
Average days from sample analysis to result validation.

Request

GET

/hiv/eid/laboratories/tat/

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

Response

[
  {
    "testing_facility": "INS Marracuene",
    "collection_receiveHub": 3.2,
    "receiveHub_registrationHub": 0.5,
    "registrationHub_receiveLab": 2.1,
    "receiveLab_registrationLab": 0.8,
    "registrationLab_analyseLab": 1.4,
    "analyseLab_validationLab": 0.3
  }
]

GET/hiv/eid/laboratories/tat_samples/

TAT samples

Returns the number of samples grouped by turnaround time ranges for a given TAT segment category. Use this endpoint to understand the distribution of processing times across defined intervals.

In addition to the common parameters, this endpoint accepts the following:

Name
category
Type
integer
Description
The TAT segment to analyze. Accepted values: 1 (collection to hub reception), 2 (hub reception to hub registration), 3 (hub registration to lab reception), 4 (lab reception to lab registration), 5 (lab registration to analysis), 6 (analysis to validation).

Response fields:

Name
category
Type
string
Description
The name of the TAT segment being measured.
Name
less_7
Type
integer
Description
Number of samples processed in less than 7 days.
Name
between_7_14
Type
integer
Description
Number of samples processed in 7 to 14 days.
Name
between_15_21
Type
integer
Description
Number of samples processed in 15 to 21 days.
Name
greater_21
Type
integer
Description
Number of samples processed in more than 21 days.

Request

GET

/hiv/eid/laboratories/tat_samples/

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

Response

[
  {
    "category": "Collection to Hub Reception",
    "less_7": 4521,
    "between_7_14": 1203,
    "between_15_21": 387,
    "greater_21": 142
  }
]

GET/hiv/eid/laboratories/rejected_samples/

Rejected samples

Returns the total number of rejected EID samples per testing facility. Use this endpoint to identify laboratories with high rejection rates.

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

Request

GET

/hiv/eid/laboratories/rejected_samples/

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

Response

[
  {
    "testing_facility": "INS Marracuene",
    "total": 312
  },
  {
    "testing_facility": "Hospital Central de Maputo",
    "total": 187
  }
]

GET/hiv/eid/laboratories/rejected_samples_by_month/

Rejected samples by month

Returns the number of rejected EID samples per month. Use this endpoint to track rejection trends over time.

Name
year
Type
integer
Description
The calendar year of the rejection.
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 that month.

Request

GET

/hiv/eid/laboratories/rejected_samples_by_month/

curl -G https://api.openldr.org.mz/hiv/eid/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": 45
  },
  {
    "year": 2025,
    "month": 2,
    "month_name": "February",
    "total": 38
  }
]

GET/hiv/eid/laboratories/samples_by_equipment/

Samples by equipment

Returns the number of EID samples processed per testing facility, broken down by equipment platform. Use this endpoint to analyze equipment utilization across laboratories.

Name
testing_facility
Type
string
Description
The name of the testing laboratory.
Name
CAPCTM
Type
integer
Description
Number of samples processed on the Roche COBAS CAP/CTM platform.
Name
ALINITY
Type
integer
Description
Number of samples processed on the Abbott Alinity platform.
Name
M2000
Type
integer
Description
Number of samples processed on the Abbott m2000 platform.
Name
C6800
Type
integer
Description
Number of samples processed on the Roche COBAS 6800 platform.
Name
PANTHER
Type
integer
Description
Number of samples processed on the Hologic Panther platform.
Name
MPIMA
Type
integer
Description
Number of samples processed on the Abbott m-PIMA platform.
Name
MANUAL
Type
integer
Description
Number of samples processed manually.

Request

GET

/hiv/eid/laboratories/samples_by_equipment/

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

Response

[
  {
    "testing_facility": "INS Marracuene",
    "CAPCTM": 1245,
    "ALINITY": 987,
    "M2000": 1532,
    "C6800": 0,
    "PANTHER": 0,
    "MPIMA": 450,
    "MANUAL": 0
  }
]

GET/hiv/eid/laboratories/samples_by_equipment_by_month/

Samples by equipment by month

Returns the number of EID samples processed per month, broken down by equipment platform. Use this endpoint to track equipment utilization trends over time.

Name
year
Type
integer
Description
The calendar year.
Name
month
Type
integer
Description
The month number (1-12).
Name
month_name
Type
string
Description
The full name of the month.
Name
CAPCTM
Type
integer
Description
Number of samples processed on the Roche COBAS CAP/CTM platform.
Name
ALINITY
Type
integer
Description
Number of samples processed on the Abbott Alinity platform.
Name
M2000
Type
integer
Description
Number of samples processed on the Abbott m2000 platform.
Name
C6800
Type
integer
Description
Number of samples processed on the Roche COBAS 6800 platform.
Name
PANTHER
Type
integer
Description
Number of samples processed on the Hologic Panther platform.
Name
MPIMA
Type
integer
Description
Number of samples processed on the Abbott m-PIMA platform.
Name
MANUAL
Type
integer
Description
Number of samples processed manually.

Request

GET

/hiv/eid/laboratories/samples_by_equipment_by_month/

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

Response

[
  {
    "year": 2025,
    "month": 1,
    "month_name": "January",
    "CAPCTM": 412,
    "ALINITY": 305,
    "M2000": 498,
    "C6800": 0,
    "PANTHER": 0,
    "MPIMA": 127,
    "MANUAL": 0
  }
]

GET/hiv/eid/laboratories/sample_routes/

Sample routes

Returns the geographic routing of EID samples from requesting facilities to testing laboratories, including coordinates for mapping. Use this endpoint to visualize sample transport networks.

Name
requesting_facility
Type
string
Description
The name of the health facility that requested the test.
Name
testing_facility
Type
string
Description
The name of the laboratory that processed the sample.
Name
requesting_latitude
Type
float
Description
Latitude coordinate of the requesting facility.
Name
requesting_longitude
Type
float
Description
Longitude coordinate of the requesting facility.
Name
testing_latitude
Type
float
Description
Latitude coordinate of the testing laboratory.
Name
testing_longitude
Type
float
Description
Longitude coordinate of the testing laboratory.
Name
total
Type
integer
Description
Total number of samples transported along this route.

Request

GET

/hiv/eid/laboratories/sample_routes/

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

Response

[
  {
    "requesting_facility": "CS Machava II",
    "testing_facility": "INS Marracuene",
    "requesting_latitude": -25.9623,
    "requesting_longitude": 32.5732,
    "testing_latitude": -25.7312,
    "testing_longitude": 32.6408,
    "total": 245
  }
]

GET/hiv/eid/laboratories/sample_routes_viewport/

Sample routes viewport

Returns sample route data filtered to a geographic bounding box, useful for map-based interfaces that only need routes visible in the current viewport. Accepts the same parameters as the sample routes endpoint, plus a viewport filter.

In addition to the common parameters, this endpoint accepts the following:

Name
viewport
Type
string
Description
A comma-separated bounding box in the format "south,west,north,east" using decimal degrees. Only routes with at least one endpoint inside the bounding box are returned.

Response fields:

Name
requesting_facility
Type
string
Description
The name of the health facility that requested the test.
Name
testing_facility
Type
string
Description
The name of the laboratory that processed the sample.
Name
requesting_latitude
Type
float
Description
Latitude coordinate of the requesting facility.
Name
requesting_longitude
Type
float
Description
Longitude coordinate of the requesting facility.
Name
testing_latitude
Type
float
Description
Latitude coordinate of the testing laboratory.
Name
testing_longitude
Type
float
Description
Longitude coordinate of the testing laboratory.
Name
total
Type
integer
Description
Total number of samples transported along this route.

Request

GET

/hiv/eid/laboratories/sample_routes_viewport/

curl -G https://api.openldr.org.mz/hiv/eid/laboratories/sample_routes_viewport/ \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  --data-urlencode 'interval_dates=["2025-01-01","2025-12-31"]' \
  --data-urlencode "viewport=-26.87,32.01,-25.00,33.50"

Response

[
  {
    "requesting_facility": "CS Machava II",
    "testing_facility": "INS Marracuene",
    "requesting_latitude": -25.9623,
    "requesting_longitude": 32.5732,
    "testing_latitude": -25.7312,
    "testing_longitude": 32.6408,
    "total": 245
  }
]