Introduction
This documentation aims to provide all the information you need to work with our API.
<aside>As you scroll, you'll see code examples for working with the API in different programming languages in the dark area to the right (or as part of the content on mobile).
You can switch the language used with the tabs at the top right (or from the nav menu at the top left on mobile).</aside>
Authenticating requests
To authenticate requests, include a x-api-key header with the value "{YOUR_AUTH_KEY}".
All authenticated endpoints are marked with a requires authentication badge in the documentation below.
You can retrieve your token by visiting your dashboard and clicking Generate API token.
Sensors
Export sensor data
requires authentication
Export data from a sensor. Only sensors you own (via its hub) or sensors marked as public can be exported.
Dates: from and to accept ISO-8601 datetime strings (e.g. 2025-10-31T12:00:00Z) or Unix timestamps
(seconds or milliseconds; ms auto-detected by length). If to is omitted it defaults to "now". All processing is in UTC.
from must be before (or equal to) to.
Aggregation shapes:
raw: an array of raw measurements with fields:observed_at(ISO-8601),temperature_c,humidity_pct,pressure_hpa,battery_pct, nullable integerbattery_mv(millivolts), nullable integerbattery_type(0 unknown, 1 Li-ion, 2 LiFePO4, 3 NiMH, 4 alkaline), and nullable booleancharging.hour: grouped by day, then hour (0-23). For each metric you get{ avg, min, max }.day: an array; each element is an object keyed byYYYY-MM-DD, whose value contains per-metric{ avg, min, max }.
Example request:
curl --request GET \
--get "https://weather-guardian.com/api/sensors/architecto/export?from=2025-10-01T00%3A00%3A00Z&to=1730332799000&agg_type=hour" \
--header "x-api-key: {YOUR_AUTH_KEY}" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data "{
\"from\": \"architecto\",
\"to\": \"architecto\",
\"agg_type\": \"hour\"
}"
const url = new URL(
"https://weather-guardian.com/api/sensors/architecto/export"
);
const params = {
"from": "2025-10-01T00:00:00Z",
"to": "1730332799000",
"agg_type": "hour",
};
Object.keys(params)
.forEach(key => url.searchParams.append(key, params[key]));
const headers = {
"x-api-key": "{YOUR_AUTH_KEY}",
"Content-Type": "application/json",
"Accept": "application/json",
};
let body = {
"from": "architecto",
"to": "architecto",
"agg_type": "hour"
};
fetch(url, {
method: "GET",
headers,
body: JSON.stringify(body),
}).then(response => response.json());Example response (200, raw):
{
"ok": true,
"geohash": "gcw2mn3",
"data": [
{
"observed_at": "2025-10-31T12:34:56Z",
"pressure_hpa": 1013.2,
"temperature_c": 19.8,
"humidity_pct": 62.1
},
{
"observed_at": "2025-10-31T12:35:56Z",
"pressure_hpa": 1013.1,
"temperature_c": 19.9,
"humidity_pct": 61.8
}
]
}
Example response (200, hour):
{
"ok": true,
"geohash": "gcw2mn3",
"data": {
"2025-10-31": {
"hours": {
"12": {
"temperature": {
"avg": 19.4,
"min": 18.9,
"max": 20.1
},
"humidity": {
"avg": 61.7,
"min": 59.2,
"max": 64
},
"pressure": {
"avg": 1012.9,
"min": 1012.4,
"max": 1013.5
}
},
"13": {
"temperature": {
"avg": 19.1,
"min": 18.6,
"max": 19.8
},
"humidity": {
"avg": 62.3,
"min": 60.1,
"max": 64.2
},
"pressure": {
"avg": 1012.6,
"min": 1012.1,
"max": 1013
}
}
}
}
}
}
Example response (200, day):
{
"ok": true,
"geohash": "gcw2mn3",
"data": [
{
"2025-10-30": {
"temperature": {
"avg": 18.7,
"min": 16.9,
"max": 20.8
},
"humidity": {
"avg": 63.2,
"min": 54,
"max": 71.4
},
"pressure": {
"avg": 1014.1,
"min": 1009.8,
"max": 1017.2
}
}
},
{
"2025-10-31": {
"temperature": {
"avg": 18.1,
"min": 17.3,
"max": 19.4
},
"humidity": {
"avg": 64.5,
"min": 58.2,
"max": 69.9
},
"pressure": {
"avg": 1013,
"min": 1010.1,
"max": 1015
}
}
}
]
}
Example response (403):
{
"ok": false,
"message": "unauthorised"
}
Example response (422):
{
"message": "from date cannot be null"
}
Example response (422):
{
"message": "unable to parse from date"
}
Example response (422):
{
"message": "unable to parse to date"
}
Example response (422):
{
"message": "to date must be after from date"
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
Export latest sensor measurement
requires authentication
Returns the latest measurement for a single sensor. Only sensors you own (via its hub) or sensors marked as public can be queried.
The response payload is the MeasurementResource output for the sensor's lastMeasurement.
Example request:
curl --request GET \
--get "https://weather-guardian.com/api/sensors/architecto/latest" \
--header "x-api-key: {YOUR_AUTH_KEY}" \
--header "Content-Type: application/json" \
--header "Accept: application/json"const url = new URL(
"https://weather-guardian.com/api/sensors/architecto/latest"
);
const headers = {
"x-api-key": "{YOUR_AUTH_KEY}",
"Content-Type": "application/json",
"Accept": "application/json",
};
fetch(url, {
method: "GET",
headers,
}).then(response => response.json());Example response (200, ok):
{
"observed_at": "2026-01-10T00:00:00Z",
"pressure_hpa": 1013.2,
"temperature_c": 19.8,
"humidity_pct": 62.1,
"battery_pct": 87,
"charging": null
}
Example response (200, no_measurement):
null
Example response (403):
{
"ok": false,
"message": "unauthorised"
}
Example response (422):
"Data can only be exported from sensors"
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
Export the latest rain sensor state
requires authentication
Returns the current rain state and its latest observation using the
dashboard API token (x-api-key). A stale observation remains available
under rain.latest_observation, while rain.state becomes unknown.
Example request:
curl --request GET \
--get "https://weather-guardian.com/api/sensors/architecto/rain/latest" \
--header "x-api-key: {YOUR_AUTH_KEY}" \
--header "Content-Type: application/json" \
--header "Accept: application/json"const url = new URL(
"https://weather-guardian.com/api/sensors/architecto/rain/latest"
);
const headers = {
"x-api-key": "{YOUR_AUTH_KEY}",
"Content-Type": "application/json",
"Accept": "application/json",
};
fetch(url, {
method: "GET",
headers,
}).then(response => response.json());Example response (200):
{
"ok": true,
"device_id": "SEN-1234567890",
"sensor_type": "rain",
"rain": {
"state": "dry",
"reported_state": "dry",
"fresh": true,
"observed_at": "2026-11-05T09:55:04.667Z",
"latest_observation": {
"id": 2449,
"device_id": "SEN-1234567890",
"observed_at": "2026-11-05T09:55:04.667Z",
"rain": {
"kind": "rain_summary",
"state": "dry"
}
}
}
}
Example response (403):
{
"ok": false,
"message": "unauthorised"
}
Example response (422):
{
"ok": false,
"message": "Sensor is not reporting rain data."
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
Export rain observations
requires authentication
Export rain events and summaries using the dashboard API token (x-api-key).
Access follows the sensor export rules: the token owner must own a private
sensor; public sensors can be exported by any valid token. Released devices
and devices currently reporting a non-rain sensor type are not exported.
A first request may use from and to to select an observation-time range.
Subsequent requests can use after_id to fetch only newer rows. In cursor
mode, the subscription history window still applies and date filters are ignored.
Rows are returned in ascending ID order; continue from next_after_id while
has_more is true.
Example request:
curl --request GET \
--get "https://weather-guardian.com/api/sensors/architecto/rain/export?from=2026-11-05T00%3A00%3A00Z&to=2026-11-05T23%3A59%3A59Z&limit=500&after_id=2449&kind=rain_summary" \
--header "x-api-key: {YOUR_AUTH_KEY}" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data "{
\"from\": \"architecto\",
\"to\": \"architecto\",
\"limit\": 2,
\"after_id\": 84,
\"kind\": \"rain_ended\"
}"
const url = new URL(
"https://weather-guardian.com/api/sensors/architecto/rain/export"
);
const params = {
"from": "2026-11-05T00:00:00Z",
"to": "2026-11-05T23:59:59Z",
"limit": "500",
"after_id": "2449",
"kind": "rain_summary",
};
Object.keys(params)
.forEach(key => url.searchParams.append(key, params[key]));
const headers = {
"x-api-key": "{YOUR_AUTH_KEY}",
"Content-Type": "application/json",
"Accept": "application/json",
};
let body = {
"from": "architecto",
"to": "architecto",
"limit": 2,
"after_id": 84,
"kind": "rain_ended"
};
fetch(url, {
method: "GET",
headers,
body: JSON.stringify(body),
}).then(response => response.json());Example response (200):
{
"ok": true,
"device_id": "SEN-1234567890",
"sensor_type": "rain",
"rain": {
"state": "dry"
},
"data": [
{
"id": 2449,
"device_id": "SEN-1234567890",
"observed_at": "2026-11-05T09:55:04.667Z",
"received_at": "2026-11-05T09:55:06.469Z",
"observation_time_known": true,
"rain": {
"kind": "rain_summary",
"state": "dry"
}
}
],
"has_more": false,
"next_after_id": 2449
}
Example response (403):
{
"ok": false,
"message": "unauthorised"
}
Example response (422):
{
"ok": false,
"message": "Use a range of at most 12 months."
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.