TB GeneXpert - Laboratory

Laboratory-level endpoints for TB GeneXpert analytics. These endpoints provide testing data grouped by testing facility (laboratory), including sample counts, specimen types, rejection analysis, drug resistance profiling, and turnaround time metrics.

Common parameters

Most laboratory endpoints accept the following query parameters for filtering and aggregating data.

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

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

GET/tb/gx/laboratories/registered_samples/

Registered samples

Returns the total number of registered GeneXpert samples grouped by testing laboratory.

Name
Testing_Facility
Type
string
Description
The name of the testing laboratory.
Name
Registered_Samples
Type
integer
Description
Total number of registered samples at this laboratory.

Request

GET

/tb/gx/laboratories/registered_samples/

curl -G https://api.openldr.org.mz/tb/gx/laboratories/registered_samples/ \
  -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
  },
  {
    "Testing_Facility": "Hospital Provincial de Nampula",
    "Registered_Samples": 3870
  }
]

GET/tb/gx/laboratories/tested_samples/

Tested samples

Returns the number of GeneXpert samples tested per laboratory, with detected and not detected breakdowns.

Name
Testing_Facility
Type
string
Description
The name of the testing 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.

Request

GET

/tb/gx/laboratories/tested_samples/

curl -G https://api.openldr.org.mz/tb/gx/laboratories/tested_samples/ \
  -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",
    "Analysed_Samples": 4980,
    "Detected_Samples": 747,
    "Not_Detected_Samples": 4233
  },
  {
    "Testing_Facility": "Hospital Provincial de Nampula",
    "Analysed_Samples": 3650,
    "Detected_Samples": 548,
    "Not_Detected_Samples": 3102
  }
]

GET/tb/gx/laboratories/registered_samples_by_month/

Registered samples by month

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

Name
Month
Type
integer
Description
The month number (1-12).
Name
Month_Name
Type
string
Description
The full 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 that month.

Request

GET

/tb/gx/laboratories/registered_samples_by_month/

curl -G https://api.openldr.org.mz/tb/gx/laboratories/registered_samples_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
  },
  {
    "Month": 2,
    "Month_Name": "February",
    "Year": 2025,
    "Registered_Samples": 2640
  }
]

GET/tb/gx/laboratories/tested_samples_by_month/

Tested samples by month

Returns the number of GeneXpert samples tested per month, with detected and not detected breakdowns.

Name
Month
Type
integer
Description
The month number (1-12).
Name
Month_Name
Type
string
Description
The full name of the month.
Name
Year
Type
integer
Description
The year of the record.
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.

Request

GET

/tb/gx/laboratories/tested_samples_by_month/

curl -G https://api.openldr.org.mz/tb/gx/laboratories/tested_samples_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,
    "Analysed_Samples": 2650,
    "Detected_Samples": 398,
    "Not_Detected_Samples": 2252
  },
  {
    "Month": 2,
    "Month_Name": "February",
    "Year": 2025,
    "Analysed_Samples": 2480,
    "Detected_Samples": 362,
    "Not_Detected_Samples": 2118
  }
]

GET/tb/gx/laboratories/tested_samples_by_sample_types/

Tested samples by sample types

Returns tested sample counts grouped by laboratory and specimen type.

Name
Testing_Facility
Type
string
Description
The name of the testing laboratory.
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 tested at the laboratory.

Request

GET

/tb/gx/laboratories/tested_samples_by_sample_types/

curl -G https://api.openldr.org.mz/tb/gx/laboratories/tested_samples_by_sample_types/ \
  -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",
    "Sample_Type": "Sputum",
    "Total": 4120
  },
  {
    "Testing_Facility": "Hospital Central de Maputo",
    "Sample_Type": "Feces",
    "Total": 345
  }
]

GET/tb/gx/laboratories/tested_samples_by_sample_types_by_month/

Tested samples by sample types by month

Returns tested sample counts grouped by specimen type and aggregated by month.

Name
Month
Type
integer
Description
The month number (1-12).
Name
Month_Name
Type
string
Description
The full 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/laboratories/tested_samples_by_sample_types_by_month/

curl -G https://api.openldr.org.mz/tb/gx/laboratories/tested_samples_by_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
  }
]

GET/tb/gx/laboratories/rejected_samples/

Rejected samples

Returns the total number of rejected GeneXpert samples grouped by testing laboratory.

Name
Testing_Facility
Type
string
Description
The name of the testing laboratory.
Name
Rejected_Samples
Type
integer
Description
Total number of rejected samples at this laboratory.

Request

GET

/tb/gx/laboratories/rejected_samples/

curl -G https://api.openldr.org.mz/tb/gx/laboratories/rejected_samples/ \
  -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",
    "Rejected_Samples": 312
  },
  {
    "Testing_Facility": "Hospital Provincial de Nampula",
    "Rejected_Samples": 187
  }
]

GET/tb/gx/laboratories/rejected_samples_by_month/

Rejected samples by month

Returns the number of rejected GeneXpert samples aggregated by month.

Name
Month
Type
integer
Description
The month number (1-12).
Name
Month_Name
Type
string
Description
The full name of the month.
Name
Year
Type
integer
Description
The year of the record.
Name
Rejected_Samples
Type
integer
Description
Total number of rejected samples in the month.

Request

GET

/tb/gx/laboratories/rejected_samples_by_month/

curl -G https://api.openldr.org.mz/tb/gx/laboratories/rejected_samples_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,
    "Rejected_Samples": 145
  },
  {
    "Month": 2,
    "Month_Name": "February",
    "Year": 2025,
    "Rejected_Samples": 118
  }
]

GET/tb/gx/laboratories/rejected_samples_by_reason/

Rejected samples by reason

Returns rejected sample counts grouped by laboratory and rejection reason.

Name
Testing_Facility
Type
string
Description
The name of the testing laboratory.
Name
Rejection_Reason
Type
string
Description
The reason for sample rejection.
Name
Rejected_Samples
Type
integer
Description
Number of samples rejected for this reason at this laboratory.

Request

GET

/tb/gx/laboratories/rejected_samples_by_reason/

curl -G https://api.openldr.org.mz/tb/gx/laboratories/rejected_samples_by_reason/ \
  -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",
    "Rejection_Reason": "Insufficient sample volume",
    "Rejected_Samples": 87
  },
  {
    "Testing_Facility": "Hospital Central de Maputo",
    "Rejection_Reason": "Sample leaked during transport",
    "Rejected_Samples": 45
  }
]

GET/tb/gx/laboratories/rejected_samples_by_reason_by_month/

Rejected samples by reason by month

Returns rejected sample counts grouped by rejection reason and aggregated by month.

Name
Month
Type
integer
Description
The month number (1-12).
Name
Month_Name
Type
string
Description
The full name of the month.
Name
Year
Type
integer
Description
The year of the record.
Name
Rejection_Reason
Type
string
Description
The reason for sample rejection.
Name
Rejected_Samples
Type
integer
Description
Number of samples rejected for this reason in the month.

Request

GET

/tb/gx/laboratories/rejected_samples_by_reason_by_month/

curl -G https://api.openldr.org.mz/tb/gx/laboratories/rejected_samples_by_reason_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,
    "Rejection_Reason": "Insufficient sample volume",
    "Rejected_Samples": 32
  },
  {
    "Month": 1,
    "Month_Name": "January",
    "Year": 2025,
    "Rejection_Reason": "Sample leaked during transport",
    "Rejected_Samples": 18
  }
]

GET/tb/gx/laboratories/tested_samples_by_drug_type/

Tested samples by drug type

Returns tested sample counts grouped by laboratory and drug resistance type. Drug types include Rifampicin (for Ultra cartridges) and extended resistance markers (Isoniazid, Fluoroquinolone, Ethionamide, Amikacin) for XDR cartridges.

Name
Testing_Facility
Type
string
Description
The name of the testing laboratory.
Name
Drug_Type
Type
string
Description
The drug being tested for resistance (e.g., "Rifampicin", "Isoniazid", "Fluoroquinolona", "Ethionamide", "Amikacin").
Name
Resistant
Type
integer
Description
Number of samples with resistance detected.
Name
Susceptible
Type
integer
Description
Number of samples with no resistance detected.
Name
Indeterminate
Type
integer
Description
Number of samples with indeterminate resistance results.

Request

GET

/tb/gx/laboratories/tested_samples_by_drug_type/

curl -G https://api.openldr.org.mz/tb/gx/laboratories/tested_samples_by_drug_type/ \
  -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",
    "Drug_Type": "Rifampicin",
    "Resistant": 42,
    "Susceptible": 685,
    "Indeterminate": 20
  },
  {
    "Testing_Facility": "Hospital Provincial de Nampula",
    "Drug_Type": "Rifampicin",
    "Resistant": 31,
    "Susceptible": 502,
    "Indeterminate": 15
  }
]

GET/tb/gx/laboratories/tested_samples_by_drug_type_by_month/

Tested samples by drug type by month

Returns tested sample counts grouped by drug resistance type and aggregated by month.

Name
Month
Type
integer
Description
The month number (1-12).
Name
Month_Name
Type
string
Description
The full name of the month.
Name
Year
Type
integer
Description
The year of the record.
Name
Drug_Type
Type
string
Description
The drug being tested for resistance.
Name
Resistant
Type
integer
Description
Number of resistant samples in the month.
Name
Susceptible
Type
integer
Description
Number of susceptible samples in the month.
Name
Indeterminate
Type
integer
Description
Number of indeterminate samples in the month.

Request

GET

/tb/gx/laboratories/tested_samples_by_drug_type_by_month/

curl -G https://api.openldr.org.mz/tb/gx/laboratories/tested_samples_by_drug_type_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,
    "Drug_Type": "Rifampicin",
    "Resistant": 12,
    "Susceptible": 375,
    "Indeterminate": 11
  },
  {
    "Month": 2,
    "Month_Name": "February",
    "Year": 2025,
    "Drug_Type": "Rifampicin",
    "Resistant": 9,
    "Susceptible": 342,
    "Indeterminate": 8
  }
]

GET/tb/gx/laboratories/trl_samples_by_lab_in_days/

TRL samples by lab in days

Returns the distribution of samples across turnaround time (TAT) day ranges, grouped by testing laboratory. TAT is measured in four segments: collection to reception (colheita to recepcao), reception to registration (recepcao to registo), registration to analysis (registo to analise), and analysis to validation (analise to validacao).

Name
Testing_Facility
Type
string
Description
The name of the testing laboratory.
Name
colheita_recepcao
Type
float
Description
Average days from sample collection to laboratory reception.
Name
recepcao_registo
Type
float
Description
Average days from laboratory reception to registration.
Name
registo_analise
Type
float
Description
Average days from registration to analysis.
Name
analise_validacao
Type
float
Description
Average days from analysis to result validation.

Request

GET

/tb/gx/laboratories/trl_samples_by_lab_in_days/

curl -G https://api.openldr.org.mz/tb/gx/laboratories/trl_samples_by_lab_in_days/ \
  -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",
    "colheita_recepcao": 2.3,
    "recepcao_registo": 0.4,
    "registo_analise": 0.8,
    "analise_validacao": 0.2
  },
  {
    "Testing_Facility": "Hospital Provincial de Nampula",
    "colheita_recepcao": 3.1,
    "recepcao_registo": 0.6,
    "registo_analise": 1.2,
    "analise_validacao": 0.3
  }
]

GET/tb/gx/laboratories/trl_samples_by_lab_in_days_by_month/

TRL samples by lab in days by month

Returns the TAT segment averages aggregated by month.

Name
Month
Type
integer
Description
The month number (1-12).
Name
Month_Name
Type
string
Description
The full name of the month.
Name
Year
Type
integer
Description
The year of the record.
Name
colheita_recepcao
Type
float
Description
Average days from sample collection to laboratory reception.
Name
recepcao_registo
Type
float
Description
Average days from laboratory reception to registration.
Name
registo_analise
Type
float
Description
Average days from registration to analysis.
Name
analise_validacao
Type
float
Description
Average days from analysis to result validation.

Request

GET

/tb/gx/laboratories/trl_samples_by_lab_in_days_by_month/

curl -G https://api.openldr.org.mz/tb/gx/laboratories/trl_samples_by_lab_in_days_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,
    "colheita_recepcao": 2.5,
    "recepcao_registo": 0.5,
    "registo_analise": 0.9,
    "analise_validacao": 0.2
  },
  {
    "Month": 2,
    "Month_Name": "February",
    "Year": 2025,
    "colheita_recepcao": 2.2,
    "recepcao_registo": 0.4,
    "registo_analise": 0.7,
    "analise_validacao": 0.2
  }
]

GET/tb/gx/laboratories/trl_samples_avg_by_days/

TRL samples avg by days

Returns the distribution of samples grouped by total turnaround time day ranges, broken down by testing laboratory. Useful for monitoring the percentage of samples processed within target timeframes.

Name
Testing_Facility
Type
string
Description
The name of the testing laboratory.
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

/tb/gx/laboratories/trl_samples_avg_by_days/

curl -G https://api.openldr.org.mz/tb/gx/laboratories/trl_samples_avg_by_days/ \
  -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",
    "less_7": 3840,
    "between_7_15": 780,
    "between_16_21": 245,
    "greater_21": 115
  },
  {
    "Testing_Facility": "Hospital Provincial de Nampula",
    "less_7": 2650,
    "between_7_15": 620,
    "between_16_21": 230,
    "greater_21": 150
  }
]

GET/tb/gx/laboratories/trl_samples_avg_by_days_by_month/

TRL samples avg by days by month

Returns the distribution of samples grouped by total turnaround time day ranges, aggregated by month.

Name
Month
Type
integer
Description
The month number (1-12).
Name
Month_Name
Type
string
Description
The full name of the month.
Name
Year
Type
integer
Description
The year of the record.
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

/tb/gx/laboratories/trl_samples_avg_by_days_by_month/

curl -G https://api.openldr.org.mz/tb/gx/laboratories/trl_samples_avg_by_days_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,
    "less_7": 1920,
    "between_7_15": 450,
    "between_16_21": 180,
    "greater_21": 100
  },
  {
    "Month": 2,
    "Month_Name": "February",
    "Year": 2025,
    "less_7": 1850,
    "between_7_15": 410,
    "between_16_21": 145,
    "greater_21": 75
  }
]