Welcome to the Miri Africa API documentation. This guide provides information on how to use our RESTful API to retrieve environmental data from our network of devices.
Base URL: https://api.climateinafrica.com/api/
All API requests must be made over HTTPS.
To access the API, you must include a valid api_key in the query parameters of every request. You can obtain your API Key from your account dashboard.
This section outlines the available endpoints, their corresponding HTTP methods, and their intended purposes.
3.1. Get All Devices
GET /devices
This method gets a list of all the devices whose data an API can access.
Query Parameters:
api_key(required): Your unique API Key.
Sample Request:
curl https://api.climateinafrica.com/api/devices?api_key=YOUR_API_KEY
⠀Success Response (200 OK):
[
"CIA-005 (fWX9cXQLKEY)"
]
Note: The device ID (e.g., fWX9cXQLKEY) is the value of device to be used with the other endpoints.
3.2. Get Real-Time Data
GET /realtime-data
Retrieves real-time environmental data for a specific device or group of devices.
Query Parameters:
api_key(required): Your unique API Key.device(required): The device ID of the device or devices as a comma-separated list.
Sample Request:
curl https://api.climateinafrica.com/api/realtime-data?api_key=YOUR_API_KEY&device=fWX9cXQLKEY
Response (200 OK):
| Field | Type | Description |
|---|---|---|
| device_id | String | A unique identifier for the monitoring device. Example: 5PwDqeyU6x |
| device_name | String | The human-readable name of the device. Example: LASEPA-002 |
| place | String | The geographical location or site name of the device. Example: Itamaga-Ijede Ikorodu |
| type | String | Identifier for the device type. a - air device w - weather device |
| data | Object | The primary container for the data. (See Data Object Schema below) |
The data object contains all the environmental metrics and their change indicators.
| Field | Type | Description |
|---|---|---|
| active | Boolean | Status indicating if the device is currently active (true) or inactive (false). |
| aqi | String | Current Air Quality Index reading. |
| aqi_increase | String | Change in AQI relative to the last measurement (e.g., +1). |
| aqi_main_pollutant | String | The primary pollutant driving the current AQI reading. Example: PM2.5 |
| temperature | Integer | Current temperature reading in degrees Celsius (°C). |
| temperature_increase | String | Change in temperature relative to the last measurement. |
| humidity | String | Current relative humidity percentage (%). |
| humidity_increase | String | Change in humidity relative to the last measurement. |
| pressure | String | Current atmospheric pressure reading (e.g., in hPa). |
| noise | String | Current noise level reading (e.g., in dB). |
| noise_increase | String | Change in noise level. |
| solar | String | Current solar irradiance/radiation reading. |
| solar_peak | Number | The peak solar value recorded for the current period. |
| last_updated | String | Time since the device data was last updated. |
| last_aqi_updated_time | String | Time since the AQI value was last specifically calculated. |
| co2 | String | Current Carbon Dioxide (CO₂) concentration in parts per million(ppm). |
| co2_increase | String | Change in CO₂ concentration. |
| co | String | Current Carbon Monoxide (CO) concentration in ppm. |
| co_increase | String | Change in CO concentration. |
| nox | String | Current Nitrogen Oxide index (NOx). |
| nox_increase | String | Change in NOx. |
| o3 | String | Current Ozone (O3) concentration in parts per billion(ppb). |
| o3_increase | String | Change in O3 concentration. |
| so2 | String | Current Sulfur Dioxide (SO₂) concentration in ppm. |
| so2_increase | String | Change in SO₂ concentration. |
| ch20 | String | Current Formaldehyde (CH₂O) concentration in ppm. |
| ch20_increase | String | Change in CH₂O concentration. |
| ch4 | String | Current Methane (CH4O) concentration in ppm. |
| ch4_increase | String | Change in $CH4O concentration. |
| pmtwo | String | Current Particulate Matter 2.5 (PM2.5) concentration (μg/m^3). |
| pmtwo_increase | String | Change in PM2.5 concentration. |
| pmten | String | Current Particulate Matter 10(PM10) concentration (μg/m^3). |
| pmten_increase | String | Change in PM10 concentration. |
| voc | String | Current Volatile Organic Compounds index. |
| voc_increase | String | Change in VOC index. |
| daily | Object | Daily weather forecast data for the primary forecast day. (See Daily Object Schema below) |
| forecast_dates | Array of Objects | A chronological list of forecast dates. (See Forecast Dates Array below) |
| forecast_index | Array of Numbers | An array of indices corresponding to the forecast_dates. |
| hourly | Array of Objects | Detailed hourly forecast data. (See Hourly Array below) |
| Field | Type | Description |
|---|---|---|
| date | String | The full date and time string for the forecast day. Example: Thu, 04 Dec 2025 23:00:00 GMT |
| high | Number | The expected high temperature for the day. |
| low | Number | The expected low temperature for the day. |
An array of objects providing a short list of dates for navigation or summary display.
| Field | Type | Description |
|---|---|---|
| date | String | The day of the month. Example: 04 |
| day | String | The three-letter abbreviation for the day of the week. Example: Thu |
| month | String | The three-letter abbreviation for the month. Example: Dec |
An array of objects providing detailed metrics for a 24-hour period (and possibly crossing midnight).
| Field | Type | Description |
|---|---|---|
| date | String | The timestamp for the hourly reading (usually |
| eaqi_forecast | Number | The forecasted European Air Quality Index for that hour. |
| weather_code | String (Optional) | A specific code indicating a weather event/change at this time (used for non-hourly entries). Example: 11.0 |
{
data: {
active: true,
aqi: '67',
aqi_increase: '+1',
aqi_main_pollutant: 'PM2.5',
ch20: '0.010',
ch20_increase: '-0.02',
ch4: '0.00',
ch4_increase: '+0.0',
co: '3.00',
co2: '514',
co2_increase: '+8.76',
co_increase: '+0.0',
daily: { date: 'Thu, 04 Dec 2025 23:00:00 GMT', high: 31, low: 26 },
forecast_dates: [
{ "date": "04", "day": "Thu", "month": "Dec" },
{ "date": "05", "day": "Fri", "month": "Dec" },
{ "date": "06", "day": "Sat", "month": "Dec" },
{ "date": "07", "day": "Sun", "month": "Dec" },
{ "date": "08", "day": "Mon", "month": "Dec" }
],
forecast_index: [1, 2, 3, 4, 5],
hourly: [
{ "date": "08:00", "eaqi_forecast": 41, "i": 0 },
{ "date": "09:00", "eaqi_forecast": 41, "i": 1 },
{ "date": "10:00", "eaqi_forecast": 40, "i": 2 },
{ "date": "11:00", "eaqi_forecast": 41, "i": 3 },
{ "date": "12:00", "eaqi_forecast": 45, "i": 4 },
{ "date": "13:00", "eaqi_forecast": 48, "i": 5 },
{ "date": "14:00", "eaqi_forecast": 50, "i": 6 },
{ "date": "15:00", "eaqi_forecast": 48, "i": 7 },
{ "date": "16:00", "eaqi_forecast": 44, "i": 8 },
{ "date": "17:00", "eaqi_forecast": 45, "i": 9 },
{ "date": "17:29", "eaqi_forecast": 45, "weather_code": "11.0" },
{ "date": "18:00", "eaqi_forecast": 45, "i": 10 },
{ "date": "19:00", "eaqi_forecast": 45, "i": 11 },
{ "date": "20:00", "eaqi_forecast": 45, "i": 12 },
{ "date": "21:00", "eaqi_forecast": 45, "i": 13 },
{ "date": "22:00", "eaqi_forecast": 46, "i": 14 },
{ "date": "23:00", "eaqi_forecast": 46, "i": 15 },
{ "date": "00:00", "eaqi_forecast": 46, "i": 16 },
{ "date": "01:00", "eaqi_forecast": 46, "i": 17 },
{ "date": "02:00", "eaqi_forecast": 46, "i": 18 },
{ "date": "03:00", "eaqi_forecast": 46, "i": 19 },
{ "date": "04:00", "eaqi_forecast": 47, "i": 20 },
{ "date": "05:00", "eaqi_forecast": 48, "i": 21 },
{ "date": "05:44", "eaqi_forecast": 48, "weather_code": "10.0" },
{ "date": "06:00", "eaqi_forecast": 49, "i": 22 },
{ "date": "07:00", "eaqi_forecast": 51, "i": 23 }
],
humidity: '78.61',
humidity_increase: '+7',
last_aqi_updated_time: '14 hours ago',
last_updated: '13 hours ago',
noise: '73.04',
noise_increase: '73.04',
nox: '1.00',
nox_increase: '+0.16',
o3: '0.00',
o3_increase: '+0.0',
pmten: '22.54',
pmten_increase: '-4.88',
pmtwo: '12.95',
pmtwo_increase: '-4.38',
pressure: '1002',
so2: '0.00',
so2_increase: '+0.0',
solar: '29.41',
solar_peak: 0,
temperature: '29.14',
temperature_increase: '-1',
voc: '100',
voc_increase: '+18.85',
},
device_id: '5PwDqeyU6x',
device_name: 'LASEPA-002',
place: 'Itamaga-Ijede Ikorodu',
type: 'a',
},
]
Retrieves historical environmental data from a single device or multiple devices over a specific time period. This endpoint provides access to a rich dataset of past measurements, useful for trend analysis and reporting.
Endpoint: /api/air-data
Method: GET
The request must include the following query parameters:
| Parameter | Required | Type | Description | Example |
|---|---|---|---|---|
| api_key | Yes | String | Your unique authentication key. | api_key=api_key |
| device | Yes | String | The ID of the monitoring device to query. | device=5PwDqeyU6x |
| start-date | Yes | String | The starting date for the data query (Format: YYYY-MM-DD). | start-date=2025-12-01 |
| end-date | Yes | String | The ending date for the data query (Format: YYYY-MM-DD). | end-date=2025-12-02 |
| variables | Yes | String | A comma-separated list of data variables to retrieve. For a full list of available variables, see Available Variables below. | variables=temperature,humidity,aqi |
The table below lists all possible values for the required variables query parameter:
| Friendly Name | Variable Key |
|---|---|
| Temperature | temperature |
| Pressure | pressure |
| Humidity | humidity |
| Wind speed | wind_speed |
| Wind direction | wind_direction |
| Rain | rain |
| Solar Irradiance | solar_irradiance |
| Particulate Matter 2.5 | pmtwo |
| Particulate Matter 10 | pmten |
| Noise | noise |
| Air Quality Index | aqi |
| Carbon Monoxide Index | co_index |
| Carbon Dioxide Index | co2_index |
| Nitrogen Dioxide Index | nox_index |
| Sulfur Dioxide Index | so2_index |
| Methane Index | ch4_index |
| Formaldehyde Index | ch20_index |
| Volatile Organic Compounds Index | voc_index |
| Soil Moisture (Level 1-4) | soil_moisturel1, soil_moisturel2, soil_moisturel3, soil_moisturel4 |
| Soil Temperature (Level 1-4) | soil_temperaturel1, soil_temperaturel2, soil_temperaturel3, soil_temperaturel4 |
The response is an array containing a single object with metadata and the historical data payload.
| Field | Type | Description |
|---|---|---|
| device_id | String | A unique identifier for the monitoring device. |
| device_name | String | The human-readable name of the device. |
| place | String | The geographical location or site name of the device. |
| type | String | A classification type for the device or data. |
| data | Array of Objects | The array containing all historical records. (See Time-Series Record Schema below) |
Each object within the data array represents a single, hourly measurement point. The fields included are dynamic, based on the variables requested in the API call.
| Field | Type | Description |
|---|---|---|
| date_added | String | The UTC timestamp for the measurement point (Format: YYYY-MM-DD HH:MM:SSZ). |
| aqi | Number | Air Quality Index value. (Present only if aqi was requested) |
| humidity | Number | Relative humidity percentage. (Present only if humidity was requested) |
| temperature | Number | Temperature reading. (Present only if temperature was requested) |
| ... (Other Variables) | Number | Any other requested environmental metric. |
Sample Request:
curl https://api.climateinafrica.com/api/air-data?api_key=YOUR_API_KEY&device=fWX9cXQLKEY&variables=temperature,humidity&start-date=2025-08-01&end-date=2025-08-31
⠀Example:
[
{
"data": [
{
"aqi": 37,
"date_added": "2025-08-31 10:00:00Z",
"humidity": 20.0,
"temperature": 30.0
},
...,
...,
{
"aqi": 32.0,
"date_added": "2025-08-01 23:00:00Z",
"humidity": 15.0,
"temperature": 27
}
],
"device_id": "fWX9cXQLKEY",
"device_name": "device-ce9ffd",
"place": "Victoria Garden City",
"type": "a"
}
]
Our API uses standard HTTP status codes to indicate the success or failure of a request.
- 400 Bad Request: The request body or parameters are invalid.
- 401 Unauthorized: Authentication failed due to an invalid or missing api_key.
- 404 Not Found: The requested resource (e.g., a device) could not be found.