search
Open Grid Status

Publish Time

hashtag
Overview

The GridStatus API provides sophisticated publish time filtering capabilities that allow you to control which data points are returned based on when they were published or reported. This is particularly useful for forecasting data, where multiple predictions may exist for the same operating time but were published at different times.

circle-info

Publish time filtering is only available for datasets that have a publish_time_column. You can identify these datasets by checking the dataset metadata - datasets with publish time capabilities will have a non-null publish_time_column field.

hashtag
Available Publish Time Parameters

hashtag
1. publish_time - Primary Filtering Parameter

The publish_time parameter is the main way to filter data based on publication timing. It supports several different modes:

1.1. latest_report - Most Recent Report

Returns only data from the most recently published report across the entire dataset.

Use Case: Get the very latest forecast or report available

Example:

curl "https://api.gridstatus.io/v1/datasets/ercot_load_forecast_by_forecast_zone/query?publish_time=latest_report&limit=5&api_key=YOUR_API_KEY"

1.2. latest - Latest for Each Time Index

For any given operating timestamp, returns the most recently published data point.

Use Case: Get the most up-to-date forecast for each operating hour

Dataset Requirement: Requires the dataset to have both a publish_time_column and time_index_column

Example:

Response: For each interval_start_utc timestamp, returns the record with the most recent publish_time_utc.

1.3. Specific Timestamp

Provide an ISO 8601 timestamp to get only data published at that exact time.

Use Case: Retrieve data from a specific forecast time

Example:

1.4. latest_before - Latest Before Cutoff

Returns the most recent forecast for each operating time where the publish time is before or equal to a calculated cutoff time relative to each operating time.

Formats:

Format
Description

latest_before

Shorthand for latest_before:-0 hours. Returns the latest forecast published at or before each operating time

latest_before:<offset>

e.g., latest_before:-6 hours. Retrieves forecasts published at least 6 hours before each operating time

latest_before:<offset>@<HH:MM:SS>

e.g., latest_before:-1 day@10:30:00. Retrieves forecasts published at or before 10:30 AM on the day before each operating time

Use Case: Get forecasts published at least X time before the operating time, useful for day-ahead vs real-time analysis

Examples:

Basic offset:

With specific time:

Logic:

  • For latest_before:-6 hours: publish_time ≤ operating_time - 6 hours

  • For latest_before:-1 day@10:30:00: publish_time ≤ 10:30:00 on (operating_time - 1 day)

1.5. window - Time Window

Returns all forecasts published within a specific time window relative to the operating time.

Formats:

Format
Description

window:<offset>

e.g., window:-6 hours. Returns all forecasts published in the 6 hours leading up to each operating time

window:<offset>@<HH:MM:SS>

e.g., window:-1 day@10:00:00. Returns all forecasts published from 10:00 AM the day before up to the operating time

Use Case: Analyze all forecasts published within a specific timeframe before the operating time

Example:

Logic: (operating_time + offset) ≤ publish_time ≤ operating_time

For window:-6 hours: (operating_time - 6 hours) ≤ publish_time ≤ operating_time

hashtag
2. publish_time_start - Start Range Filter

Filter data to include only records published on or after this timestamp.

  • Use Case: Get all data published since a specific date/time

  • Cannot be used with: publish_time parameter

  • Format: ISO 8601 datetime string

Example:

hashtag
3. publish_time_end - End Range Filter

Filter data to include only records published before this timestamp (exclusive).

  • Use Case: Get historical data published before a specific cutoff

  • Cannot be used with: publish_time parameter

  • Format: ISO 8601 datetime string

Example:

hashtag
4. Combined Range Filtering

You can use both publish_time_start and publish_time_end together to create a specific publication time window.

Example:

This returns all forecasts published between 6 AM and 6 PM on January 1st, 2024.

hashtag
Offset Format Specification

For latest_before and window parameters, the offset format follows these rules:

hashtag
Basic Offset Format

<amount> <unit> where:

  • amount: Number (can be negative, positive, or decimal)

  • unit: One of: seconds, minutes, hours, days, weeks, months, years

Examples:

  • -6 hours

  • 1.5 days

  • -30 minutes

  • 2 weeks

hashtag
Time-Specific Format

<offset>@<HH:MM:SS> where:

  • offset: Basic offset as above

  • @: Separator

  • HH:MM:SS: Specific time in 24-hour format

Examples:

  • -1 day@10:30:00 - 10:30 AM on the previous day

  • -2 days@14:15:30 - 2:15:30 PM two days prior

hashtag
URL Encoding

circle-exclamation

When using offsets in URLs, remember to URL-encode spaces:

  • -6 hours becomes -6%20hours

  • -1 day@10:30:00 becomes -1%20day@10:30:00

hashtag
Common Use Cases and Examples

hashtag
1. Day-Ahead vs Real-Time Forecast Analysis

Compare day-ahead forecasts (published ~24 hours before) with near-real-time forecasts:

Day-ahead forecasts:

Near real-time forecasts:

hashtag
2. Morning Forecast Analysis

Get forecasts published during morning hours (6 AM - 12 PM):

hashtag
3. Forecast Revision Analysis

Analyze how forecasts change over time by getting all forecasts in a 6-hour window before operating time:

hashtag
4. Historical Snapshot

Get the most recent data as it was available at a specific point in time:

hashtag
Response Format

All responses include the publish_time_utc column when available, allowing you to verify the publication timing:

hashtag
Error Handling and Validation

hashtag
Common Errors

Invalid Offset Format

Invalid Time Format

Dataset Without Publish Time

Conflicting Parameters

hashtag
Best Practices

hashtag
1. Check Dataset Compatibility

Before using publish time filtering, verify that the dataset has a publish_time_column:

Look for "publish_time_column": "publish_time_utc" in the response.

hashtag
2. Use Appropriate Time Zones

The API works in UTC. If you need to work with local time zones, consider the dataset's typical publication schedule and convert accordingly.

hashtag
3. Limit Result Sets

Publish time filtering can return large datasets. Always use limit parameters appropriately:

hashtag
4. Combine with Other Filters

Publish time filters work well with other parameters like start_time, end_time, and column filters:

hashtag
5. Performance Considerations

  • latest_report is typically the fastest option as it returns the smallest dataset

  • window operations can be slower for large time ranges

  • Consider using pagination for large result sets

hashtag
Timezone Handling

The API accepts a timezone parameter that affects how publish time calculations are performed:

When a timezone is specified:

  • The time calculations for @HH:MM:SS formats are performed in the specified timezone

  • The input timestamps are converted to the specified timezone before processing

  • Results are still returned in UTC

hashtag
Summary

The GridStatus API's publish time filtering provides powerful capabilities for:

  • Getting the latest available data (latest, latest_report)

  • Historical analysis (latest_before with timestamps)

  • Forecast revision tracking (window operations)

  • Time-based publication filtering (publish_time_start, publish_time_end)

These features enable sophisticated analysis of how forecasts evolve over time and allow users to recreate historical views of data as it was available at specific points in time.

PreviousResponse FormatNextQuery Parameters

Last updated

Was this helpful?