> ## Documentation Index
> Fetch the complete documentation index at: https://docs-beta.rebase.energy/llms.txt
> Use this file to discover all available pages before exploring further.

# Live Data

> Connect to external APIs for real-time energy data and automatic updates

## Understanding live data

Live data is where the real power of the Rebase Dashboard API comes to life - connecting to external APIs to get real-time energy production, consumption, prices, and weather data. This comprehensive integration enables dynamic, up-to-the-minute energy monitoring and analysis.

## Creating live datasets

### Basic live dataset

Connect to any REST API for real-time data feeds using the `create_timeseries_live` method.

```python theme={null}
# Create a live dataset that fetches from an external API
live_dataset = client.datasets.create_timeseries_live(
    name="Live Energy Production",
    url="https://api.example.com/energy/production",
    params={
        "start": "{start}",  # These get replaced with actual timestamps
        "end": "{end}",
        "region": "DK1"
    },
    data_format="json",  # or "csv"
    aliases={
        "time": "timestamp",  # Map API column names to expected format
        "production_mw": "value"
    },
    headers={
        "Authorization": "Bearer your-api-key"
    },
    datetime_format="%Y-%m-%dT%H:%M",  # Optional: custom datetime format
    description="Real-time energy production data from external API",
    metadata={
        "unit": "MW",
        "region": "DK1",
        "data_source": "external_api"
    }
)
```

**Key Features:**

* **URL with params**: The url is your external API endpoint, and params can use `{start}` and `{end}` placeholders that get replaced with actual timestamps when fetching data
* **Column mapping**: Use aliases to map your API's column names to the expected timestamp and value format
* **Flexible formats**: Supports both JSON and CSV responses
* **Custom datetime formatting**: If your API needs a specific datetime format, you can specify it with `datetime_format`
* **Headers**: Add authentication or other headers as needed

**Limitations:**

* Column mapping is limited to `timestamp` and `value` fields only
* Start and end parameters are required when fetching data
* Only JSON and CSV formats are supported
* No automatic refresh: Live datasets don't automatically refresh - data is fetched on-demand
* No status monitoring: No built-in status tracking or error monitoring
* No real-time updates: Data is fetched when requested, not continuously updated

### Using live datasets in components

The data gets fetched automatically when you use it in components:

```python theme={null}
# The data gets fetched automatically when you use it in components
timeseries_component = client.components.create_timeseries(
    name="Live Energy Dashboard",
    title="Real-time Energy Production",
    datasets=[live_dataset.id]
)
```

## Advanced live dataset configurations

### CSV data format

For APIs that return CSV data:

```python theme={null}
# Live dataset with CSV format
csv_live_dataset = client.datasets.create_timeseries_live(
    name="CSV Energy Data",
    url="https://api.example.com/energy/csv",
    params={
        "start": "{start}",
        "end": "{end}"
    },
    data_format="csv",
    aliases={
        "datetime": "timestamp",
        "power_output": "value"
    },
    headers={
        "Authorization": "Bearer your-api-key"
    },
    description="Energy data in CSV format"
)
```

### Complex parameter mapping

For APIs with complex parameter requirements:

```python theme={null}
# Live dataset with complex parameters
complex_live_dataset = client.datasets.create_timeseries_live(
    name="Complex API Integration",
    url="https://api.energy-provider.com/v2/production",
    params={
        "start_time": "{start}",
        "end_time": "{end}",
        "region": "DK1",
        "data_type": "production",
        "resolution": "hourly",
        "include_metadata": "true"
    },
    data_format="json",
    aliases={
        "timestamp": "timestamp",
        "production_mw": "value",
        "capacity_mw": "capacity",
        "efficiency": "efficiency_pct"
    },
    headers={
        "Authorization": "Bearer your-api-key",
        "Accept": "application/json",
        "User-Agent": "RebaseEnergyAPI/1.0"
    },
    datetime_format="%Y-%m-%dT%H:%M:%SZ",
    description="Complex energy production data with metadata"
)
```

### Custom datetime formats

Handle various datetime formats from different APIs:

```python theme={null}
# Live dataset with custom datetime format
custom_datetime_dataset = client.datasets.create_timeseries_live(
    name="Custom DateTime Format",
    url="https://api.example.com/energy",
    params={
        "start": "{start}",
        "end": "{end}"
    },
    data_format="json",
    aliases={
        "date_time": "timestamp",
        "power": "value"
    },
    datetime_format="%Y-%m-%d %H:%M:%S",  # Custom format
    headers={
        "Authorization": "Bearer your-api-key"
    },
    description="Data with custom datetime format"
)
```

## Use cases

### Energy trading

```python theme={null}
# Real-time energy trading data
trading_dataset = client.datasets.create_timeseries_live(
    name="Energy Trading Data",
    url="https://api.energy-exchange.com/prices",
    params={
        "start": "{start}",
        "end": "{end}",
        "market": "DK1"
    },
    data_format="json",
    aliases={
        "time": "timestamp",
        "price_eur_mwh": "value"
    },
    headers={
        "Authorization": "Bearer your-api-key"
    },
    description="Real-time electricity prices from European markets",
    metadata={
        "unit": "EUR/MWh",
        "market": "DK1",
        "data_source": "energy_exchange"
    }
)
```

### Wind farm monitoring

```python theme={null}
# Wind farm SCADA data
scada_dataset = client.datasets.create_timeseries_live(
    name="Wind Farm SCADA",
    url="https://scada.windfarm.com/api/production",
    params={
        "start": "{start}",
        "end": "{end}",
        "turbine_id": "all"
    },
    data_format="json",
    aliases={
        "timestamp": "timestamp",
        "production_mw": "value",
        "wind_speed": "wind_speed_ms",
        "status": "turbine_status"
    },
    headers={
        "Authorization": "Bearer your-api-key"
    },
    description="Real-time wind farm production data",
    metadata={
        "unit": "MW",
        "data_source": "scada_system"
    }
)
```

### Grid monitoring

```python theme={null}
# Grid operator data
grid_dataset = client.datasets.create_timeseries_live(
    name="Grid Load Data",
    url="https://api.grid-operator.com/load",
    params={
        "start": "{start}",
        "end": "{end}",
        "region": "DK1"
    },
    data_format="json",
    aliases={
        "time": "timestamp",
        "load_mw": "value",
        "frequency": "frequency_hz"
    },
    headers={
        "Authorization": "Bearer your-api-key"
    },
    description="Real-time grid load and frequency data",
    metadata={
        "unit": "MW",
        "region": "DK1",
        "data_source": "grid_operator"
    }
)
```

## Best practices

### Data quality

* Ensure your API returns consistent data formats
* Use appropriate datetime formats for your data source
* Validate that your aliases correctly map to the expected column names
* Test your live dataset connections before deploying to production

### Performance

* Use appropriate time ranges in your params to avoid fetching too much data
* Consider the refresh rate of your external API
* Monitor data freshness and API response times
* Use caching when possible to reduce API calls

### Reliability

* Implement proper error handling for API failures
* Use fallback data sources when possible
* Monitor connection health and data flow
* Set up alerts for data quality issues

### Security

* Use secure authentication methods (Bearer tokens, API keys)
* Store sensitive credentials securely
* Implement proper access controls
* Monitor for suspicious activity

## Troubleshooting

### Common issues

**Data not updating**: Check that your `{start}` and `{end}` placeholders are being replaced correctly and that your API is returning data for the specified time range.

**Authentication errors**: Verify that your headers contain the correct authentication information and that your API key is valid.

**Format errors**: Ensure that your `data_format` matches what your API returns and that your `aliases` correctly map the column names.

**Datetime parsing errors**: Check that your `datetime_format` matches the format returned by your API.

### Debugging live datasets

```python theme={null}
# Check your live dataset
dataset = client.datasets.get_dataset(live_dataset.id)
print(f"Dataset name: {dataset.name}")
print(f"Created at: {dataset.created_at}")
print(f"Updated at: {dataset.updated_at}")
```

## Next steps

Now that you understand live data, explore advanced features:

<CardGroup cols={2}>
  <Card title="Weather Integration" icon="cloud" href="/essentials/weather-integration">
    Combine live data with weather information.
  </Card>

  <Card title="Customization" icon="palette" href="/essentials/customization">
    Customize live data visualization and behavior.
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/introduction">
    Explore all dataset endpoints and options.
  </Card>

  <Card title="Components" icon="puzzle-piece" href="/essentials/components">
    Learn how to use live data in components.
  </Card>
</CardGroup>