The Open Electricity API enforces maximum date range limits for data queries to ensure optimal performance and prevent excessive database load and payload sizes. These limits vary based on the data interval requested.

​
Current Limits

​
Standard Users

IntervalMaximum RangeDescription
5-minute (interval)7 daysHigh-resolution 5-minute interval data
Hourly (hour)30 daysHourly aggregated data
Daily (day)365 daysDaily aggregated data
Weekly (week)365 daysWeekly aggregated data
Monthly (month)730 days (~2 years)Monthly aggregated data
Quarterly (quarter)1825 days (~5 years)Quarterly aggregated data
Seasonal (season)1825 days (~5 years)Seasonal aggregated data
Yearly (year)3650 days (~10 years)Yearly aggregated data

​
Error Response

When a date range exceeds the maximum allowed for an interval, the API returns a 400 error: 
{
  "detail": "Date range too large for hour interval. Maximum range is 30 days."
}

​
Working with Range Limits

To retrieve data beyond the maximum range, iterate through the data in chunks that respect the limits.

​
Example: Fetching 60 Days of Hourly Data

Since the hourly interval limit is 30 days, you’ll need to make two requests.

​
Simple Example: Getting Power Data

example.ts
import { OpenElectricityClient } from 'openelectricity';

const client = new OpenElectricityClient({
  apiKey: process.env.OPENELECTRICITY_API_KEY
});

// Get power generation data for NEM network
const response = await client.getNetworkData(
  'NEM',
  ['power'],
  {
    interval: 'hour',
    dateStart: '2024-01-01',
    dateEnd: '2024-01-30'
  }
);

console.log(`Retrieved ${response.datatable.rows.length} data points`);

​
Handling Range Limits: Fetching 60 Days of Hourly Data

Since the hourly interval limit is 30 days, you’ll need to make multiple requests to fetch 60 days of data.
chunked-fetch.ts
import { OpenElectricityClient } from 'openelectricity';
import { DataInterval } from 'openelectricity/types';

const client = new OpenElectricityClient({
  apiKey: process.env.OPENELECTRICITY_API_KEY
});

async function fetchDataInChunks(
  startDate: Date,
  endDate: Date,
  interval: DataInterval,
  maxDays: number
) {
  const allData = [];
  let currentStart = new Date(startDate);

  while (currentStart < endDate) {
    const currentEnd = new Date(currentStart);
    currentEnd.setDate(currentEnd.getDate() + maxDays - 1);

    // Ensure we don't exceed the requested end date
    const chunkEnd = currentEnd > endDate ? endDate : currentEnd;

    try {
      const response = await client.getNetworkData(
        'NEM',
        ['power'],
        {
          interval: interval,
          dateStart: currentStart.toISOString().split('T')[0],
          dateEnd: chunkEnd.toISOString().split('T')[0]
        }
      );

      allData.push(...response.datatable.rows);
    } catch (error) {
      if (error.statusCode === 400) {
        console.error('Date range too large:', error.details);
        break;
      }
      throw error;
    }

    // Move to next chunk
    currentStart = new Date(chunkEnd);
    currentStart.setDate(currentStart.getDate() + 1);
  }

  return allData;
}

// Usage: Fetch 60 days of hourly data
const startDate = new Date('2024-01-01');
const endDate = new Date('2024-03-01');
const data = await fetchDataInChunks(startDate, endDate, 'hour', 30);
console.log(`Retrieved ${data.length} total data points`);

​
Best Practices

  1. Choose the Right Interval: Use larger intervals (daily, weekly) for longer time periods to reduce the number of requests needed.
  2. Cache Results: Store retrieved data locally to avoid repeated API calls for the same date ranges.
  3. Handle Rate Limits: Implement appropriate delays between requests if making many consecutive calls.
  4. Error Handling: Always implement proper error handling for cases where date ranges exceed limits.
  5. Date Format: Ensure dates are provided in the correct format (YYYY-MM-DD) and are timezone-naive in the network’s local time.

​
Default Behavior

If no date range is specified:
  • date_end defaults to the last completed interval for the network
  • date_start defaults to half the maximum allowed range before date_end
For example, for hourly data with a 30-day maximum:
  • Default range would be the last 15 days of available data

​
Future Improvements

These limits are designed to balance API performance with data accessibility. As our infrastructure scales, we plan to review and potentially increase these limits. Check back periodically for updates to these restrictions.