Quickstart
This guide will get you up and running with the OpenLDR Analytics API. You'll learn how to authenticate, make your first request, and understand the common query parameters.
Authentication
All API endpoints require authentication via a JWT Bearer token. To obtain a token, send a POST request to the /auth/login endpoint with your credentials.
The response will include an access_token that you must include in the Authorization header of all subsequent requests.
- Name
user_name- Type
- string
- Description
Your OpenLDR account username.
- Name
password- Type
- string
- Description
Your OpenLDR account password.
Request
curl -X POST https://api.openldr.org.mz/auth/login \
-H "Content-Type: application/json" \
-d '{
"user_name": "your_username",
"password": "your_password"
}'
Response
{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
Making your first request
Once you have your access token, you can make authenticated requests to any API endpoint. Let's start by fetching HIV Viral Load tested samples data.
Include the token in the Authorization header as a Bearer token. The API will return JSON data that you can use in your applications.
Request
curl https://api.openldr.org.mz/hiv/vl/laboratories/tested_samples/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
Response
[
{
"year": 2025,
"month": 1,
"month_name": "January",
"total": 12453,
"suppressed": 10287,
"not_suppressed": 2166,
"testing_facility": "Maputo Central Hospital"
},
{
"year": 2025,
"month": 2,
"month_name": "February",
"total": 11892,
"suppressed": 9841,
"not_suppressed": 2051,
"testing_facility": "Maputo Central Hospital"
}
]
Common parameters
Most API endpoints accept a set of common query parameters for filtering and aggregating data. These parameters allow you to narrow down results by date range, geographic location, and level of detail.
- Name
interval_dates- Type
- JSON array
- Description
Date range filter as a JSON array with two dates in
YYYY-MM-DDformat:["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
curl -G https://api.openldr.org.mz/hiv/vl/laboratories/tested_samples/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
--data-urlencode 'interval_dates=["2025-01-01","2025-12-31"]' \
--data-urlencode "province=Maputo Cidade" \
--data-urlencode "province=Gaza" \
--data-urlencode "facility_type=district" \
--data-urlencode "disaggregation=True"
Error handling
If you receive a 401 Unauthorized response, your JWT token may have expired. Request a new token by calling the /auth/login endpoint again.
The API uses standard HTTP status codes to indicate the success or failure of a request.
| Status Code | Description |
|---|---|
200 | Success — The request was processed successfully. |
401 | Unauthorized — The JWT token is missing, invalid, or expired. |
500 | Server Error — An unexpected error occurred on the server. |
Error response
{
"error": "Unauthorized",
"message": "Missing or invalid authentication token.",
"status_code": 401
}