MENU navbar-image

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:

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"
}
 

Request      

GET api/sensors/{sensor_id}/export

Headers

x-api-key        

Example: {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

sensor_id   string     

The ID of the sensor. Example: architecto

Query Parameters

from   string     

Start of the range (inclusive). ISO-8601 or Unix timestamp (s or ms). Example: 2025-10-01T00:00:00Z

to   string  optional    

End of the range (inclusive). ISO-8601 or Unix timestamp (s or ms). Defaults to now. Example: 1730332799000

agg_type   string     

The aggregation level. One of: raw, hour, day. Example: hour

Body Parameters

from   string     

Example: architecto

to   string  optional    

Example: architecto

agg_type   string     

Example: hour

Must be one of:
  • raw
  • hour
  • day

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"
 

Request      

GET api/sensors/{sensor_id}/latest

Headers

x-api-key        

Example: {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

sensor_id   string     

The ID of the sensor. Example: architecto

sensor   string     

The sensor device ID. Example: SEN-1234567890

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."
}
 

Request      

GET api/sensors/{sensor_id}/rain/latest

Headers

x-api-key        

Example: {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

sensor_id   string     

The ID of the sensor. Example: architecto

sensor   string     

The sensor device ID. Example: SEN-1234567890

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."
}
 

Request      

GET api/sensors/{sensor_id}/rain/export

Headers

x-api-key        

Example: {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

sensor_id   string     

The ID of the sensor. Example: architecto

Query Parameters

from   string  optional    

Start of the range (inclusive), ISO-8601. Defaults to 24 hours ago. Example: 2026-11-05T00:00:00Z

to   string  optional    

End of the range (inclusive), ISO-8601. Defaults to now. Example: 2026-11-05T23:59:59Z

limit   integer  optional    

Maximum number of rows, 1..500. Default: 100. Example: 500

after_id   string  optional    

Return rows with a larger observation ID. When present, date filters are ignored. Example: 2449

kind   string  optional    

Optional event filter: rain_started, status, rain_summary, rain_ended, or sensor_fault. Example: rain_summary

Body Parameters

from   string  optional    

Example: architecto

to   string  optional    

Example: architecto

limit   integer  optional    

Must be between 1 and 500. Example: 2

after_id   integer  optional    

Must be at least 0. Example: 84

kind   string  optional    

Example: rain_ended

Must be one of:
  • rain_started
  • status
  • rain_summary
  • rain_ended
  • sensor_fault