HIV EID - Health Facilities

Health facility-level endpoints for HIV Early Infant Diagnosis (EID/DPI) analytics. These endpoints provide data grouped by requesting facility (health facility that sent the sample), including sample counts, positivity, gender breakdown, turnaround times, rejection data, and age group analysis.

Common parameters

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

Request with parameters

GET

/hiv/eid/facilities/

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

GET/hiv/eid/facilities/registered_samples/

Registered samples

Returns the total number of registered EID samples grouped by requesting health facility.

Name
requesting_facility
Type
string
Description
Name of the health facility that requested the test.
Name
total
Type
integer
Description
Total number of registered samples for this facility.

Request

GET

/hiv/eid/facilities/registered_samples/

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

Response

[
  {
    "requesting_facility": "CS Machava II",
    "total": 342
  },
  {
    "requesting_facility": "CS 1 de Junho",
    "total": 287
  }
]

GET/hiv/eid/facilities/registered_samples_by_month/

Registered samples by month

Returns the total number of registered EID samples aggregated by month.

Name
year
Type
integer
Description
Year of the record.
Name
month
Type
integer
Description
Month number (1-12).
Name
month_name
Type
string
Description
Full name of the month.
Name
total
Type
integer
Description
Total number of registered samples for this month.

Request

GET

/hiv/eid/facilities/registered_samples_by_month/

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

GET/hiv/eid/facilities/tested_samples/

Tested samples

Returns tested EID samples grouped by requesting health facility, including positivity breakdown.

Name
requesting_facility
Type
string
Description
Name of the health facility that requested the test.
Name
total
Type
integer
Description
Total number of tested samples for this facility.
Name
positive
Type
integer
Description
Number of HIV-positive results (DNA detected).
Name
negative
Type
integer
Description
Number of HIV-negative results (DNA not detected).

Request

GET

/hiv/eid/facilities/tested_samples/

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

Response

[
  {
    "requesting_facility": "CS Machava II",
    "total": 310,
    "positive": 18,
    "negative": 292
  },
  {
    "requesting_facility": "CS 1 de Junho",
    "total": 265,
    "positive": 12,
    "negative": 253
  }
]

GET/hiv/eid/facilities/tested_samples_by_month/

Tested samples by month

Returns tested EID samples aggregated by month, with positivity and gender breakdown.

Name
year
Type
integer
Description
Year of the record.
Name
month
Type
integer
Description
Month number (1-12).
Name
month_name
Type
string
Description
Full name of the month.
Name
total
Type
integer
Description
Total number of tested samples.
Name
positive
Type
integer
Description
Number of HIV-positive results.
Name
negative
Type
integer
Description
Number of HIV-negative results.
Name
female
Type
integer
Description
Number of female infant samples tested.
Name
male
Type
integer
Description
Number of male infant samples tested.

Request

GET

/hiv/eid/facilities/tested_samples_by_month/

curl -G https://api.openldr.org.mz/hiv/eid/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": 1180,
    "positive": 65,
    "negative": 1115,
    "female": 598,
    "male": 582
  },
  {
    "year": 2025,
    "month": 2,
    "month_name": "February",
    "total": 1043,
    "positive": 52,
    "negative": 991,
    "female": 520,
    "male": 523
  }
]

GET/hiv/eid/facilities/tested_samples_by_gender/

Tested samples by gender

Returns tested EID samples grouped by requesting health facility with gender breakdown.

Name
requesting_facility
Type
string
Description
Name of the health facility that requested the test.
Name
total
Type
integer
Description
Total number of tested samples for this facility.
Name
female
Type
integer
Description
Number of female infant samples tested.
Name
male
Type
integer
Description
Number of male infant samples tested.

Request

GET

/hiv/eid/facilities/tested_samples_by_gender/

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

Response

[
  {
    "requesting_facility": "CS Machava II",
    "total": 310,
    "female": 158,
    "male": 152
  },
  {
    "requesting_facility": "CS 1 de Junho",
    "total": 265,
    "female": 130,
    "male": 135
  }
]

GET/hiv/eid/facilities/tested_samples_by_gender_by_month/

Tested samples by gender by month

Returns tested EID samples aggregated by month with gender breakdown.

Name
year
Type
integer
Description
Year of the record.
Name
month
Type
integer
Description
Month number (1-12).
Name
month_name
Type
string
Description
Full name of the month.
Name
total
Type
integer
Description
Total number of tested samples.
Name
female
Type
integer
Description
Number of female infant samples tested.
Name
male
Type
integer
Description
Number of male infant samples tested.

Request

GET

/hiv/eid/facilities/tested_samples_by_gender_by_month/

curl -G https://api.openldr.org.mz/hiv/eid/facilities/tested_samples_by_gender_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": 1180,
    "female": 598,
    "male": 582
  },
  {
    "year": 2025,
    "month": 2,
    "month_name": "February",
    "total": 1043,
    "female": 520,
    "male": 523
  }
]

GET/hiv/eid/facilities/tat_avg_by_month/

TAT avg by month

Returns the average turnaround time (TAT) for each stage of the sample workflow, aggregated by month. Values are expressed in days.

Name
year
Type
integer
Description
Year of the record.
Name
month
Type
integer
Description
Month number (1-12).
Name
month_name
Type
string
Description
Full name of the month.
Name
collection_receiveHub
Type
float
Description
Average days from sample collection to reception at the hub.
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 analysis.
Name
analyseLab_validationLab
Type
float
Description
Average days from analysis to result validation.

Request

GET

/hiv/eid/facilities/tat_avg_by_month/

curl -G https://api.openldr.org.mz/hiv/eid/facilities/tat_avg_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_receiveHub": 3.2,
    "receiveHub_registrationHub": 0.5,
    "registrationHub_receiveLab": 2.1,
    "receiveLab_registrationLab": 0.3,
    "registrationLab_analyseLab": 1.8,
    "analyseLab_validationLab": 0.4
  }
]

GET/hiv/eid/facilities/tat_avg/

TAT avg

Returns the average turnaround time (TAT) for each workflow stage, grouped by requesting health facility. Values are expressed in days.

Name
requesting_facility
Type
string
Description
Name of the health facility that requested the test.
Name
collection_receiveHub
Type
float
Description
Average days from sample collection to reception at the hub.
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 analysis.
Name
analyseLab_validationLab
Type
float
Description
Average days from analysis to result validation.

Request

GET

/hiv/eid/facilities/tat_avg/

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

Response

[
  {
    "requesting_facility": "CS Machava II",
    "collection_receiveHub": 2.8,
    "receiveHub_registrationHub": 0.4,
    "registrationHub_receiveLab": 1.9,
    "receiveLab_registrationLab": 0.2,
    "registrationLab_analyseLab": 1.5,
    "analyseLab_validationLab": 0.3
  },
  {
    "requesting_facility": "CS 1 de Junho",
    "collection_receiveHub": 4.1,
    "receiveHub_registrationHub": 0.6,
    "registrationHub_receiveLab": 2.5,
    "receiveLab_registrationLab": 0.4,
    "registrationLab_analyseLab": 2.0,
    "analyseLab_validationLab": 0.5
  }
]

GET/hiv/eid/facilities/tat_days_by_month/

TAT days by month

Returns the distribution of total turnaround time grouped into day ranges, aggregated by month. Useful for monitoring the percentage of samples processed within target timeframes.

Name
year
Type
integer
Description
Year of the record.
Name
month
Type
integer
Description
Month number (1-12).
Name
month_name
Type
string
Description
Full name of the month.
Name
less_7
Type
integer
Description
Number of samples with total TAT less than 7 days.
Name
between_7_15
Type
integer
Description
Number of samples with total TAT between 7 and 15 days.
Name
between_16_21
Type
integer
Description
Number of samples with total TAT between 16 and 21 days.
Name
greater_21
Type
integer
Description
Number of samples with total TAT greater than 21 days.

Request

GET

/hiv/eid/facilities/tat_days_by_month/

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

Response

[
  {
    "year": 2025,
    "month": 1,
    "month_name": "January",
    "less_7": 420,
    "between_7_15": 385,
    "between_16_21": 210,
    "greater_21": 165
  },
  {
    "year": 2025,
    "month": 2,
    "month_name": "February",
    "less_7": 390,
    "between_7_15": 350,
    "between_16_21": 180,
    "greater_21": 123
  }
]

GET/hiv/eid/facilities/tat_days/

TAT days

Returns the distribution of total turnaround time grouped into day ranges, broken down by requesting health facility.

Name
requesting_facility
Type
string
Description
Name of the health facility that requested the test.
Name
less_7
Type
integer
Description
Number of samples with total TAT less than 7 days.
Name
between_7_15
Type
integer
Description
Number of samples with total TAT between 7 and 15 days.
Name
between_16_21
Type
integer
Description
Number of samples with total TAT between 16 and 21 days.
Name
greater_21
Type
integer
Description
Number of samples with total TAT greater than 21 days.

Request

GET

/hiv/eid/facilities/tat_days/

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

Response

[
  {
    "requesting_facility": "CS Machava II",
    "less_7": 95,
    "between_7_15": 110,
    "between_16_21": 62,
    "greater_21": 43
  },
  {
    "requesting_facility": "CS 1 de Junho",
    "less_7": 78,
    "between_7_15": 92,
    "between_16_21": 55,
    "greater_21": 40
  }
]

GET/hiv/eid/facilities/rejected_samples_by_month/

Rejected samples by month

Returns the total number of rejected EID samples aggregated by month.

Name
year
Type
integer
Description
Year of the record.
Name
month
Type
integer
Description
Month number (1-12).
Name
month_name
Type
string
Description
Full name of the month.
Name
total
Type
integer
Description
Total number of rejected samples for this month.

Request

GET

/hiv/eid/facilities/rejected_samples_by_month/

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

GET/hiv/eid/facilities/rejected_samples/

Rejected samples

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

Name
requesting_facility
Type
string
Description
Name of the health facility that requested the test.
Name
total
Type
integer
Description
Total number of rejected samples for this facility.

Request

GET

/hiv/eid/facilities/rejected_samples/

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

Response

[
  {
    "requesting_facility": "CS Machava II",
    "total": 32
  },
  {
    "requesting_facility": "CS 1 de Junho",
    "total": 22
  }
]

GET/hiv/eid/facilities/key_indicators/

Key indicators

Returns a comprehensive summary of key EID indicators for each requesting health facility, including registration, testing, rejection, and result counts.

Name
requesting_facility
Type
string
Description
Name of the health facility that requested the test.
Name
registered
Type
integer
Description
Total number of registered samples.
Name
tested
Type
integer
Description
Total number of tested samples.
Name
rejected
Type
integer
Description
Total number of rejected samples.
Name
pending
Type
integer
Description
Number of samples still pending results.
Name
positive
Type
integer
Description
Number of HIV-positive results (DNA detected).
Name
negative
Type
integer
Description
Number of HIV-negative results (DNA not detected).

Request

GET

/hiv/eid/facilities/key_indicators/

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

Response

[
  {
    "requesting_facility": "CS Machava II",
    "registered": 342,
    "tested": 310,
    "rejected": 32,
    "pending": 0,
    "positive": 18,
    "negative": 292
  },
  {
    "requesting_facility": "CS 1 de Junho",
    "registered": 287,
    "tested": 265,
    "rejected": 22,
    "pending": 0,
    "positive": 12,
    "negative": 253
  }
]

GET/hiv/eid/facilities/tested_samples_by_age/

Tested samples by age

Returns tested EID samples broken down by age group and month. Age groups are based on the infant's age in days at the time of sample collection.

Age groups are defined as follows: 0-2 months (0-60 days), 2-9 months (61-270 days), 9-18 months (271-540 days), 18+ months (more than 540 days), and Unknown (age not recorded).

Name
year
Type
integer
Description
Year of the record.
Name
month
Type
integer
Description
Month number (1-12).
Name
month_name
Type
string
Description
Full name of the month.
Name
age_group
Type
string
Description
Age group label. Possible values: "0-2 months", "2-9 months", "9-18 months", "18+ months", "Unknown".
Name
total
Type
integer
Description
Total number of tested samples in this age group for the given month.

Request

GET

/hiv/eid/facilities/tested_samples_by_age/

curl -G https://api.openldr.org.mz/hiv/eid/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-2 months",
"total": 485
  },
  {
"year": 2025,
"month": 1,
"month_name": "January",
"age_group": "2-9 months",
"total": 392
  },
  {
"year": 2025,
"month": 1,
"month_name": "January",
"age_group": "9-18 months",
"total": 198
  },
  {
"year": 2025,
"month": 1,
"month_name": "January",
"age_group": "18+ months",
"total": 72
  },
  {
"year": 2025,
"month": 1,
"month_name": "January",
"age_group": "Unknown",
"total": 33
  }
]