Add API endpoint to fetch historical temperature data from sensors

[adrienjoly]

Current Situation

The SwitchBot API currently only provides access to the current temperature reading from sensors via the GET /v1.1/devices/{deviceId}/status endpoint. There is no way to retrieve historical temperature data over a specified time period, such as the last 4 hours.

Developers who need to track temperature trends are forced to implement their own workarounds:

• Polling the status endpoint repeatedly and maintaining their own database
• Implementing custom logging of webhook events
• Managing their own infrastructure for data storage and retrieval

Proposed Change

Add a new API endpoint to retrieve historical temperature and humidity data for a given device over a specified time range.

Proposed endpoint:

GET /v1.1/devices/{deviceId}/history

Query parameters:

• startTime (required): Unix timestamp (milliseconds) for the start of the time range
• endTime (required): Unix timestamp (milliseconds) for the end of the time range
• interval (optional): Data point interval in seconds (e.g., 60 for 1-minute intervals, default 300 for 5-minute intervals)

Example request:

GET https://api.switch-bot.com/v1.1/devices/C271111EC0AB/history?startTime=1692460800000&endTime=1692474200000&interval=60

Expected response:

{
    "statusCode": 100,
    "message": "success",
    "body": {
        "deviceId": "C271111EC0AB",
        "deviceType": "Meter",
        "data": [
            {
                "timestamp": 1692460800000,
                "temperature": 22.5,
                "humidity": 45
            },
            {
                "timestamp": 1692460860000,
                "temperature": 22.6,
                "humidity": 44
            }
        ]
    }
}

Additional Context

Benefits

• Eliminates the need for developers to implement custom polling and data storage
• Reduces API call load compared to frequent status endpoint requests
• Enables analytics, trend analysis, and data visualization features
• Improves developer experience and ease of adoption

Affected Devices

This feature should apply to all temperature and humidity sensors in the SwitchBot ecosystem:

• Meter
• Meter Plus (JP/US)
• Outdoor Meter
• Meter Pro
• Meter Pro (CO2 Monitor)
• Weather Station
• Hub 2
• Hub 3
• Any future devices that report temperature/humidity data