Gridova Logo
API Reference

REST API

Complete REST API documentation with examples in cURL, JavaScript, and Dart

ESP32 Sensor Data

Read electricity sensor data from a specific room.

GET/api/sensor

Retrieves current sensor readings including voltage, current, power, energy, frequency, and power factor.

Query Parameters

ParameterTypeRequiredDescription
room_idstringOptionalFilter by room ID

Example Request

curl -X GET "http://192.168.1.100/api/sensor" \
  -H "Accept: application/json"

Response

200 OKjson
{
  "success": true,
  "data": {
    "voltage": 220.5,
    "current": 2.45,
    "power": 540.2,
    "energy": 12.5,
    "frequency": 50.0,
    "powerFactor": 0.98,
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

Control Relay

Turn relay on or off to control power remotely.

POST/api/relay/control

Controls the relay module to switch power on or off for a specific room.

Request Body

FieldTypeRequiredDescription
channelintegerRequiredRelay channel (1-4)
statestringRequired"on" or "off"

Example Request

curl -X POST "http://192.168.1.100/api/relay/control" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": 1,
    "state": "on"
  }'

Response

200 OKjson
{
  "success": true,
  "data": {
    "channel": 1,
    "state": "on",
    "timestamp": "2024-01-15T10:35:00Z"
  },
  "message": "Relay control successful"
}

Safety Notice

Always ensure the connected device can be safely switched on/off remotely. Implement proper safeguards for critical appliances.

Get Historical Data

Retrieve historical sensor data for analysis and reporting.

GET/api/sensor/history

Returns historical sensor readings with optional date range filtering.

Query Parameters

ParameterTypeRequiredDescription
startDatestringOptionalStart date (ISO 8601)
endDatestringOptionalEnd date (ISO 8601)
limitintegerOptionalMax records (default: 100)

Example Request

curl -X GET "http://192.168.1.100/api/sensor/history?startDate=2024-01-01&endDate=2024-01-15&limit=50" \
  -H "Accept: application/json"

Response

200 OKjson
{
  "success": true,
  "data": [
    {
      "timestamp": "2024-01-15T10:00:00Z",
      "voltage": 220.3,
      "current": 2.40,
      "power": 528.7,
      "energy": 12.3,
      "frequency": 50.0,
      "powerFactor": 0.97
    },
    {
      "timestamp": "2024-01-15T10:05:00Z",
      "voltage": 220.5,
      "current": 2.45,
      "power": 540.2,
      "energy": 12.5,
      "frequency": 50.0,
      "powerFactor": 0.98
    }
    // ... more records
  ],
  "meta": {
    "total": 50,
    "startDate": "2024-01-01",
    "endDate": "2024-01-15"
  }
}

Backend API Endpoints

Additional endpoints for the main backend server.

List Rooms

GET/api/rooms
curl -X GET "https://api.gridova.com/api/rooms" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Error Handling

Implement proper error handling in your application:

async function getSensorDataSafely() {
  try {
    const response = await fetch('http://192.168.1.100/api/sensor');
    
    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }
    
    const data = await response.json();
    
    if (!data.success) {
      throw new Error(data.error?.message || 'Unknown error');
    }
    
    return data.data;
  } catch (error) {
    console.error('Failed to fetch sensor data:', error);
    // Handle error appropriately (show notification, retry, etc.)
    throw error;
  }
}

Complete API Reference

For WebSocket real-time communication and data models, see the WebSocket API and Data Models pages.