telemetry api

Telemetry API Documentation

Complete API reference for telemetry data management

Overview

The Telemetry API provides comprehensive functionality for collecting, storing, and retrieving time-series telemetry data from IoT devices. This API supports high-frequency data ingestion, efficient querying, and real-time data streaming.

Base Endpoint

/api/v1/telemetry/

Authentication

All Telemetry API endpoints require JWT authentication:

Authorization: Bearer <jwt-token>

Endpoints

1. Submit Telemetry Data

Submit new telemetry data for a device.

Endpoint: POST /api/v1/telemetry/

Request Body:

{
  "device_id": "integer (required)",
  "metric_name": "string (required)",
  "metric_value": "number (required)",
  "unit": "string (optional)",
  "timestamp": "datetime (optional, ISO format)",
  "metadata": "object (optional)"
}

Example Request:

curl -X POST http://localhost:8000/api/v1/telemetry/ \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "device_id": 1,
    "metric_name": "temperature",
    "metric_value": 23.5,
    "unit": "°C",
    "timestamp": "2024-01-01T12:00:00Z",
    "metadata": {
      "sensor_type": "DS18B20",
      "location": "server_room"
    }
  }'

Example Response:

{
  "success": true,
  "data": {
    "id": 12345,
    "device_id": 1,
    "metric_name": "temperature",
    "metric_value": 23.5,
    "unit": "°C",
    "timestamp": "2024-01-01T12:00:00Z",
    "created_at": "2024-01-01T12:00:01Z"
  },
  "message": "Telemetry data submitted successfully"
}

2. Batch Submit Telemetry Data

Submit multiple telemetry data points in a single request.

Endpoint: POST /api/v1/telemetry/batch

Request Body:

{
  "telemetry_data": [
    {
      "device_id": 1,
      "metric_name": "temperature",
      "metric_value": 23.5,
      "unit": "°C"
    },
    {
      "device_id": 1,
      "metric_name": "humidity",
      "metric_value": 45.2,
      "unit": "%"
    }
  ]
}

Example Request:

curl -X POST http://localhost:8000/api/v1/telemetry/batch \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "telemetry_data": [
      {
        "device_id": 1,
        "metric_name": "temperature",
        "metric_value": 23.5,
        "unit": "°C"
      },
      {
        "device_id": 1,
        "metric_name": "humidity",
        "metric_value": 45.2,
        "unit": "%"
      },
      {
        "device_id": 2,
        "metric_name": "pressure",
        "metric_value": 1013.25,
        "unit": "hPa"
      }
    ]
  }'

Example Response:

{
  "success": true,
  "data": {
    "submitted": 3,
    "failed": 0,
    "ids": [12345, 12346, 12347]
  },
  "message": "Batch telemetry data submitted successfully"
}

3. Get Telemetry Data

Retrieve telemetry data with filtering and pagination.

Endpoint: GET /api/v1/telemetry/

Query Parameters:

Parameter	Type	Default	Description
`device_id`	integer	null	Filter by device ID
`metric_name`	string	null	Filter by metric name
`start_time`	datetime	null	Start time (ISO format)
`end_time`	datetime	null	End time (ISO format)
`page`	integer	1	Page number
`size`	integer	100	Items per page (1-1000)
`sort`	string	`timestamp`	Sort field
`order`	string	`desc`	Sort order (asc/desc)

Example Request:

curl -X GET "http://localhost:8000/api/v1/telemetry/?device_id=1&metric_name=temperature&start_time=2024-01-01T00:00:00Z&end_time=2024-01-01T23:59:59Z&page=1&size=50" \
  -H "Authorization: Bearer <token>"

Example Response:

{
  "success": true,
  "data": {
    "items": [
      {
        "id": 12345,
        "device_id": 1,
        "metric_name": "temperature",
        "metric_value": 23.5,
        "unit": "°C",
        "timestamp": "2024-01-01T12:00:00Z",
        "created_at": "2024-01-01T12:00:01Z",
        "metadata": {
          "sensor_type": "DS18B20"
        }
      }
    ],
    "pagination": {
      "page": 1,
      "size": 50,
      "total": 1440,
      "pages": 29,
      "has_next": true,
      "has_prev": false
    }
  }
}

4. Get Latest Telemetry Values

Retrieve the most recent telemetry values for a device.

Endpoint: GET /api/v1/telemetry/latest

Query Parameters:

Parameter	Type	Default	Description
`device_id`	integer	null	Filter by device ID
`metrics`	string	null	Comma-separated list of metrics
`limit`	integer	10	Maximum number of metrics per device

Example Request:

curl -X GET "http://localhost:8000/api/v1/telemetry/latest?device_id=1&metrics=temperature,humidity,pressure&limit=5" \
  -H "Authorization: Bearer <token>"

Example Response:

{
  "success": true,
  "data": {
    "device_id": 1,
    "telemetry": {
      "temperature": {
        "value": 23.5,
        "unit": "°C",
        "timestamp": "2024-01-01T12:00:00Z",
        "id": 12345
      },
      "humidity": {
        "value": 45.2,
        "unit": "%",
        "timestamp": "2024-01-01T12:00:00Z",
        "id": 12346
      },
      "pressure": {
        "value": 1013.25,
        "unit": "hPa",
        "timestamp": "2024-01-01T12:00:00Z",
        "id": 12347
      }
    },
    "last_updated": "2024-01-01T12:00:00Z"
  }
}

5. Get Historical Telemetry Data

Retrieve historical telemetry data with aggregations.

Endpoint: GET /api/v1/telemetry/history

Query Parameters:

Parameter	Type	Default	Description
`device_id`	integer	required	Device ID
`metric`	string	required	Metric name
`start_time`	datetime	required	Start time (ISO format)
`end_time`	datetime	required	End time (ISO format)
`interval`	string	`1m`	Aggregation interval (1m/5m/15m/1h/1d)
`aggregation`	string	`avg`	Aggregation function (avg/min/max/count/sum)

Example Request:

curl -X GET "http://localhost:8000/api/v1/telemetry/history?device_id=1&metric=temperature&start_time=2024-01-01T00:00:00Z&end_time=2024-01-01T23:59:59Z&interval=1h&aggregation=avg" \
  -H "Authorization: Bearer <token>"

Example Response:

{
  "success": true,
  "data": {
    "device_id": 1,
    "metric": "temperature",
    "interval": "1h",
    "aggregation": "avg",
    "data_points": [
      {
        "timestamp": "2024-01-01T00:00:00Z",
        "value": 22.5,
        "count": 60
      },
      {
        "timestamp": "2024-01-01T01:00:00Z",
        "value": 23.1,
        "count": 60
      }
    ],
    "statistics": {
      "min": 22.5,
      "max": 23.1,
      "avg": 22.8,
      "count": 1440
    }
  }
}

6. Get Device Telemetry Summary

Get a summary of all telemetry data for a device.

Endpoint: GET /api/v1/telemetry/device/{device_id}/summary

Path Parameters:

Parameter	Type	Description
`device_id`	integer	Device ID

Query Parameters:

Parameter	Type	Default	Description
`time_range`	string	`24h`	Time range (1h/6h/24h/7d/30d)

Example Request:

curl -X GET "http://localhost:8000/api/v1/telemetry/device/1/summary?time_range=24h" \
  -H "Authorization: Bearer <token>"

Example Response:

{
  "success": true,
  "data": {
    "device_id": 1,
    "time_range": "24h",
    "total_data_points": 1440,
    "metrics": {
      "temperature": {
        "count": 1440,
        "min": 18.5,
        "max": 28.9,
        "avg": 23.4,
        "stddev": 2.1,
        "latest_value": 23.5,
        "latest_timestamp": "2024-01-01T12:00:00Z"
      },
      "humidity": {
        "count": 1440,
        "min": 35.2,
        "max": 65.8,
        "avg": 48.7,
        "stddev": 8.3,
        "latest_value": 45.2,
        "latest_timestamp": "2024-01-01T12:00:00Z"
      }
    },
    "data_quality": {
      "expected_points": 1440,
      "actual_points": 1440,
      "completeness": 100.0,
      "gaps": []
    }
  }
}

7. Delete Telemetry Data

Delete telemetry data based on criteria.

Endpoint: DELETE /api/v1/telemetry/

Query Parameters:

Parameter	Type	Default	Description
`device_id`	integer	null	Filter by device ID
`metric_name`	string	null	Filter by metric name
`start_time`	datetime	null	Start time (ISO format)
`end_time`	datetime	null	End time (ISO format)
`confirm`	boolean	false	Confirmation required for bulk deletion

Example Request:

curl -X DELETE "http://localhost:8000/api/v1/telemetry/?device_id=1&start_time=2024-01-01T00:00:00Z&end_time=2024-01-01T23:59:59Z&confirm=true" \
  -H "Authorization: Bearer <token>"

Example Response:

{
  "success": true,
  "data": {
    "deleted_count": 1440,
    "criteria": {
      "device_id": 1,
      "start_time": "2024-01-01T00:00:00Z",
      "end_time": "2024-01-01T23:59:59Z"
    }
  },
  "message": "Telemetry data deleted successfully"
}

8. Get Available Metrics

Get all available metrics for devices.

Endpoint: GET /api/v1/telemetry/metrics

Query Parameters:

Parameter	Type	Default	Description
`device_id`	integer	null	Filter by device ID

Example Request:

curl -X GET "http://localhost:8000/api/v1/telemetry/metrics?device_id=1" \
  -H "Authorization: Bearer <token>"

Example Response:

{
  "success": true,
  "data": {
    "metrics": [
      {
        "metric_name": "temperature",
        "unit": "°C",
        "device_count": 5,
        "total_data_points": 7200,
        "last_updated": "2024-01-01T12:00:00Z"
      },
      {
        "metric_name": "humidity",
        "unit": "%",
        "device_count": 5,
        "total_data_points": 7200,
        "last_updated": "2024-01-01T12:00:00Z"
      },
      {
        "metric_name": "pressure",
        "unit": "hPa",
        "device_count": 3,
        "total_data_points": 4320,
        "last_updated": "2024-01-01T12:00:00Z"
      }
    ]
  }
}

9. Get Telemetry Statistics

Get statistical information about telemetry data.

Endpoint: GET /api/v1/telemetry/statistics

Query Parameters:

Parameter	Type	Default	Description
`time_range`	string	`24h`	Time range (1h/6h/24h/7d/30d)
`group_by`	string	`device`	Group by field (device/metric)

Example Request:

curl -X GET "http://localhost:8000/api/v1/telemetry/statistics?time_range=24h&group_by=device" \
  -H "Authorization: Bearer <token>"

Example Response:

{
  "success": true,
  "data": {
    "time_range": "24h",
    "total_data_points": 36000,
    "unique_devices": 5,
    "unique_metrics": 8,
    "by_device": [
      {
        "device_id": 1,
        "device_name": "Temperature Sensor Alpha",
        "data_points": 7200,
        "metrics": ["temperature", "humidity"],
        "last_updated": "2024-01-01T12:00:00Z"
      },
      {
        "device_id": 2,
        "device_name": "Pressure Monitor Beta",
        "data_points": 7200,
        "metrics": ["pressure", "temperature"],
        "last_updated": "2024-01-01T12:00:00Z"
      }
    ],
    "by_metric": [
      {
        "metric_name": "temperature",
        "unit": "°C",
        "device_count": 5,
        "data_points": 14400,
        "avg_value": 23.4,
        "min_value": 18.5,
        "max_value": 28.9
      },
      {
        "metric_name": "humidity",
        "unit": "%",
        "device_count": 5,
        "data_points": 14400,
        "avg_value": 48.7,
        "min_value": 35.2,
        "max_value": 65.8
      }
    ]
  }
}

10. Export Telemetry Data

Export telemetry data in various formats.

Endpoint: GET /api/v1/telemetry/export

Query Parameters:

Parameter	Type	Default	Description
`device_id`	integer	null	Filter by device ID
`metric_name`	string	null	Filter by metric name
`start_time`	datetime	null	Start time (ISO format)
`end_time`	datetime	null	End time (ISO format)
`format`	string	`json`	Export format (json/csv/xlsx)
`limit`	integer	10000	Maximum records to export

Example Request:

curl -X GET "http://localhost:8000/api/v1/telemetry/export?device_id=1&metric_name=temperature&format=csv&limit=1000" \
  -H "Authorization: Bearer <token>" \
  -o telemetry_data.csv

Example Response (CSV):

timestamp,device_id,metric_name,metric_value,unit
2024-01-01T12:00:00Z,1,temperature,23.5,°C
2024-01-01T12:01:00Z,1,temperature,23.6,°C
2024-01-01T12:02:00Z,1,temperature,23.4,°C

Data Models

Telemetry Data Object

{
  "id": "integer",
  "device_id": "integer",
  "metric_name": "string",
  "metric_value": "number",
  "unit": "string",
  "timestamp": "datetime (ISO format)",
  "created_at": "datetime (ISO format)",
  "metadata": "object"
}

Telemetry Statistics Object

{
  "count": "integer",
  "min": "number",
  "max": "number",
  "avg": "number",
  "stddev": "number",
  "latest_value": "number",
  "latest_timestamp": "datetime"
}

Supported Metric Types

temperature: Temperature measurements (°C, °F, K)
humidity: Humidity measurements (%)
pressure: Pressure measurements (Pa, hPa, bar, psi)
voltage: Voltage measurements (V, mV)
current: Current measurements (A, mA)
power: Power measurements (W, kW)
flow_rate: Flow rate measurements (L/min, m³/h)
position: Position measurements (%, degrees)
speed: Speed measurements (m/s, km/h)
frequency: Frequency measurements (Hz, kHz, MHz)

Rate Limiting

Telemetry API endpoints have specific rate limits:

Submit Data: 1,000 requests per minute per device
Query Data: 100 requests per minute per user
Batch Submit: 100 requests per minute
Export Data: 10 requests per hour

WebSocket Integration

Telemetry data updates are broadcast via WebSocket:

Real-time Telemetry Updates

const ws = new WebSocket('ws://localhost:8000/ws');

// Subscribe to device telemetry
ws.send(JSON.stringify({
  type: 'subscribe',
  channel: 'telemetry',
  device_id: 1
}));

// Receive telemetry updates
ws.onmessage = function(event) {
  const data = JSON.parse(event.data);
  if (data.type === 'telemetry_update') {
    console.log('New telemetry:', data);
  }
};

WebSocket Message Format

{
  "type": "telemetry_update",
  "device_id": 1,
  "metric_name": "temperature",
  "metric_value": 23.5,
  "unit": "°C",
  "timestamp": "2024-01-01T12:00:00Z"
}

Error Handling

Common Error Codes

400 Bad Request - Invalid telemetry data format
401 Unauthorized - Authentication required
403 Forbidden - Insufficient permissions
404 Not Found - Device not found
422 Unprocessable Entity - Validation errors
429 Too Many Requests - Rate limit exceeded
500 Internal Server Error - Server error

Validation Errors

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid telemetry data",
    "details": {
      "field": "metric_value",
      "issue": "Value must be a number"
    }
  }
}

Best Practices

Data Submission

Use batch submission for multiple data points
Include timestamps for accurate time series data
Validate data before submission
Handle rate limiting gracefully

Data Retrieval

Use appropriate time ranges to limit data volume
Use pagination for large datasets
Cache frequently accessed data
Use aggregations for historical data

Performance

Submit data in real-time for immediate processing
Use WebSocket for real-time updates
Implement proper error handling
Monitor API usage and performance

Examples and Use Cases

Real-time Data Submission

import requests
import json
from datetime import datetime

def submit_telemetry_batch(device_id, readings):
    """Submit batch telemetry data"""
    telemetry_data = []
    
    for reading in readings:
        telemetry_data.append({
            "device_id": device_id,
            "metric_name": reading["metric"],
            "metric_value": reading["value"],
            "unit": reading["unit"],
            "timestamp": datetime.utcnow().isoformat()
        })
    
    response = requests.post(
        "http://localhost:8000/api/v1/telemetry/batch",
        json={"telemetry_data": telemetry_data},
        headers={"Authorization": f"Bearer {token}"}
    )
    
    return response.json()

# Usage example
readings = [
    {"metric": "temperature", "value": 23.5, "unit": "°C"},
    {"metric": "humidity", "value": 45.2, "unit": "%"},
    {"metric": "pressure", "value": 1013.25, "unit": "hPa"}
]

result = submit_telemetry_batch(1, readings)
print(f"Submitted {result['data']['submitted']} data points")

Historical Data Analysis

def get_historical_analysis(device_id, metric, hours=24):
    """Get historical data with analysis"""
    end_time = datetime.utcnow()
    start_time = end_time - timedelta(hours=hours)
    
    response = requests.get(
        f"http://localhost:8000/api/v1/telemetry/history",
        params={
            "device_id": device_id,
            "metric": metric,
            "start_time": start_time.isoformat(),
            "end_time": end_time.isoformat(),
            "interval": "1h",
            "aggregation": "avg"
        },
        headers={"Authorization": f"Bearer {token}"}
    )
    
    return response.json()

# Usage example
analysis = get_historical_analysis(1, "temperature", 24)
data_points = analysis["data"]["data_points"]
statistics = analysis["data"]["statistics"]

print(f"Average temperature: {statistics['avg']}°C")
print(f"Temperature range: {statistics['min']}°C - {statistics['max']}°C")

Support

For Telemetry API support:

Documentation: API Overview
Device API: Device API
WebSocket API: WebSocket API
Troubleshooting: Troubleshooting Guide
Email: autobotsolution@gmail.com

telemetry api

Telemetry API Documentation

Overview

Base Endpoint

Authentication

Endpoints

1. Submit Telemetry Data

2. Batch Submit Telemetry Data

3. Get Telemetry Data

4. Get Latest Telemetry Values

5. Get Historical Telemetry Data

6. Get Device Telemetry Summary

7. Delete Telemetry Data

8. Get Available Metrics

9. Get Telemetry Statistics

10. Export Telemetry Data

Data Models

Telemetry Data Object

Telemetry Statistics Object

Supported Metric Types

Rate Limiting

WebSocket Integration

Real-time Telemetry Updates

WebSocket Message Format

Error Handling

Common Error Codes

Validation Errors

Best Practices

Data Submission

Data Retrieval

Performance

Examples and Use Cases

Real-time Data Submission

Historical Data Analysis

Support

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Clone this wiki locally