TB GeneXpert - Summary

System-wide summary and dashboard endpoints for TB GeneXpert analytics. These endpoints provide aggregated indicators, positivity rates by month and laboratory, and sample type distribution across the entire GeneXpert testing network.

Common parameters

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

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
genexpert_result_type
Type
string
Description
Filter by cartridge type. Accepted values: "Ultra 6 Cores", "XDR 10 Cores".

Request with parameters

GET

/tb/gx/summary/summary_header_component/

curl -G https://api.openldr.org.mz/tb/gx/summary/summary_header_component/ \
  -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" \
  --data-urlencode "genexpert_result_type=Ultra 6 Cores"

GET/tb/gx/summary/summary_header_component/

Summary header component

Returns a single object with the main GeneXpert dashboard indicators for the selected period. Includes totals for registered, analyzed, detected, and not detected samples for both Ultra and XDR result types, along with average turnaround time, error counts, and invalid sample counts.

Name
Ultra_Registered
Type
integer
Description
Total number of Ultra samples registered in the system.
Name
Ultra_Analysed
Type
integer
Description
Total number of Ultra samples that have been analyzed.
Name
Ultra_Detected
Type
integer
Description
Total number of Ultra samples with MTB detected result.
Name
Ultra_Not_Detected
Type
integer
Description
Total number of Ultra samples with MTB not detected result.
Name
XDR_Registered
Type
integer
Description
Total number of XDR samples registered in the system.
Name
XDR_Analysed
Type
integer
Description
Total number of XDR samples that have been analyzed.
Name
XDR_Detected
Type
integer
Description
Total number of XDR samples with resistance detected.
Name
XDR_Not_Detected
Type
integer
Description
Total number of XDR samples with no resistance detected.
Name
AVG_TRL_Days
Type
float
Description
Average total turnaround time in days across all samples.
Name
Errors
Type
integer
Description
Total number of samples that resulted in system errors.
Name
Invalid
Type
integer
Description
Total number of samples with invalid results.

Request

GET

/tb/gx/summary/summary_header_component/

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

Response

{
  "Ultra_Registered": 32450,
  "Ultra_Analysed": 30120,
  "Ultra_Detected": 4518,
  "Ultra_Not_Detected": 25602,
  "XDR_Registered": 4200,
  "XDR_Analysed": 3980,
  "XDR_Detected": 312,
  "XDR_Not_Detected": 3668,
  "AVG_TRL_Days": 3.7,
  "Errors": 845,
  "Invalid": 423
}

GET/tb/gx/summary/positivity_by_month/

Positivity by month

Returns an array of monthly positivity data, including registered samples, analyzed samples, detected and not detected results, errors, and invalid sample counts.

Name
Month
Type
integer
Description
The month number (1-12).
Name
Month_Name
Type
string
Description
The name of the month.
Name
Year
Type
integer
Description
The year of the record.
Name
Registered_Samples
Type
integer
Description
Total number of samples registered in the month.
Name
Analysed_Samples
Type
integer
Description
Total number of samples analyzed in the month.
Name
Detected_Samples
Type
integer
Description
Number of samples with MTB detected.
Name
Not_Detected_Samples
Type
integer
Description
Number of samples with MTB not detected.
Name
Errors
Type
integer
Description
Number of samples with error results.
Name
Invalid_Samples
Type
integer
Description
Number of samples with invalid results.

Request

GET

/tb/gx/summary/positivity_by_month/

curl -G https://api.openldr.org.mz/tb/gx/summary/positivity_by_month/ \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  --data-urlencode 'interval_dates=["2025-01-01","2025-12-31"]' \
  --data-urlencode "genexpert_result_type=Ultra 6 Cores"

Response

[
  {
    "Month": 1,
    "Month_Name": "January",
    "Year": 2025,
    "Registered_Samples": 2870,
    "Analysed_Samples": 2650,
    "Detected_Samples": 398,
    "Not_Detected_Samples": 2252,
    "Errors": 72,
    "Invalid_Samples": 35
  },
  {
    "Month": 2,
    "Month_Name": "February",
    "Year": 2025,
    "Registered_Samples": 2640,
    "Analysed_Samples": 2480,
    "Detected_Samples": 362,
    "Not_Detected_Samples": 2118,
    "Errors": 58,
    "Invalid_Samples": 28
  }
]

GET/tb/gx/summary/positivity_by_lab/

Positivity by lab

Returns an array of positivity data grouped by testing laboratory, including registered, analyzed, detected, not detected, error, and invalid counts for each lab.

Name
Testing_Facility
Type
string
Description
The name of the testing laboratory.
Name
Registered_Samples
Type
integer
Description
Total number of samples registered at this laboratory.
Name
Analysed_Samples
Type
integer
Description
Total number of samples analyzed at this laboratory.
Name
Detected_Samples
Type
integer
Description
Number of samples with MTB detected.
Name
Not_Detected_Samples
Type
integer
Description
Number of samples with MTB not detected.
Name
Errors
Type
integer
Description
Number of samples with error results.
Name
Invalid_Samples
Type
integer
Description
Number of samples with invalid results.

Request

GET

/tb/gx/summary/positivity_by_lab/

curl -G https://api.openldr.org.mz/tb/gx/summary/positivity_by_lab/ \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  --data-urlencode 'interval_dates=["2025-01-01","2025-12-31"]' \
  --data-urlencode "genexpert_result_type=Ultra 6 Cores"

Response

[
  {
    "Testing_Facility": "Hospital Central de Maputo",
    "Registered_Samples": 5240,
    "Analysed_Samples": 4980,
    "Detected_Samples": 747,
    "Not_Detected_Samples": 4233,
    "Errors": 112,
    "Invalid_Samples": 48
  },
  {
    "Testing_Facility": "Hospital Provincial de Nampula",
    "Registered_Samples": 3870,
    "Analysed_Samples": 3650,
    "Detected_Samples": 548,
    "Not_Detected_Samples": 3102,
    "Errors": 85,
    "Invalid_Samples": 37
  }
]

GET/tb/gx/summary/positivity_by_lab_by_age/

Positivity by lab by age

Returns positivity data grouped by testing laboratory with age group disaggregation. Each record represents a laboratory-age group combination with detected and not detected counts.

Name
Testing_Facility
Type
string
Description
The name of the testing laboratory.
Name
Age_Group
Type
string
Description
Age group label (e.g., "0-4", "5-14", "15-24", "25-34", "35-44", "45-54", "55-64", "65+").
Name
Registered_Samples
Type
integer
Description
Total number of samples registered for this lab and age group.
Name
Analysed_Samples
Type
integer
Description
Total number of samples analyzed.
Name
Detected_Samples
Type
integer
Description
Number of samples with MTB detected.
Name
Not_Detected_Samples
Type
integer
Description
Number of samples with MTB not detected.

Request

GET

/tb/gx/summary/positivity_by_lab_by_age/

curl -G https://api.openldr.org.mz/tb/gx/summary/positivity_by_lab_by_age/ \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  --data-urlencode 'interval_dates=["2025-01-01","2025-12-31"]' \
  --data-urlencode "genexpert_result_type=Ultra 6 Cores"

Response

[
  {
    "Testing_Facility": "Hospital Central de Maputo",
    "Age_Group": "25-34",
    "Registered_Samples": 1420,
    "Analysed_Samples": 1350,
    "Detected_Samples": 215,
    "Not_Detected_Samples": 1135
  },
  {
    "Testing_Facility": "Hospital Central de Maputo",
    "Age_Group": "35-44",
    "Registered_Samples": 1180,
    "Analysed_Samples": 1120,
    "Detected_Samples": 198,
    "Not_Detected_Samples": 922
  }
]

GET/tb/gx/summary/sample_types_by_month/

Sample types by month

Returns the distribution of samples by specimen type aggregated by month. Use this endpoint to track trends in the types of specimens submitted for GeneXpert testing over time.

Name
Month
Type
integer
Description
The month number (1-12).
Name
Month_Name
Type
string
Description
The name of the month.
Name
Year
Type
integer
Description
The year of the record.
Name
Sample_Type
Type
string
Description
The specimen type (e.g., "Sputum", "Feces", "Urine", "Blood", "Other").
Name
Total
Type
integer
Description
Total number of samples of this type in the month.

Request

GET

/tb/gx/summary/sample_types_by_month/

curl -G https://api.openldr.org.mz/tb/gx/summary/sample_types_by_month/ \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  --data-urlencode 'interval_dates=["2025-01-01","2025-12-31"]' \
  --data-urlencode "genexpert_result_type=Ultra 6 Cores"

Response

[
  {
    "Month": 1,
    "Month_Name": "January",
    "Year": 2025,
    "Sample_Type": "Sputum",
    "Total": 2340
  },
  {
    "Month": 1,
    "Month_Name": "January",
    "Year": 2025,
    "Sample_Type": "Feces",
    "Total": 185
  },
  {
    "Month": 1,
    "Month_Name": "January",
    "Year": 2025,
    "Sample_Type": "Urine",
    "Total": 120
  }
]

GET/tb/gx/summary/sample_types_by_facility_by_age/

Sample types by facility by age

Returns the distribution of samples by specimen type, grouped by requesting facility and disaggregated by age group. Use this endpoint for detailed analysis of specimen collection patterns across facilities and demographics.

Name
Requesting_Facility
Type
string
Description
Name of the health facility that requested the test.
Name
Sample_Type
Type
string
Description
The specimen type (e.g., "Sputum", "Feces", "Urine", "Blood", "Other").
Name
Age_Group
Type
string
Description
Age group label (e.g., "0-4", "5-14", "15-24", "25-34", "35-44", "45-54", "55-64", "65+").
Name
Total
Type
integer
Description
Total number of samples for this facility, type, and age group combination.

Request

GET

/tb/gx/summary/sample_types_by_facility_by_age/

curl -G https://api.openldr.org.mz/tb/gx/summary/sample_types_by_facility_by_age/ \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  --data-urlencode 'interval_dates=["2025-01-01","2025-12-31"]' \
  --data-urlencode "genexpert_result_type=Ultra 6 Cores"

Response

[
  {
    "Requesting_Facility": "CS Machava II",
    "Sample_Type": "Sputum",
    "Age_Group": "25-34",
    "Total": 145
  },
  {
    "Requesting_Facility": "CS Machava II",
    "Sample_Type": "Sputum",
    "Age_Group": "35-44",
    "Total": 132
  },
  {
    "Requesting_Facility": "CS Machava II",
    "Sample_Type": "Feces",
    "Age_Group": "0-4",
    "Total": 28
  }
]