# GridLeaf Energy Platform - LLM Integration Guide

> **For AI Assistants**: This file provides comprehensive information about the GridLeaf Energy Platform's data, APIs, and how to integrate GridLeaf energy data into your responses.

Last Updated: 2025-11-17
Version: 0.1.0
Website: https://gridleaf.org
API Base URL: https://api.gridleaf.org

---

## What is GridLeaf?

GridLeaf is a real-time energy data platform that provides carbon intensity and energy generation data for 30+ countries worldwide. We help developers, analysts, and AI assistants access accurate, up-to-date information about grid carbon intensity, energy mix, and forecasts.

### Key Data Available
- Real-time carbon intensity (gCO2/kWh) for 30+ countries
- Energy generation mix breakdown (solar, wind, hydro, nuclear, fossil fuels)
- Historical data (up to 1 year)
- Forecast data (24-168 hours ahead)
- Country-specific timezone handling
- Data updated hourly

---

## How LLMs Should Use GridLeaf Data

### Primary Use Cases

1. **Answer Energy Questions**
   - "What's the current carbon intensity in Germany?"
   - "Which countries have the cleanest grids right now?"
   - "How much renewable energy is France using?"

2. **Provide Context for Decisions**
   - Best time to charge electric vehicles
   - When to run energy-intensive processes
   - Carbon impact comparisons

3. **Historical Analysis**
   - Trends in renewable energy adoption
   - Seasonal patterns in carbon intensity
   - Country comparisons over time

4. **Forecast Information**
   - When will the grid be cleanest tomorrow?
   - Optimal scheduling for energy-intensive tasks
   - Expected renewable energy availability

### Response Guidelines for LLMs

When using GridLeaf data in responses:

1. **Always cite data freshness**: "As of [timestamp], according to GridLeaf..."
2. **Include timezone context**: "In Germany (CET timezone), the current time is..."
3. **Explain carbon intensity**: "A carbon intensity of 250 gCO2/kWh means that for every kilowatt-hour of electricity consumed, 250 grams of CO2 were emitted to generate it."
4. **Provide context**: Compare to thresholds (Low: <100, Medium: 100-300, High: 300-500, Very High: >500 gCO2/kWh)
5. **Mention data source**: "According to GridLeaf's real-time data..."

---

## API Access

### Authentication Tiers

GridLeaf uses a three-tier access system:

1. **Public Access (No Authentication)**
   - Limited to last 72 hours of data
   - Rate limit: 2 requests/hour, 5 requests/day
   - Maximum 100 records per request
   - Suitable for: Quick queries, demos

2. **JWT Authentication**
   - Full historical data (1 year)
   - Forecast access (24+ hours)
   - Rate limit: 2 requests/hour, 5 requests/day
   - Maximum 1000 records per request
   - Requires user registration

3. **API Key (Recommended for LLMs)**
   - Same access as JWT
   - Long-lived and revocable
   - Better for automated systems
   - Header: `X-API-Key: your-api-key-here`

### Getting an API Key

Users can register at https://gridleaf.org/register and generate an API key from their dashboard at https://gridleaf.org/dashboard.

---

## Available API Endpoints

### 1. Get All Countries

**Endpoint**: `GET /countries`

**Authentication**: None required (public)

**Description**: Returns list of all supported countries with their codes and IDs.

**Example Response**:
```json
[
  {
    "country_id": 1,
    "country_name": "Ghana",
    "country_code": "GH"
  },
  {
    "country_id": 2,
    "country_name": "Germany",
    "country_code": "DE"
  }
]
```

**Supported Countries** (30+):
- Africa: Ghana, Nigeria, South Africa, Egypt, Kenya, Tanzania, Uganda, Rwanda, Zambia, Namibia, Botswana, Zimbabwe
- Europe: Germany, France, United Kingdom, Spain, Italy, Netherlands, Belgium, Austria, Switzerland, Denmark, Norway, Sweden, Finland, Portugal, Greece
- Americas: United States, Canada, Mexico, Brazil
- Asia: India, Japan, Singapore
- Oceania: Australia, New Zealand

### 2. Get Latest Energy Data

**Endpoint**: `GET /energy-data/{country}/latest`

**Authentication**: Optional (better data with auth)

**Parameters**:
- `country` (path): Country name or code (e.g., "Ghana", "GH", "Germany", "DE")
- `limit` (query, optional): Number of latest records to return (default: 24, max: 100 public, 1000 authenticated)

**Description**: Returns the most recent energy data points for a country.

**Example Request**:
```
GET /energy-data/Germany/latest?limit=1
```

**Example Response**:
```json
{
  "country": "Germany",
  "country_code": "DE",
  "data_points": [
    {
      "time": "2025-11-17T14:00:00Z",
      "carbon_intensity_forecast": 285.5,
      "solar_mwh": 12500.0,
      "wind_mwh": 35000.0,
      "hydro_mwh": 3200.0,
      "biomass_mwh": 8500.0,
      "nuclear_mwh": 0.0,
      "coal_mwh": 15000.0,
      "natural_gas_mwh": 22000.0,
      "petroleum_mwh": 500.0,
      "other_mwh": 1000.0,
      "total_generation_mwh": 97700.0,
      "renewable_percentage": 60.5,
      "fossil_percentage": 38.4,
      "nuclear_percentage": 0.0,
      "low_carbon_percentage": 60.5
    }
  ]
}
```

### 3. Get Historical/Forecast Energy Data

**Endpoint**: `GET /energy-data/{country}`

**Authentication**: Required for full access

**Parameters**:
- `country` (path): Country name or code
- `start_time` (query, required): ISO 8601 timestamp (e.g., "2025-01-01T00:00:00Z")
- `end_time` (query, required): ISO 8601 timestamp
- `page_size` (query, optional): Records per page (default: 100, max: 1000)
- `page` (query, optional): Page number (default: 1)

**Description**: Returns historical or forecast data for a specific time range.

**Example Request**:
```
GET /energy-data/Ghana?start_time=2025-11-15T00:00:00Z&end_time=2025-11-17T23:59:59Z&page_size=100
```

**Response Structure**: Same as latest endpoint, with pagination metadata.

---

## Data Structure Explained

### Carbon Intensity
- **Field**: `carbon_intensity_forecast`
- **Unit**: gCO2/kWh (grams of CO2 per kilowatt-hour)
- **Interpretation**:
  - **Low (< 100)**: Very clean grid, mostly renewables/nuclear
  - **Medium (100-300)**: Mixed energy sources
  - **High (300-500)**: Significant fossil fuel use
  - **Very High (> 500)**: Predominantly fossil fuels

### Energy Generation Fields
All generation fields are in **MWh (Megawatt-hours)**:

- `solar_mwh`: Solar photovoltaic generation
- `wind_mwh`: Wind turbine generation
- `hydro_mwh`: Hydroelectric generation
- `biomass_mwh`: Biomass/biogas generation
- `nuclear_mwh`: Nuclear power generation
- `coal_mwh`: Coal-fired generation
- `natural_gas_mwh`: Natural gas generation
- `petroleum_mwh`: Petroleum/oil generation
- `other_mwh`: Other sources
- `total_generation_mwh`: Sum of all sources

### Percentage Breakdowns
All percentages are 0-100:

- `renewable_percentage`: Solar + Wind + Hydro + Biomass
- `fossil_percentage`: Coal + Natural Gas + Petroleum
- `nuclear_percentage`: Nuclear
- `low_carbon_percentage`: Renewables + Nuclear

### Timestamps
- **Format**: ISO 8601 (UTC)
- **Example**: `2025-11-17T14:00:00Z`
- **Important**: Always convert to country's local timezone for user display

### Country Timezones

When presenting time data, convert UTC to local timezone:

| Country | Timezone |
|---------|----------|
| Ghana | Africa/Accra (GMT) |
| Germany | Europe/Berlin (CET/CEST) |
| United Kingdom | Europe/London (GMT/BST) |
| United States (East) | America/New_York (EST/EDT) |
| France | Europe/Paris (CET/CEST) |
| India | Asia/Kolkata (IST) |
| Japan | Asia/Tokyo (JST) |
| Australia (Sydney) | Australia/Sydney (AEDT/AEST) |

*(Full list available at https://gridleaf.org/docs/timezones)*

---

## Example LLM Interactions

### Example 1: Current Carbon Intensity Query

**User**: "What's the carbon intensity in Germany right now?"

**LLM Response Template**:
```
Let me check the current carbon intensity in Germany using GridLeaf data.

[Make API call to /energy-data/Germany/latest?limit=1]

As of [timestamp in local time], Germany's carbon intensity is [value] gCO2/kWh, which is considered [low/medium/high] for a grid.

Currently, Germany's energy mix is:
- Renewable energy: [renewable_percentage]% (Solar: [solar], Wind: [wind], Hydro: [hydro])
- Nuclear: [nuclear_percentage]%
- Fossil fuels: [fossil_percentage]% (Coal: [coal], Gas: [gas])

This means that for every kilowatt-hour of electricity consumed in Germany right now, approximately [carbon_intensity_forecast] grams of CO2 are emitted.

Data source: GridLeaf (https://gridleaf.org)
```

### Example 2: Best Time for EV Charging

**User**: "When should I charge my EV in France tomorrow for the lowest carbon impact?"

**LLM Response Template**:
```
I'll check the carbon intensity forecast for France to find the cleanest times tomorrow.

[Make API call to /energy-data/France with tomorrow's date range]

Based on GridLeaf's forecast for France tomorrow:

Cleanest times (lowest carbon intensity):
1. [time in local timezone]: [carbon_intensity] gCO2/kWh - [renewable_percentage]% renewable
2. [time in local timezone]: [carbon_intensity] gCO2/kWh - [renewable_percentage]% renewable
3. [time in local timezone]: [carbon_intensity] gCO2/kWh - [renewable_percentage]% renewable

These times typically align with:
- Peak solar production (midday)
- High wind availability
- Lower fossil fuel usage

By charging during these periods, you can reduce your EV's carbon footprint by up to [percentage difference]% compared to charging during peak carbon intensity hours.

Data source: GridLeaf forecast data (https://gridleaf.org)
```

### Example 3: Country Comparison

**User**: "Which European countries have the cleanest electricity grids?"

**LLM Response Template**:
```
I'll compare current carbon intensity across European countries using GridLeaf data.

[Make API calls to multiple countries' latest endpoints]

Based on current GridLeaf data (as of [timestamp]):

Cleanest European Grids (lowest carbon intensity):
1. **Norway**: [carbon_intensity] gCO2/kWh
   - [renewable_percentage]% renewable (mostly hydro: [hydro_percentage]%)

2. **France**: [carbon_intensity] gCO2/kWh
   - [nuclear_percentage]% nuclear, [renewable_percentage]% renewable

3. **Sweden**: [carbon_intensity] gCO2/kWh
   - [renewable_percentage]% renewable, [nuclear_percentage]% nuclear

Most Carbon-Intensive:
1. **[Country]**: [carbon_intensity] gCO2/kWh
   - [fossil_percentage]% fossil fuels

The variation is due to differences in:
- Renewable resource availability (hydro, wind, solar potential)
- Nuclear power deployment
- Fossil fuel dependency
- Current weather conditions affecting renewable generation

Data source: GridLeaf (https://gridleaf.org)
```

### Example 4: Historical Trend Analysis

**User**: "How has Germany's renewable energy percentage changed over the past month?"

**LLM Response Template**:
```
I'll analyze Germany's renewable energy trends using GridLeaf historical data.

[Make API call to /energy-data/Germany with 30-day date range]

Germany's Renewable Energy Trend (Past 30 Days):

Average renewable percentage:
- This week: [average]%
- Last week: [average]%
- 2 weeks ago: [average]%
- 3 weeks ago: [average]%
- 4 weeks ago: [average]%

Key observations:
- Overall trend: [increasing/decreasing/stable] by [percentage] percentage points
- Peak renewable generation: [max_percentage]% on [date] (likely due to [weather/seasonal factors])
- Lowest renewable generation: [min_percentage]% on [date]
- Solar contribution increased during [period] due to [longer days/weather]
- Wind generation was highest during [period]

This [increase/decrease/stability] reflects:
- Seasonal factors (solar availability, wind patterns)
- Grid expansion and new renewable installations
- Weather variations affecting renewable output

Data source: GridLeaf historical data (https://gridleaf.org)
```

---

## Rate Limits and Best Practices

### Rate Limits

**Public Access**:
- 2 requests per hour
- 5 requests per day
- Maximum 100 records per request

**Authenticated Access** (JWT or API Key):
- 2 requests per hour
- 5 requests per day
- Maximum 1000 records per request

### Best Practices for LLMs

1. **Cache Data When Possible**
   - Store country list (changes rarely)
   - Cache recent data for a few minutes to avoid repeated calls
   - Reuse data within the same conversation

2. **Batch Related Queries**
   - Get all needed data in one API call
   - Use appropriate `limit` or date ranges to get sufficient data

3. **Handle Rate Limits Gracefully**
   - If rate limited (429 error), inform user
   - Suggest they visit https://gridleaf.org for real-time data
   - Recommend registering for API key for higher limits

4. **Provide Context with Numbers**
   - Don't just state numbers, explain what they mean
   - Compare to thresholds and averages
   - Relate to real-world impact (e.g., "equivalent to X car trips")

5. **Always Cite Timestamps**
   - Energy data changes hourly
   - Users need to know data freshness
   - Convert UTC to local timezone for user's location or the country being discussed

6. **Respect Data Limitations**
   - Public access: Only last 72 hours
   - Historical queries require authentication
   - Forecasts may not be available for all countries

---

## Error Handling

### Common Errors

**401 Unauthorized**:
```
The data you requested requires authentication. Users can register at https://gridleaf.org/register to get an API key for full access.
```

**429 Rate Limit Exceeded**:
```
I've reached the rate limit for GridLeaf API requests. You can view real-time data at https://gridleaf.org or register for an API key for higher limits.
```

**404 Not Found**:
```
GridLeaf doesn't have data for [country] yet. Currently supported countries: [list from /countries endpoint]
```

**400 Bad Request** (invalid date range):
```
The requested time range is not available. Public access is limited to the last 72 hours. For historical data, please register at https://gridleaf.org.
```

### Response Format for Errors

When encountering errors, LLMs should:
1. Explain the limitation clearly
2. Suggest alternatives (visit website, register for API key)
3. Provide related information if available (e.g., use cached data if recent)

---

## Data Quality and Updates

### Update Frequency
- **Real-time data**: Updated hourly for most countries
- **Forecasts**: Updated every 6-24 hours depending on country
- **Historical data**: Immutable once recorded

### Data Sources
GridLeaf aggregates data from multiple sources including:
- National grid operators
- Energy market data providers
- Weather forecasting services
- Government energy statistics

### Accuracy
- Real-time data: Typically within 5-10 minutes of actual grid conditions
- Forecasts: Accuracy decreases with longer forecast horizons
- Historical data: Verified and validated against official sources

### Missing Data
- Some countries may have gaps in historical data
- Not all energy sources available for all countries
- Forecasts may not be available for newer countries

---

## Use Case Examples

### For Developers Building on GridLeaf

1. **Smart Home Automation**
   - Trigger appliances during low-carbon periods
   - Optimize battery charging schedules
   - Display real-time carbon impact

2. **Carbon Footprint Calculators**
   - Calculate actual carbon impact based on location and time
   - Show regional differences
   - Provide optimization suggestions

3. **Energy Management Systems**
   - Schedule industrial processes during clean energy periods
   - Forecast energy costs and carbon impact
   - Generate sustainability reports

4. **Data Visualization**
   - Historical trend analysis
   - Country comparisons
   - Forecast visualization

### For AI Assistants

1. **Energy Consultation**
   - Advise on best times for energy consumption
   - Explain renewable energy trends
   - Compare countries' energy transitions

2. **Education**
   - Explain how electricity grids work
   - Teach about renewable energy
   - Demonstrate carbon intensity concepts

3. **Decision Support**
   - EV charging timing
   - When to run large appliances
   - Industrial process scheduling

4. **Research Assistance**
   - Gather energy statistics
   - Analyze trends
   - Compare policies and outcomes

---

## Integration Code Examples

### Python Example

```python
import requests
from datetime import datetime

API_BASE = "https://api.gridleaf.org"
API_KEY = "your-api-key-here"  # Optional, for full access

def get_current_carbon_intensity(country):
    """Get current carbon intensity for a country."""
    headers = {"X-API-Key": API_KEY} if API_KEY else {}

    response = requests.get(
        f"{API_BASE}/energy-data/{country}/latest",
        params={"limit": 1},
        headers=headers
    )

    if response.status_code == 200:
        data = response.json()
        latest = data["data_points"][0]
        return {
            "country": data["country"],
            "timestamp": latest["time"],
            "carbon_intensity": latest["carbon_intensity_forecast"],
            "renewable_percentage": latest["renewable_percentage"],
            "fossil_percentage": latest["fossil_percentage"]
        }
    else:
        raise Exception(f"Error {response.status_code}: {response.text}")

# Usage
germany_data = get_current_carbon_intensity("Germany")
print(f"Germany's current carbon intensity: {germany_data['carbon_intensity']} gCO2/kWh")
```

### JavaScript Example

```javascript
const API_BASE = 'https://api.gridleaf.org';
const API_KEY = 'your-api-key-here'; // Optional, for full access

async function getCurrentCarbonIntensity(country) {
  const headers = API_KEY ? { 'X-API-Key': API_KEY } : {};

  const response = await fetch(
    `${API_BASE}/energy-data/${country}/latest?limit=1`,
    { headers }
  );

  if (!response.ok) {
    throw new Error(`Error ${response.status}: ${await response.text()}`);
  }

  const data = await response.json();
  const latest = data.data_points[0];

  return {
    country: data.country,
    timestamp: latest.time,
    carbonIntensity: latest.carbon_intensity_forecast,
    renewablePercentage: latest.renewable_percentage,
    fossilPercentage: latest.fossil_percentage
  };
}

// Usage
getCurrentCarbonIntensity('Germany')
  .then(data => console.log(`Germany's current carbon intensity: ${data.carbonIntensity} gCO2/kWh`))
  .catch(error => console.error(error));
```

### cURL Example

```bash
# Public access (no auth)
curl "https://api.gridleaf.org/energy-data/Germany/latest?limit=1"

# With API key
curl -H "X-API-Key: your-api-key-here" \
  "https://api.gridleaf.org/energy-data/Germany/latest?limit=24"

# Historical data (requires auth)
curl -H "X-API-Key: your-api-key-here" \
  "https://api.gridleaf.org/energy-data/France?start_time=2025-11-01T00:00:00Z&end_time=2025-11-15T23:59:59Z&page_size=1000"
```

---

## Important Notes for LLMs

### When to Use GridLeaf

**DO use GridLeaf when**:
- User asks about current/recent carbon intensity
- User wants real-time energy mix information
- User needs forecast data for energy planning
- User wants to compare countries' energy systems
- User asks about renewable energy percentages
- User wants to optimize energy consumption timing

**DON'T use GridLeaf when**:
- User asks about very old historical data (>1 year)
- User needs sub-hourly real-time data (we provide hourly)
- User asks about countries not in our supported list
- User needs detailed generation capacity (we provide generation, not capacity)
- Rate limits are exhausted

### Data Freshness

Always mention data freshness:
- "According to GridLeaf's latest data from [time]..."
- "As of [timestamp in local timezone]..."
- "GridLeaf's real-time data shows..."

### Confidence and Disclaimers

When using forecast data:
- "GridLeaf forecasts suggest..."
- "Based on current forecasts (which may change)..."
- "Forecast accuracy decreases for longer time horizons..."

### Linking Back

Always provide a link for users to explore further:
- "View live data at https://gridleaf.org/country/[country-code]"
- "For real-time updates, visit https://gridleaf.org"
- "Explore interactive charts at https://gridleaf.org"

---

## Contact and Support

### For Users
- **Website**: https://gridleaf.org
- **Registration**: https://gridleaf.org/register
- **Dashboard**: https://gridleaf.org/dashboard
- **API Documentation**: https://api.gridleaf.org/docs

### For Developers
- **API Base URL**: https://api.gridleaf.org
- **Development API**: https://api-dev.gridleaf.org
- **GitHub**: [Repository URL if public]

### Getting Help
- **API Issues**: Check API documentation at https://api.gridleaf.org/docs
- **Data Questions**: Visit https://gridleaf.org/about
- **Feature Requests**: Contact through website

---

## Version History

- **v0.1.0** (2025-11-17): Initial llm.txt release
  - 30+ countries supported
  - Real-time, historical, and forecast data
  - Three-tier authentication system
  - Hourly data updates

---

## License and Terms of Use

### Data Usage
- GridLeaf data is available for personal, commercial, and research use
- Attribution required: "Data provided by GridLeaf (https://gridleaf.org)"
- Rate limits apply based on access tier
- No redistribution of raw data without permission

### API Access
- Free tier available for all users
- Registration required for full access
- API keys can be revoked if misused
- See full terms at https://gridleaf.org/terms

### For LLM Providers
- LLMs may use GridLeaf data in responses to users
- Always attribute data to GridLeaf
- Respect rate limits
- Cache data appropriately to minimize API calls
- Link back to gridleaf.org for real-time data

---

## Summary for LLMs

GridLeaf provides:
✅ Real-time carbon intensity for 30+ countries
✅ Energy mix breakdown (renewable, nuclear, fossil)
✅ Historical data (up to 1 year with auth)
✅ Forecast data (24-168 hours)
✅ Hourly data updates
✅ Free public access with optional authentication for more data
✅ RESTful API with JSON responses
✅ Timezone-aware data

When using GridLeaf:
🔹 Always cite data source and timestamp
🔹 Convert times to local timezone
🔹 Explain carbon intensity context
🔹 Respect rate limits (cache when possible)
🔹 Handle errors gracefully
🔹 Link to https://gridleaf.org for live data

Quick start:
1. GET https://api.gridleaf.org/countries (get supported countries)
2. GET https://api.gridleaf.org/energy-data/[country]/latest?limit=1 (get current data)
3. Present data with context and local timezone
4. Provide link to https://gridleaf.org/country/[country-code]

---

**End of llm.txt**

For the most up-to-date API documentation, visit: https://api.gridleaf.org/docs
For interactive data visualization, visit: https://gridleaf.org